@squirrel-forge/sass-package-importer

A simple node sass package importer built for the new sass js api must be used with the new sass package. Made to be compatible with node ^10.0.0, might work on higher versions, but currently not supported or tested.

---

Please note that if you are looking for a more versatile implementation, especially if you are looking for the old node-sass api or the sass legacy api, check out the node-sass-package-importer.

Installation

npm i @squirrel-forge/sass-package-importer

Usage

Use ~ to prefix packages that should be imported or used and they will be resolved according to your options, the default options will attempt to load from the node_modules directory inside your cwd or you may set/add your own paths that should be used to resolve packages.

Source scss

1@import "~@squirrel-forge/sass-util";
2
3// OR
4@use "~@squirrel-forge/sass-util";

It will also allow nested package paths if you wish to import or use a file nested inside a package and not import the complete package as following:

1@import "~@squirrel-forge/sass-util/src/mixins/index";
2
3// OR
4@use "~@squirrel-forge/sass-util/src/mixins/index";

Plugin usage:

1const sass = require( 'sass' );
2const packageImporter = require( '@squirrel-forge/sass-package-importer' );
3
4// Classic way, calling the factory in place with options
5const sassOptions = { importers : [ packageImporter( /* null|PackageImporterOptions */ ) ] };
6
7// Plugin way, supply the sass options as second argument
8// It will create the importers property if required and append the importer.
9const sassOptions = {};
10packageImporter( /* null|PackageImporterOptions */, sassOptions );
11
12// Since the importer is sync it work for both sync and async compile
13const result = sass.compile( scssFilename, sassOptions );
14
15// OR
16const result = await sass.compileAsync( scssFilename, sassOptions );

Options

1/**
2 * Package importer options
3 * @type {null|PackageImporterOptions}
4 */
5const PACKAGE_IMPORTER_DEFAULT_OPTIONS = {
6    strict : false,
7    cwd : null,
8    prefix : '~',
9    ext : [ '.scss', '.sass', '.css' ],
10    keys : [ 'scss', 'sass', 'style', 'css', 'main.scss', 'main.sass', 'main.style', 'main.css', 'main' ],
11    paths : [ 'node_modules' ],
12};
13
14/**
15 * @typedef {Object} PackageImporterOptions
16 * @property {boolean} strict - Require a package directory and a package.json if there is no module target info, default: false
17 * @property {null|string} cwd - Set the working directory for the importer, default: null > process.cwd()
18 * @property {string} prefix - Package import prefix, default: ~
19 * @property {Array<string>} ext - Array of acceptable extensions, defaults: see PACKAGE_IMPORTER_DEFAULT_OPTIONS.ext
20 * @property {Array<string>} keys - Array of possible package keys to check for a file reference, defaults: see PACKAGE_IMPORTER_DEFAULT_OPTIONS.keys
21 * @property {Array<string>} paths - Array of possible package locations, relative or absolute paths, defaults see PACKAGE_IMPORTER_DEFAULT_OPTIONS.paths
22 */

Issues

If you encounter any issues, please report here.

---

Check the sourcecode on github for extensive comments.