node-sass-magic-importer

Custom node-sass importer for selector specific imports, module importing, globbing support and importing files only once.

Features

This importer enables several comfort functions for importing SASS files more easily.

• Selector filtering: import only specific selectors from a file.
  (Uses the node-sass-selector-importer module.)
• Module importing: import modules from node_modules without specifying the full path.
  (Uses the node-sass-package-importer module.)
• Globbing: use globbing (e.g. @import: 'scss/**/*.scss') to import multiple files at once.
  (Uses the node-sass-glob-importer module.)

By default every file is only imported once even if you @import the same file multiple times in your code.

Selector filtering

With selector filtering, it is possible to import only certain CSS selectors form a file. This is especially useful if you want to import only a few CSS classes from a huge library or framework.

// Example:
@import '{ .btn, .btn-alert } from style.scss';

// Result:
.btn { }
.btn-alert { }

Transform imported selectors

// Example:
@import '{ .btn as .button, .btn-alert as .button--alert } from style.scss';

// Result:
.button { }
.button--alert { } // Transformed to match BEM syntax.

RegEx

// Example:
@import '{ /^\..+-alert/ } from style.scss';

// Result:
.box-alert { }
.btn-alert { }

// Example:
@import '{ /^\.btn(.*)/ as .button$1 } from style.scss';

// Result:
.button { }
.button-alert { }

Usage with Bootstrap

Bootstrap is a mighty and robust framework but most of the time you use only certain parts of it. There is the possibility to customize Bootstrap to your needs but this can be annoying and you still end up with more code than you need. Also you might want to use just some specific parts of Bootstrap but your project uses the BEM syntax for writing class names.

// This example uses the v4 dev version of the Bootstrap `alert` component:
// https://github.com/twbs/bootstrap/blob/v4-dev/scss/_alert.scss
@import 'bootstrap/scss/variables';
@import 'bootstrap/scss/mixins/border-radius';
@import 'bootstrap/scss/mixins/alert';
@import '{
  .alert,
  .alert-dismissible as .alert--dismissible,
  .close as .alert__close
} from bootstrap/scss/alert';

// Result:
.alert {
  padding: 15px;
  margin-bottom: 1rem;
  border: 1px solid transparent;
  border-radius: 0.25rem;
}

.alert--dismissible {
  padding-right: 35px;
}

.alert--dismissible .alert__close {
  position: relative;
  top: -2px;
  right: -21px;
  color: inherit;
}

You may notice that source map support is limited for styles which are imported with selector filtering. If you have an idea how to fix this, please feel free to create a new issue or pull request.

Module importing

In modern day web development, modules and packages are everywhere. There is no way around npm if you are a JavaScript developer. More and more CSS and SASS projects move to npm but it can be annoying to find a convenient way of including them into your project. Module importing makes this a little easier.

// Import the file that is specified in the `package.json` file of the module.
// In the case of bootstrap, the following file is loaded:
// https://github.com/twbs/bootstrap/blob/v4-dev/scss/bootstrap.scss
@import '~bootstrap';

// Import only specific files:
@import '~bootstrap/scss/variables';
@import '~bootstrap/scss/mixins/border-radius';
@import '~bootstrap/scss/mixins/alert';
@import '~bootstrap/scss/alert';

The "~" is mandatory and marks the import path as module.

Path resolving

If only the module name is given (e.g. @import '~bootstrap') the importer looks in the package.json file of the module for the following keys: "sass", "scss", "style", "css", "main.sass", "main.scss", "main.style", "main.css" and "main". The first key that is found is used for resolving the path and importing the file into your sass code.

To load only a certain file from a module you can specify the file in the import url (e.g. @import '~bootstrap/scss/_alert.scss'). The node-sass-magic-importer also supports partial file name resolving so you can import files by only specifying their base name without prefix and extension (e.g. @import '~bootstrap/scss/alert'). Sadly bootstrap and most other frameworks do not load their dependencies directly in the concerned files. So you have to load all dependencies of a file manually like in the example above. I recommend you to do better and to import dependencies directly in the files that are using them.

Globbing

Globbing allows pattern matching operators to be used to match multiple files at once.

// Import all files inside the `scss` directory and subdirectories.
@import: 'scss/**/*.scss';

Usage

var sass = require('node-sass');
var magicImporter = require('node-sass-magic-importer');

sass.render({
  ...
  importer: magicImporter()
  ...
});

Options

var sass = require('node-sass');
var magicImporter = require('node-sass-magic-importer');

var options = {
  // Defines the path in which your node_modules directory is found.
  cwd: process.cwd(),
  // Paths in which to search for imported files.
  includePaths: [process.cwd()],
  // Allowed extensions.
  extensions: [
    '.scss',
    '.sass'
  ],
  // Define the package.json keys and in which order to search for them.
  packageKeys: [
    'sass',
    'scss',
    'style',
    'css',
    'main.sass',
    'main.scss',
    'main.style',
    'main.css',
    'main'
  ]
};

sass.render({
  ...
  importer: magicImporter(options)
  ...
});

CLI

node-sass --importer node_modules/node-sass-magic-importer/dist/cli.js -o dist src/index.scss

Upgrade to 2.x.x from 1.x.x

Version 2.x.x does not return a node-sass custom importer function directly. Instead a function which can take a optional parameter for configuration is returned. When the function is executed, it returns a node-sass custom importer function.

If you want to use the node-sass-magic-importer in combination with the node-sass CLI, you now have to specify the path to the node-sass-magic-importer CLI script.

sass.render({
  ...
  // Old
  importer: magicImporter,
  magicImporter: {
    cwd: process.cwd()
  }
  // New
  importer: magicImporter({
    cwd: process.cwd()
  })
  ...
});

# Old
node-sass --importer node_modules/node-sass-magic-importer -o dist src/index.scss
# New
node-sass --importer node_modules/node-sass-magic-importer/dist/cli.js -o dist src/index.scss

About

Author

Markus Oberlehner
Twitter: https://twitter.com/MaOberlehner
PayPal.me: https://paypal.me/maoberlehner

License

MIT