Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4133 pages

Upgrades and deprecations

Node Sass Is Deprecated: Moving to Dart Sass Without Surprises

In short

With Node Sass deprecated and its repository archived since July 2024, no release will arrive for a newer Node.js line or for a security bug. The way out is a package swap to `sass` or `sass-embedded`, followed by two slower jobs: leaving the legacy `render()` API before Dart Sass 2.0.0 and leaving `@import` before 3.0.0.

Node Sass deprecated: what did the Sass team actually announce?

Two separate posts on sass-lang.com matter here. On 26 October 2020 the team deprecated LibSass, the C++ engine inside node-sass: no new features and no new CSS support, with best-effort fixes for major bugs and security problems only. That post told new projects to use Dart Sass instead.

The second post, dated 24 July 2024, retired Node Sass itself. It says the npm package is marked deprecated and the GitHub repository is archived, because the package had not shipped in about a year and a half and its maintainers no longer had time for it.

LibSass is still described as deprecated rather than end of life, since its maintainer makes occasional fixes. The same post adds that there is no longer an officially supported way to call LibSass from Node.js, and the node-sass README now warns that no further releases will come, security fixes included.

Checked against: source 1, source 2, source 3

Which Node.js versions did the last node-sass release cover?

The registry lists 9.0.0 as the latest version, published on 20 May 2023, with engines set to Node 16 or newer. Its deprecation message reads: "Node Sass is no longer supported. Please use sass or sass-embedded instead."

The README's support table stops at Node 20, which needs node-sass 9.0 or later. No row exists for 22, 24 or anything newer, and the README says binaries are not built for unsupported Node lines. A native install on a newer runtime is therefore outside anything the project promised.

If the symptom that brought you here is a failing install, the error-specific pages cover it: install fails on a current Node.js, npm stops with Command failed and the build cannot load node-sass.

Checked against: source 3, source 4

Should the replacement be sass or sass-embedded?

Both come from the same Dart Sass code and expose the same JavaScript API. The Sass docs describe sass as pure JavaScript, and sass-embedded as a wrapper around a native Dart executable that is generally faster. The trade is speed against platform reach.

Tooling leans toward the embedded build when it is present. Vite's options page says it uses sass-embedded if installed and falls back to sass, and recommends the embedded package for performance. sass-loader resolves sass-embedded first and sass second, and notes that listing the embedded one under optionalDependencies lets it fall back on systems the native binary does not support.

Check your Node version before the swap. The current sass manifest, 1.108.2, declares Node 20.19.0 or newer in engines.

Checked against: source 5, source 6, source 8, source 9, source 10

What are the migration steps, in order?

The swap itself is small; the API and syntax work behind it is what takes time. This is the order I would take it in, smallest change first, so each step can be tested on its own.

  • Replace node-sass with sass (or sass-embedded) in package.json. The LibSass deprecation post says the two packages share the same JavaScript API, meaning the older render() style.
  • Build and compare output. The same post warns that LibSass has open bugs and departs from the Sass spec in places, so a few stylesheets may need small edits.
  • Replace render() and renderSync() with compile(), compileString() or their async forms. The source path or string becomes the first argument, and the async versions return a promise instead of taking a callback.
  • Rewrite custom importers. A legacy importer is one function that returns file or contents; a modern Importer splits the work into canonicalize and load. Importers that only pointed at files on disk map to FileImporter.
  • Rewrite custom functions. Modern functions receive all Sass arguments as one list and return a promise when async, with a Value class for type checks.
  • Check every option you pass against the modern Options interface, which lists loadPaths, style, sourceMap, importers, functions and silenceDeprecations, among others.

Checked against: source 1, source 7, source 12

What do sass-loader and Vite expect now?

The sass-loader page names only Dart Sass and Sass Embedded as implementations, and node-sass is not mentioned at all. Its api option accepts auto, modern or modern-compiler, and the page says the legacy JS API is no longer supported. With auto, it picks modern-compiler when the package exposes initAsyncCompiler.

sass-loader also calls a leading ~ in imports deprecated but still accepted. See the tilde import page if removing it breaks a path, and Module build failed from sass-loader for loader errors.

For Vite, the Sass breaking-change page says Vite 6 defaults to the modern API, that 5.4 added the api setting, and that older versions use the legacy API. Vite's own guide only asks you to install sass-embedded or sass, with no plugin. The legacy JS API warning in Vite page covers the warning itself.

Checked against: source 7, source 8, source 9

When do the legacy API and @import stop working?

Sass gives version numbers, not calendar dates, for the next removals. The table puts every milestone from the fetched pages in one line-up, which none of them does alone.

The Sass migrator rewrites @import to the module system, and --built-in-only limits it to the global functions. The deprecation names to silence are import and global-builtin; this page covers the Bootstrap case under Vite.

MilestoneWhat changedWhat it asks of you
26 Oct 2020LibSass deprecatedPlan to leave node-sass
Dart Sass 1.45.0Modern API added; legacy API deprecatedStart using `compile()`
Dart Sass 1.79.0Legacy API starts printing warningsSilence with `legacy-js-api` only while you migrate
Dart Sass 1.80.0`@import` and global built-in functions deprecatedMove to `@use` and module functions
24 Jul 2024Node Sass end of life; repository archivedFinish the package swap
Dart Sass 2.0.0Legacy JS API removedNo `render()` calls left
Dart Sass 3.0.0, no sooner than two years after 1.80.0`@import` and global built-ins removedNo `@import` left
npm install -g sass-migrator
sass-migrator module --migrate-deps your-entrypoint.scss

Checked against: source 1, source 2, source 7, source 11

What else do people ask?

Can I keep node-sass if the project stays on Node 20?

The README still lists node-sass 9.0 or later for Node 20, so it may install. The project also says no more releases will come, even for security fixes, so treat it as frozen code you are carrying.

Does swapping to sass silence every warning at once?

No. The swap removes node-sass, but Dart Sass then warns about the legacy API and about @import. Those are separate jobs with separate removal versions, 2.0.0 and 3.0.0.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. This page joins Sass, node-sass, npm registry, webpack and Vite documents fetched on 20 Nov 2026. I did not run a node-sass migration for it. It does not cover your own importers, stylesheets, framework-specific builders such as Angular's, or build performance. Found a mistake? Tell me.

Keep reading

Next step

Have a project in mind?

Tell me about it. A discovery call within 48 hours.