Node-Sass JSON Importer

Common errors

• Error: 'A sentence with spaces.' is not a valid Sass string.

  cause A JSON string containing spaces or special characters was not correctly escaped with inner single quotes, leading Sass to misinterpret it.
  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'"`.

• TypeError: jsonImporter is not a function

  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.
  fix Ensure you invoke the importer factory function: use `importer: jsonImporter()` instead of `importer: jsonImporter`.

• Module not found: Can't resolve 'node-sass-json-importer'

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• deprecated 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.
  Fix: Upgrade to version 4.1.2 or later to ensure stability and correct behavior.
• gotcha 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.
  Fix: Change `importer: jsonImporter` to `importer: jsonImporter()` in your configuration.

Install

• npm install node-sass-json-importer npm
• yarn add node-sass-json-importer yarn
• pnpm add node-sass-json-importer pnpm

Imports

• jsonImporter
  wrong:

  import jsonImporter from 'node-sass-json-importer';

  correct:

  const jsonImporter = require('node-sass-json-importer');

  This is the standard CommonJS import for Node.js environments and older Webpack configurations (v1-v2) where `require` is used.
• jsonImporter
  wrong:

  const jsonImporter = require('node-sass-json-importer').default;

  correct:

  import jsonImporter from 'node-sass-json-importer';

  Used in ESM contexts, typically for modern Webpack configurations (v2+) or environments supporting ES modules natively. The package exports a default function.
• cli.js

  ./node_modules/.bin/node-sass --importer node_modules/node-sass-json-importer/dist/cli.js --recursive ./src --output ./dist

  This is how the importer is specified when using the `node-sass` command-line interface directly, rather than a programmatic import statement.

Quickstart

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.

const sass = require('node-sass');
const jsonImporter = require('node-sass-json-importer');
const path = require('path');
const fs = require('fs');

const scssContent = `@import 'colors.json'; body { color: $primary-color; }`;
const jsonContent = `{ "primary-color": "red" }`;

// Create a dummy JSON file for the import
const jsonFilePath = path.join(__dirname, 'colors.json');
fs.writeFileSync(jsonFilePath, jsonContent);

sass.render({
  data: scssContent,
  importer: jsonImporter(), // Important: call jsonImporter() to get the function
}, function(err, result) {
  if (err) {
    console.error('Async compilation error:', err);
  } else {
    console.log('Compiled CSS (Async):\n', result.css.toString());
  }
  fs.unlinkSync(jsonFilePath); // Clean up
});

console.log('\n--- Synchronous compilation example ---\n');

const scssConfigContent = `@import 'config.json'; .my-element { font-size: $base-font-size; }`;
const jsonConfigContent = `{ "base-font-size": "16px" }`;
const jsonConfigPath = path.join(__dirname, 'config.json');
fs.writeFileSync(jsonConfigPath, jsonConfigContent);

try {
  const resultSync = sass.renderSync({
    data: scssConfigContent,
    importer: [jsonImporter()], // Can be an array of importers
  });
  console.log('Compiled CSS (Sync):\n', resultSync.css.toString());
} catch (e) {
  console.error('Sync compilation error:', e);
} finally {
  fs.unlinkSync(jsonConfigPath); // Clean up
}