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.
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.
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-sasswithsass(orsass-embedded) inpackage.json. The LibSass deprecation post says the two packages share the same JavaScript API, meaning the olderrender()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()andrenderSync()withcompile(),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
fileorcontents; a modernImportersplits the work intocanonicalizeandload. Importers that only pointed at files on disk map toFileImporter. - Rewrite custom functions. Modern functions receive all Sass arguments as one list and return a promise when async, with a
Valueclass for type checks. - Check every option you pass against the modern
Optionsinterface, which listsloadPaths,style,sourceMap,importers,functionsandsilenceDeprecations, among others.
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.
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.
| Milestone | What changed | What it asks of you |
|---|---|---|
| 26 Oct 2020 | LibSass deprecated | Plan to leave node-sass |
| Dart Sass 1.45.0 | Modern API added; legacy API deprecated | Start using `compile()` |
| Dart Sass 1.79.0 | Legacy API starts printing warnings | Silence with `legacy-js-api` only while you migrate |
| Dart Sass 1.80.0 | `@import` and global built-in functions deprecated | Move to `@use` and module functions |
| 24 Jul 2024 | Node Sass end of life; repository archived | Finish the package swap |
| Dart Sass 2.0.0 | Legacy JS API removed | No `render()` calls left |
| Dart Sass 3.0.0, no sooner than two years after 1.80.0 | `@import` and global built-ins removed | No `@import` left |
npm install -g sass-migrator
sass-migrator module --migrate-deps your-entrypoint.scssWhat 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
- Sass blog, LibSass is Deprecated (26 October 2020), fetched 2026-11-20
- Sass blog, Node Sass is end-of-life (24 July 2024), fetched 2026-11-20
- node-sass README, end-of-life warning and Node support table, fetched 2026-11-20
- npm registry, node-sass metadata (latest version, publish time, deprecation message), fetched 2026-11-20
- Sass documentation, JavaScript API overview (sass and sass-embedded), fetched 2026-11-20
- npm registry, sass latest manifest (version and engines), fetched 2026-11-20
- Sass documentation, breaking change, legacy JS API, fetched 2026-11-20
- webpack documentation, sass-loader, fetched 2026-11-20
- Vite guide, features (CSS pre-processors), fetched 2026-11-20
- Vite config, shared options (css.preprocessorOptions), fetched 2026-11-20
- Sass documentation, breaking change, @import and global built-in functions, fetched 2026-11-20
- Sass documentation, JS API Options interface, fetched 2026-11-20
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.