Node Sass Tilde Importer

1.0.2 · abandoned · verified Sun Apr 19

node-sass-tilde-importer is a custom importer for node-sass that enabled the resolution of Sass `@import` statements beginning with a tilde (~) to absolute paths within the nearest `node_modules` directory. This functionality was essential for integrating npm-installed Sass libraries (e.g., Bootstrap's SCSS files) into projects built with `node-sass` and bundlers like Webpack (via `sass-loader`). The package's current stable version is 1.0.2, last published in March 2018. It has no discernible release cadence, indicating it is no longer actively maintained. Its primary differentiator was providing `~` path resolution for `node-sass`, a feature now largely superseded or natively handled by modern Sass compilers (Dart Sass, available as the `sass` npm package) and contemporary bundler loaders (e.g., `sass-loader` v8+). Given the end-of-life status and deprecation of `node-sass` itself, this package is considered obsolete for new projects and for migrations to modern Sass environments.

Common errors

```
Error: 'node-sass' usage is deprecated and will be removed in a future major version.
```
cause Your project is still using `node-sass` or a dependency that pulls in `node-sass`, which is now deprecated.

fix Uninstall `node-sass` and replace it with `sass` (Dart Sass). If using a build tool like Webpack, ensure `sass-loader` is configured to use `sass` as its `implementation`.
```
SassError: Can't find stylesheet to import: ~your-package/path
```
cause This error can occur if you've migrated to Dart Sass or a newer `sass-loader` version, but `node-sass-tilde-importer` is either still present and causing conflicts, or has been removed without correctly configuring the new Sass environment for `~` path resolution.

fix If using `sass-loader` with Dart Sass, remove `node-sass-tilde-importer`. `sass-loader` should handle `~` prefixes to `node_modules` automatically. If issues persist, configure `sassOptions.includePaths` in your `sass-loader` options to explicitly include `node_modules`.

Warnings

breaking The underlying `node-sass` package, which this importer relies on, is officially deprecated and in end-of-life status. It is no longer actively maintained and has known compatibility issues with newer Node.js versions. You should migrate to Dart Sass (`sass` npm package).
Fix: Migrate your Sass compilation pipeline from `node-sass` to `sass` (Dart Sass). This package will become obsolete in a Dart Sass environment.
gotcha Dart Sass (the modern `sass` compiler) and modern `sass-loader` versions often handle `~` (tilde) imports to `node_modules` either natively (via `loadPaths` or direct resolution) or through Webpack's resolver, rendering this custom importer unnecessary. Using this package with Dart Sass is typically not required and may cause issues.
Fix: Remove `node-sass-tilde-importer`. Configure `sass-loader` to use `implementation: require('sass')` and rely on its built-in Webpack resolution for `~` imports, or explicitly set `sassOptions.includePaths` to include `node_modules`.
deprecated This `node-sass-tilde-importer` package itself is unmaintained, with its last publish being 8 years ago (March 2018). It is unlikely to receive updates for new Sass features or compatibility fixes with newer Node.js environments.
Fix: Avoid using this package in new projects. For existing projects, prioritize migrating to Dart Sass and removing this dependency.
deprecated The `@import` rule, which this importer modifies, is deprecated in Dart Sass 1.80.0 and will be removed in Dart Sass 3.0.0. The modern Sass module system encourages the use of `@use` and `@forward` rules instead.
Fix: As part of migrating to Dart Sass, update your Sass stylesheets to use the `@use` and `@forward` syntax instead of `@import`.

Install

npm install node-sass-tilde-importer npm
yarn add node-sass-tilde-importer yarn
pnpm add node-sass-tilde-importer pnpm

Imports

tildeImporter

wrong:

import tildeImporter from 'node-sass-tilde-importer';

correct:

const tildeImporter = require('node-sass-tilde-importer');

This package is a CommonJS module and must be imported using `require()`.

Quickstart

Demonstrates how to use node-sass-tilde-importer with the deprecated `node-sass` compiler to resolve tilde imports.

const sass = require('node-sass');
const tildeImporter = require('node-sass-tilde-importer');

const scssContent = `
  // Example of importing a node_module like Bootstrap
  @import "~bootstrap/scss/functions";
  @import "~bootstrap/scss/variables";
  @import "~bootstrap/scss/mixins";
  
  .my-component {
    color: $blue;
    padding: map-get($spacers, 3);
  }
`;

sass.render({
  data: scssContent,
  importer: tildeImporter,
  outputStyle: 'expanded'
}, function(error, result) {
  if (error) {
    console.error(`Sass compilation error: ${error.message} on line ${error.line} in ${error.file}`);
  } else {
    console.log('Compiled CSS:\n', result.css.toString());
  }
});

view raw JSON →