A Custom Sass Import Resolver with included support for Node Module Resolution, additional file extensions, and path aliases/path mapping

Description

This is an implementation of the Sass Import Resolve algorithm, with added support for Node Module Resolution, and path mapping/path aliasing.

At the moment, without this Custom importer, to import files via Node Module Resolution, Sass library creators and consumers can:

• Ship .scss, .sass, or .css files via node_modules, and let consumers depend on files directly, - but not support hoisted dependencies/monorepos.
• Use Eyeglass

One major use case for this library is to support path mapping, which can be useful for many things, includiong simplifying import paths or dividing packages in a monorepo.

This implementation follows the convention of existing tooling and similar solutions that paths with a leading ~ will be resolved via Node Module Resolution.

Features

Backers

Become a sponsor/backer and get your logo listed here.

Trent Raymond	scrubtheweb

Patreon

Table of Contents

• Description
  • Features
• Backers
  • Patreon
• Table of Contents
• Install
  • npm
  • Yarn
  • pnpm
• Usage
  • Usage with sass
  • Usage with node-sass
  • Resolving files within Node Modules
    • Customizing the prefix
  • Path mapping/aliasing
  • Adjusting allowed extensions
  • Customizing the file system
  • Usage with other tools and libraries
• Contributing
• Maintainers
• FAQ
• License

Install

npm

$ npm install sass-extended-importer --save-dev

Yarn

$ yarn add sass-extended-importer --dev

pnpm

$ pnpm add sass-extended-importer --save-dev

Usage

Usage with sass

To use it with the primary sass package (dart-sass), simply import the createImporter function from this package and invoke it with the options you want to provide. Then pass it to sass is an import resolver:

1import {createImporter} from "sass-extended-importer";
2import sass from "sass";
3
4sass({
5	file: "/path/to/your/file.scss",
6	importer: createImporter({
7		// options
8	})
9});

Usage with node-sass

To use it with node-sass, simply import the createImporter function from this package and invoke it with the options you want to provide. Then pass it to node-sass is an import resolver:

1import {createImporter} from "sass-extended-importer";
2import sass from "node-sass";
3
4sass({
5	file: "/path/to/your/file.scss",
6	importer: createImporter({
7		// options
8	})
9});

Resolving files within Node Modules

Prefix the path with a ~ to indicate that the Node Module Resolution algorithm should be used:

1@import "~my-library";

The resolve function will use Node Module Resolution to find the library, and then look at the main property within the related package.json file. If it points to a file, for example index.js, for which there is an identically named file with an extension of .scss, .sass , or .css, or if the main property directly points to a file with a supported extension, that file will be resolved. Alternatively, if the main property is left out, it will default to looking for a file called index with one of the supported extensions directly within the package folder.

This means that all of the following examples will work:

1// Uses the package.json file's main property to look for a file with a supported extension.
2// Defaults to looking for a file named `index` with a supported extension
3@import "~my-library";
4
5// Specifically looks for a file called 'index' inside the package folder, with a supported extension
6@import "~my-library/index";
7
8// Specifically looks for a file with the filename `index.scss`
9@import "~my-library/index.scss";
10
11// Looks inside the /foo folder from the package folder and for a file called `bar` with a supported extension
12// (or if bar is a folder, a file within it called `index` with a supported extension)
13@import "~my-library/foo/bar";

Customizing the prefix

The default prefix of ~ (tilde) is a convention used by several popular tools and is the general recommendation. However, you can customize it with the nodeModuleResolutionPrefix option for the importer:

1import {createImporter} from "sass-extended-importer";
2import sass from "sass";
3
4sass({
5	// ...
6	importer: createImporter({
7		// Use # instead of ~
8		nodeModuleResolutionPrefix: "#"
9	})
10});

Path mapping/aliasing

You can use path mapping to map import paths to other import paths. This can be useful to simplify import statements, or if you use sass/scss/css in combination with a build pipeline that performs path mapping on your other application- or library code. For example, you might be using TypeScript's path mapping feature, and want to make sure the same paths are supported inside the sass/scss/css files you're importing from there. You can customize it with the paths option for the importer:

1import {createImporter} from "sass-extended-importer";
2import sass from "sass";
3
4sass({
5	// ...
6	importer: createImporter({
7		paths: {
8			"my-alias": ["../other-folder/src/index.scss"],
9			"my-alias/*": ["../other-folder/src/*"]
10		}
11	})
12});

This allows you do write styles such as:

1@import "my-alias/foo";

Which will actually be mapped to ../other-folder/src/foo.scss.

Adjusting allowed extensions

You can alter what kind of extensions that can be resolved via the extensions option for the importer:

1import {createImporter} from "sass-extended-importer";
2import sass from "sass";
3
4sass({
5	// ...
6	importer: createImporter({
7		// Use # instead of ~
8		extensions: [".myextension", ".foo", ".bar"]
9	})
10});

Customizing the file system

If you use a virtual file system, such as one that exists within memory, you can pass it in as the fileSystem option for the importer. If you don't, it defaults to using the fs module:

1import {createImporter} from "sass-extended-importer";
2import sass from "sass";
3import path from "path";
4import {createFsFromVolume, Volume} from "memfs";
5
6const volume = new Volume();
7
8vol.mkdirSync("/my/directory", {recursive: true});
9vol.writeFileSync("/my/directory/foo.scss", "p {color: red}");
10const fileSystem = createFsFromVolume(vol);
11
12sass({
13	// ...
14	importer: createImporter({
15		// Use another file system
16		fileSystem
17	})
18});

Usage with other tools and libraries

The resolve algorithm implemented by this library is also exported as as helper function, resolve, that can be used outside of just as a Custom Importer for Sass. To use it directly, simply import resolve:

1import {resolve} from "sass-extended-importer";
2
3resolve("~my-library", {cwd: "/path/to/directory"});

Contributing

Do you want to contribute? Awesome! Please follow these recommendations.

Maintainers

Frederik Wessberg Twitter: @FredWessberg Github: @wessberg Lead Developer

FAQ

License

MIT © Frederik Wessberg (@FredWessberg) (Website)