@onenexus/synergy-sass-importer NPM

Import JavaScript/JSON files into Sass

Overview

Synergy-Sass-Importer allows you to import JavaScript/JSON/json5 files into your Sass files. It was built for the Cell library (which in turn was built for the Synergy framework) but can be used with any projects that use Node.js and Sass.

Usecases

Share UI component configuration between Sass/JavaScript
Theming (import JavaScript themes into your Sass)
...expose theme to UI component configuration
Import any JavaScript/JSON data into Sass for any reason

Installation & Setup

npm install --save-dev @onenexus/synergy-sass-importer

node-sass

This module hooks into node-sass's importer api.

var sass = require('node-sass');
var SynergySassImporter = require('@onenexus/synergy-sass-importer');

// Example 1
sass.render({
  file: scss_filename,
  importer: SynergySassImporter,
  ...options
}, function(err, result) {
  ...
});

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

node-sass command-line interface

To run this using node-sass CLI, point --importer to your installed json importer, for example:

node-sass /PATH/TO/app.scss --importer node_modules/synergy-sass-importer/dist/synergy-sass-importer.js

Webpack / sass-loader

ES6 Imports

import SassJSONImporter from '@onenexus/sass-json-importer';

CommonJS

const SassJSONImporter = require('@onenexus/sass-json-importer');

Configuration

{
  test: /\.scss$/,
  use: [
    {
      loader: 'sass-loader', 
      options: {
        importer: SynergySassImporter
      }
    }
  ]
}

Usage

Once your Sass compiler has been setup to use Synergy-Sass-Importer, you can begin to import JavaScript/JSON files in your .scss files. Any of the following are valid imports into .scss files:

Any valid .json/.json5 file
Any .js file that exports an object
Any .js file that exports a function which returns an object

The resultant object of the import (if a function is imported it will be evaluated) will be converted to a Sass map and exposed to your Sass under a variable named after the name of the file that was imported.

Example

components/myComponent/config.json

{
  "someProperty": "someValue",
  "anotherProp": 20
}

components/myComponent/styles.scss

 // `$config` is now defined (because the file is called 'config.json');
 // if the file were called 'data.json', `$data` would instead be defined
@import 'config.json';

.myComponent {
  display: block;
  font-size: map-get($config, 'anotherProp');
}

Themes

There are several uses for themes:

Share common properties between UI components
Change entire project look and feel on the fly by switching themes

Themes can be imported like other files:

For Synergy-Sass-Importer to know that an imported file is intended to be a theme, it must either be called theme.{js|json} or have a direct parent/grand-parent directory called themes

themes/myTheme.json

{
  "colors": {
    "primary": "#009dff",
    "secondary": "#ff004c"
  }
}

components/myComponent/styles.scss

 // `$theme` is now defined
@import '../../themes/myTheme.json';

.myComponent {
  display: block;
  color: map-get-deep($theme, 'colors', 'primary');
}

Consider the case where we want to access the theme values from within the earleir config.json file. One approach would be to convert it to a .js file and manually import the theme like so:

components/myComponent/config.js

import theme from '../../themes/myTheme.json';

export default {
  'someProperty': theme.colors.primary,
  'anotherProp': 20
}

An alternative approach is to convert the configuration to a function that accepts a theme argument:

components/myComponent/config.js

export default (theme) => ({
  'someProperty': theme.colors.primary,
  'anotherProp': 20
});

The theme (provided it has been correctly imported into your Sass) will automatically be passed to the function which will be evaluated, and the returned object will be converted to a Sass map.

components/myComponent/styles.scss

@import 'config.js';

.myComponent {
  display: block;
  color: map-get($config, 'someProperty'); // #009dff
}

app.scss

@import 'themes/myTheme.json';
@import 'components/myComponent.scss';

Passing Theme To Sass Through Node.js

Rather than importing the theme into your Sass manually, you can expose it to Node.js where it will be picked up by Synergy-Sass-Importer and automatically passed to Sass - learn more.