{"id":14755,"library":"node-sass-json-importer","title":"Node-Sass JSON Importer","description":"node-sass-json-importer provides a mechanism to import JSON and JSON5 files directly into Sass stylesheets when processed by `node-sass`. It allows `@import` rules in Sass to resolve to `.json` or `.json5` files, making it possible to define design tokens, configuration variables, or other data structures in JSON and consume them directly within Sass. The package's last stable version was 4.3.0, released in May 2020. Given its fundamental dependency on the deprecated `node-sass` library, active development has ceased, and new releases are not expected. Its primary differentiator was bridging the gap between JSON data sources and Sass compilation workflows using `node-sass`, offering features like case conversion and custom path resolution, but it is not compatible with modern `sass` (Dart Sass) setups.","status":"abandoned","version":"4.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/Updater/node-sass-json-importer","tags":["javascript","sass","node-sass","importer","json"],"install":[{"cmd":"npm install node-sass-json-importer","lang":"bash","label":"npm"},{"cmd":"yarn add node-sass-json-importer","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-sass-json-importer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency providing the Sass compilation and importer API.","package":"node-sass","optional":false}],"imports":[{"note":"This is the standard CommonJS import for Node.js environments and older Webpack configurations (v1-v2) where `require` is used.","wrong":"import jsonImporter from 'node-sass-json-importer';","symbol":"jsonImporter","correct":"const jsonImporter = require('node-sass-json-importer');"},{"note":"Used in ESM contexts, typically for modern Webpack configurations (v2+) or environments supporting ES modules natively. The package exports a default function.","wrong":"const jsonImporter = require('node-sass-json-importer').default;","symbol":"jsonImporter","correct":"import jsonImporter from 'node-sass-json-importer';"},{"note":"This is how the importer is specified when using the `node-sass` command-line interface directly, rather than a programmatic import statement.","symbol":"cli.js","correct":"./node_modules/.bin/node-sass --importer node_modules/node-sass-json-importer/dist/cli.js --recursive ./src --output ./dist"}],"quickstart":{"code":"const sass = require('node-sass');\nconst jsonImporter = require('node-sass-json-importer');\nconst path = require('path');\nconst fs = require('fs');\n\nconst scssContent = `@import 'colors.json'; body { color: $primary-color; }`;\nconst jsonContent = `{ \"primary-color\": \"red\" }`;\n\n// Create a dummy JSON file for the import\nconst jsonFilePath = path.join(__dirname, 'colors.json');\nfs.writeFileSync(jsonFilePath, jsonContent);\n\nsass.render({\n  data: scssContent,\n  importer: jsonImporter(), // Important: call jsonImporter() to get the function\n}, function(err, result) {\n  if (err) {\n    console.error('Async compilation error:', err);\n  } else {\n    console.log('Compiled CSS (Async):\\n', result.css.toString());\n  }\n  fs.unlinkSync(jsonFilePath); // Clean up\n});\n\nconsole.log('\\n--- Synchronous compilation example ---\\n');\n\nconst scssConfigContent = `@import 'config.json'; .my-element { font-size: $base-font-size; }`;\nconst jsonConfigContent = `{ \"base-font-size\": \"16px\" }`;\nconst jsonConfigPath = path.join(__dirname, 'config.json');\nfs.writeFileSync(jsonConfigPath, jsonConfigContent);\n\ntry {\n  const resultSync = sass.renderSync({\n    data: scssConfigContent,\n    importer: [jsonImporter()], // Can be an array of importers\n  });\n  console.log('Compiled CSS (Sync):\\n', resultSync.css.toString());\n} catch (e) {\n  console.error('Sync compilation error:', e);\n} finally {\n  fs.unlinkSync(jsonConfigPath); // Clean up\n}","lang":"javascript","description":"This quickstart demonstrates how to integrate `node-sass-json-importer` with `node-sass` to process `.json` files within Sass, showing both asynchronous and synchronous `render` methods."},"warnings":[{"fix":"Migrate your project from `node-sass` to `sass` (Dart Sass). You will need to find an alternative JSON importer compatible with Dart Sass, such as `sass-json-vars` or implement a custom importer for Dart Sass.","message":"The underlying `node-sass` library, which this package depends on, is deprecated and no longer actively maintained. `node-sass-json-importer` is built specifically for `node-sass` and is not compatible with modern `sass` (Dart Sass) compilers.","severity":"breaking","affected_versions":"all"},{"fix":"Ensure JSON values are formatted like `\"description\": \"'A sentence with spaces.'\"` instead of `\"description\": \"A sentence with spaces.\"`. This allows Sass to process the inner single-quoted string as a literal Sass string.","message":"JSON string values that contain spaces, commas, or other special characters must be wrapped in *single quotes* within the *double-quoted JSON string itself* for Sass to interpret them correctly as unquoted Sass strings. Otherwise, Sass may throw parsing errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade to version 4.1.2 or later to ensure stability and correct behavior.","message":"Version 4.1.1 was officially marked as a 'Bad release' by the maintainers and should be avoided due to an issue with dependency handling.","severity":"deprecated","affected_versions":"4.1.1"},{"fix":"Change `importer: jsonImporter` to `importer: jsonImporter()` in your configuration.","message":"The `node-sass-json-importer` package exports a function that returns the actual importer function. Therefore, it must always be *called* (e.g., `jsonImporter()`) when passed to `node-sass`'s or `sass-loader`'s `importer` option.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"In your JSON file, ensure that values intended to be unquoted Sass strings containing special characters are wrapped in single quotes, e.g., change `\"key\": \"A value with spaces\"` to `\"key\": \"'A value with spaces'\"`.","cause":"A JSON string containing spaces or special characters was not correctly escaped with inner single quotes, leading Sass to misinterpret it.","error":"Error: 'A sentence with spaces.' is not a valid Sass string."},{"fix":"Ensure you invoke the importer factory function: use `importer: jsonImporter()` instead of `importer: jsonImporter`.","cause":"The imported `jsonImporter` variable, which is a factory function, was passed directly to the `importer` option without being called to produce the actual importer.","error":"TypeError: jsonImporter is not a function"},{"fix":"First, run `npm install node-sass-json-importer` or `yarn add node-sass-json-importer`. Then, verify that the import statement or path in your `sass-loader` or `node-sass` configuration correctly points to the installed package.","cause":"The package `node-sass-json-importer` is either not installed in your project, or the import path in a Webpack/bundler configuration is incorrect.","error":"Module not found: Can't resolve 'node-sass-json-importer'"}],"ecosystem":"npm"}