node-sass-js-importer

JavaScript data importer for sass (originally for the now deprecated node-sass, hence the package name).

This allows @importing/@useing .js/.mjs/.cjs files in Sass files parsed by sass.

This is a fork of the node-sass-json-importer repository, adjusted for usage with JavaScript files.

Setup

sass

This module hooks into sass' importer api.

const sass = require('sass')
const { jsImporter } = require('node-sass-js-importer')

// Example 1
sass.render({
  file: scss_filename,
  importer: jsImporter,
  // ...options
}, (err, result) => { /*...*/ })

// Example 2
const result = sass.renderSync({
  data: scss_content
  importer: [jsImporter, someOtherImporter]
  // ...options
})

Webpack / sass-loader

Webpack v1

import { jsImporter } from 'node-sass-js-importer'

// Webpack config
export default {
  module: {
    loaders: [
      {
        test: /\.scss$/,
        loaders: ['style', 'css', 'sass']
      }
    ]
  },
  // Apply the JS importer via sass-loader's options.
  sassLoader: {
    importer: jsImporter
  }
}

Webpack v2 and upwards

import { jsImporter } from 'node-sass-js-importer'

// Webpack config
export default {
  module: {
    rules: [
      test: /\.scss$/,
      use: [
        'style-loader',
        {
          loader: 'css-loader',
          options: {
            importLoaders: 1
          },
        },
        {
          loader: 'sass-loader',
          // Apply the JS importer via sass-loader's options.
          options: {
            importer: jsImporter,
          },
        },
      ],
    ],
  },
}

Usage

Given the following colors.mjs file:

export default {
  primary: 'blue',
  secondary: 'red'
}

The importer allows your Sass file in the same folder to do this:

@import 'colors.mjs';

.some-class {
  background: $primary;
}

Note that @import is somewhat deprecated and you should use @use instead:

@use 'colors.mjs';

.some-class {
  // Data is automatically namespaced:
  background: colors.$primary;
}

To achieve the same behavior as with @import, you can change the namespace to *:

@use 'colors.mjs' as *;

.some-class {
  // Colors are no longer namespaced:
  background: $primary;
}

Importing strings

As JavaScript values don't map directly to Sass's data types, a common source of confusion is how to handle strings. While Sass allows strings to be both quoted and unqouted, strings containing spaces, commas and/or other special characters have to be wrapped in quotes.

The importer will automatically add quotes around all strings that are not valid unquoted strings or hex colors (and that are not already quoted, of course):

Input | Output | Explanation -|-|- { color: 'red' } | $color: red; | Valid unquoted string { color: '#f00' } | $color: #f00; | Valid hex color { color: "'red'" } | $color: "red"; | Explicitly quoted string { color: "really red" } | $color: "really red"; | Valid unquoted string

Module Formats

The importer supports both CommonJS and ES modules through explicit file extensions (.cjs, .mjs). If you're using a .js extension, the importer will use the same default as the node runtime does (i.e. depending on your package.json's module field).

Map Keys

Map keys are always quoted by the importer:

// colors.mjs
export default {
  colors: {
    red: '#f00'
  }
}

@use 'colors.mjs' as *;

:root {
  // This does not work:
  color: map-get($colors, red);

  // Do this instead:
  color: map-get($colors, 'red');
}

Credit

The initial implementation of this importer was based on the node-sass-json-importer package.