Custom node-sass importer for selector specific imports, node importing, module importing, globbing support and importing files only once.
npm install node-sass-magic-importer --save-dev
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.)
- Node filtering: import only specific nodes from a file.
(Uses the node-sass-filter-importer module.)
- Module importing: import modules from
node_moduleswithout 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 (except if you are using filters).
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.
Transform imported selectors
// Result:.button.button--alert // Transformed to match BEM syntax.
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://;;;;
// Result:.alert.alert--dismissible.alert--dismissible .alert__close
Filter certain elements from SCSS code.
// style.scss:;;.selector// Result:;;
- silent: Extract only nodes that do not compile to CSS code (mixins, placeholder selectors, variables,...)
- make-your-own: Define custom filters
// Import the file that is specified in the `package.json` file of the module.// In the case of bootstrap, the following file is loaded://;
// Import only specific files:;;;;
The "~" is mandatory and marks the import path as module.
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 allows pattern matching operators to be used to match multiple files at once.
// Import all files inside the `scss` directory and subdirectories.;
var sass = ;var magicImporter = ;sass;
const sass = ;const magicImporter = ;const options =// Defines the path in which your node_modules directory is found.cwd: process// 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'// You can set the special character for indicating a module resolution.packagePrefix: '~'// Disable console warnings.disableWarnings: false// Disable importing files only once.disableImportOnce: false// Add custom node filters.customFilters: undefined;sass;
const sass = ;const magicImporter = ;const options =customFilters:// Add a node filter for a specific min-width media query.customMediaWidth:property: 'type' value: 'atrule'property: 'name' value: 'media'property: 'params' value:'(min-width: 42em)'// Add a node filter for print media queries.customMediaPrint:property: 'type' value: 'atrule'property: 'name' value: 'media'property: 'params' value: 'print';sass;
// Sass file which implements filter importing.;
// CSS output – the `min-width: 43em` media query gets not imported.
// webpack.config.jsconst magicImporter = ;const ExtractTextPlugin = ;moduleexports =module:rules:test: /\.scss$/use: ExtractTextPluginplugins:filename: 'style.css'
const gulp = ;const sass = ;const magicImporter = ;gulp;
node-sass --importer node_modules/node-sass-magic-importer/dist/cli.js -o dist src/index.scss
Upgrade from 4.x.x to 5.x.x
- It is not possible anymore to set the
includePathsoption when initializing the importer. Use the node-sass includePaths option instead.
prefixoption was renamed to
Multi level filtering
Node filtering and selector filtering goes only one level deep. This means, if you're importing a file with selector or node filtering which is importing other files, those files are not filtered but imported as is. On a technical level, there is no good solution for this problem. One possibility would be to just pass the filters to all imports in the line but this carries the risk of filtering selectors or nodes on which one of the imported files might depend and therefore break the import. I might add this as an optional feature (which can be activated on demand) in the future – let me know if you're interested in multi level filter imports.