Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Sass cannot find a stylesheet imported with a leading ~

ErrorFile to import not found or unreadable: ~bootstrap/scss/bootstrap

Short answer

The ~ prefix is not part of Sass. It is a convention of the webpack sass-loader, so a Sass compiler run directly has no idea what ~bootstrap means. Compile through sass-loader, or drop the ~ and give Sass a load path or the Node package importer so it can look inside node_modules.

  • Applies to Dart Sass 1.7x or newer, sass-loader, webpack 5, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out who compiles the file. If it is webpack with sass-loader in the rules, go to the first cause; if it is a sass command or a Node script calling Sass, go to the second.

    grep -n "sass-loader" webpack.config.js package.json
    grep -n "sass" package.json
  2. 2Match what you see, then jump to its fix

    1. 1The failing import starts with ~ and the build goes through the sass CLI, a Node script or an Express middlewareSass runs without webpack, so nobody resolves the ~Fix
    2. 2The project uses sass-loader but ~ imports still failThe webpack importer is switched off, or the ~ is used the old wayFix
    3. 3A Node script calls Sass and the import is not foundA load path would fix it but is not set in the JavaScript APIFix

What does the error look like?

  • File to import not found or unreadable: ~bootstrap/scss/bootstrap

Cause 1 of 3

Sass runs without webpack, so nobody resolves the ~

1Check

Sass resolves imports relative to the current file first and then through load paths. A ~ is only understood by the importer sass-loader adds on top. Without it, ~bootstrap is just a path that does not exist.

npx sass --version

2Fix

Remove the ~ and let Sass find the package. On the command line add node_modules as a load path, or turn on the Node package importer (Dart Sass 1.71.0 and later) and use a pkg: URL.

# load path on the CLI
npx sass --load-path=node_modules style.scss style.css

// style.scss with the Node package importer
@use "pkg:bootstrap";

# CLI flag that enables the pkg: importer
npx sass --pkg-importer=node style.scss style.css

3Verify

Run the compile command again. The stylesheet should be written without the import error.

npx sass --pkg-importer=node style.scss style.css

Confirmed by sass-lang.com

Did this fix it?

Cause 2 of 3

The webpack importer is switched off, or the ~ is used the old way

1Check

sass-loader passes every @use, @import and @forward request to webpack's resolver, which is what makes ~ work. Setting webpackImporter to false removes that. The docs also call the ~ deprecated and say it can be removed, because the loader tries a relative path first and then node_modules.

grep -n "webpackImporter" webpack.config.js

2Fix

Remove webpackImporter: false (or supply your own importer), and write the import without the ~. Do not write ~/ because that means the home directory.

// before
@use "~bootstrap";
// after
@use "bootstrap";

3Verify

Restart the webpack build and check that the stylesheet compiles.

npx webpack --mode development

Confirmed by webpack.js.org

Did this fix it?

Cause 3 of 3

A load path would fix it but is not set in the JavaScript API

1Check

Sass looks through importers first and then loadPaths. A stylesheet is never searched in node_modules unless you add one of them.

grep -rn "loadPaths\|importers" build scripts 2>/dev/null

2Fix

Pass loadPaths for plain directories, or add the Node package importer and import with pkg:.

const sass = require('sass');

const result = sass.compile('style.scss', {
  importers: [new sass.NodePackageImporter()],
});

3Verify

Run the script and confirm the output CSS contains Bootstrap rules.

node build-css.js

Confirmed by sass-lang.com

Did this fix it?

How do I stop it coming back?

  • Write package imports without ~; the loader no longer needs it.
  • Decide once how node_modules is found (load path or pkg: importer) and keep it in one build file.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

npm install node-sass fails on a current Node.js version

node-sass fails to install on a recent Node.js version

node-sass is end-of-life and its newest release supports Node.js up to 20, so on newer Node.js the install falls back to a source build that fails.

3 causes, each with a fix

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.