sass

library2.3jsnpmunverified

The `sass` npm package provides a pure JavaScript implementation of the Sass preprocessor, enabling developers to compile SCSS and Sass files into CSS. It is currently at version 1.99.0 and receives frequent, iterative updates, with new features and bug fixes released regularly as seen in its changelog. This package is a compilation of Dart Sass to JavaScript, making it highly portable with no native dependencies, unlike `node-sass` which relies on LibSass (C++). It offers both a command-line interface and a Node.js API, featuring modern asynchronous and synchronous `compile` functions for transforming Sass code. While it maintains a legacy API compatible with `node-sass` (`render`, `renderSync`), this API is deprecated and slated for removal in Dart Sass 2.0.0, distinguishing its usage patterns from older Sass integrations. Its key differentiators include platform independence, official support from the Sass team, and predictable evolution, providing a robust and evolving solution for CSS preprocessing in JavaScript environments.

serialization

npm install sass

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SASS

sass

serializationjavascriptv2.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

compile

✓ import { compile } from 'sass';

✗ import sass from 'sass'; const result = sass.compile(...);

Use named imports for modern API functions like `compile` and `compileAsync`. This is the synchronous API for processing SCSS/Sass files or strings.

compileAsync

✓ import { compileAsync } from 'sass';

✗ const sass = require('sass'); const result = sass.compileAsync(...);

Use named imports for the modern asynchronous API. This is generally preferred for I/O operations but can be slower than `compile` for local file system operations. Ensure your environment supports top-level await or wrap in an async function.

sass (namespace/default)

✓ import * as sass from 'sass';

✗ const sass = require('sass'); // While functional, ESM is the preferred module system for modern Node.js development.

For full API access, including deprecated legacy functions or utility types, importing the entire module as a namespace is common. `require('sass')` is still fully supported in CommonJS environments.

Logger

✓ import { Logger } from 'sass';

The `Logger` class provides functionality for custom logging within the Sass compilation process, available since version 1.98.0.

This quickstart demonstrates both synchronous (`compile`) and asynchronous (`compileAsync`) compilation of a simple SCSS string into CSS, writing the output to temporary files. It showcases common Sass features like variables and nesting, and cleans up after execution.

import { compile, compileAsync } from 'sass'; import * as fs from 'fs/promises'; import * as path from 'path'; async function runSassExample() { const scssContent = ` $primary-color: #337ab7; $font-stack: Helvetica, sans-serif; body { font: 100% $font-stack; color: #333; } .button { background-color: $primary-color; color: white; padding: 10px 15px; border: none; &:hover { background-color: darken($primary-color, 10%); } } `; const tempScssFile = path.join(process.cwd(), 'styles.scss'); const tempCssFileSync = path.join(process.cwd(), 'styles-sync.css'); const tempCssFileAsync = path.join(process.cwd(), 'styles-async.css'); try { await fs.writeFile(tempScssFile, scssContent); console.log(`Wrote temporary SCSS to ${tempScssFile}`); // Synchronous compilation (often faster for local files than async) const syncResult = compile(tempScssFile); await fs.writeFile(tempCssFileSync, syncResult.css); console.log(`\nCompiled SCSS synchronously to ${tempCssFileSync}:\n${syncResult.css}`); // Asynchronous compilation (generally preferred for non-blocking I/O, but can be slower for simple local files) const asyncResult = await compileAsync(tempScssFile); await fs.writeFile(tempCssFileAsync, asyncResult.css); console.log(`\nCompiled SCSS asynchronously to ${tempCssFileAsync}:\n${asyncResult.css}`); } catch (error) { console.error('Sass compilation failed:', error); } finally { // Clean up temporary files await fs.unlink(tempScssFile).catch(() => {}); await fs.unlink(tempCssFileSync).catch(() => {}); await fs.unlink(tempCssFileAsync).catch(() => {}); console.log('\nCleaned up temporary files.'); } } runSassExample();

sass --version

Debug

Known issues

deprecatedThe legacy `render()` and `renderSync()` JavaScript API functions are deprecated and will be removed in Dart Sass 2.0.0. Projects should migrate to the modern `compile()` and `compileAsync()` APIs.

fix

Rewrite compilation logic to use `sass.compile()` or `sass.compileAsync()`. Refer to the Sass JS API documentation for the new signature and options, as they differ significantly from the legacy API.

affects: >=1.0.0

gotchaThe asynchronous `compileAsync()` function can be substantially slower than the synchronous `compile()` function when the input is local and not an I/O stream. For local file compilation, `compile()` may offer better performance, contrary to typical async/sync expectations in Node.js.

fix

Benchmark both `compile()` and `compileAsync()` for your specific use case to determine the optimal choice. For local file system compilation, `compile()` is often the faster option, while `compileAsync()` remains beneficial for non-blocking operations in larger build processes.

affects: >=1.0.0

breakingThe legacy `render()` and `renderSync()` functions in Dart Sass have limitations compared to `node-sass`'s API. Specifically, they do not support `outputStyle` values other than 'expanded' or 'compressed', nor do they support `precision` or `sourceComments`. These options are explicitly unsupported.

fix

When migrating from `node-sass`, ensure these deprecated options are removed or replaced. `precision` is handled automatically by Dart Sass, and `sourceComments` is superseded by source maps (the default behavior for `compile` and `compileAsync`).

affects: >=1.0.0

gotchaThis `sass` package is a pure JavaScript distribution of *Dart Sass*. It is distinct from `node-sass`, which is a wrapper around LibSass (C++). While their legacy APIs were similar, their underlying implementations and feature evolution diverge. `node-sass` has been largely unmaintained for several years and may have compatibility issues.

fix

Always install `sass` for modern Sass compilation in JavaScript environments. Avoid `node-sass` for new projects, and consider migrating existing projects due to its lack of updates, potential installation issues with native dependencies, and differing feature sets.

affects: >=1.0.0

Errors

Common errors & fixes

Error: `render()` and `renderSync()` are no longer supported. Use `compile()` or `compileAsync()` instead.

Attempting to use the deprecated legacy `render` or `renderSync` functions from the `sass` package.

fix

Update your code to use the modern `compile()` or `compileAsync()` functions. The API signatures and return types are different, so carefully consult the official Sass JS API documentation.

TypeError: Cannot read properties of undefined (reading 'css') (when using legacy API options)

Passing unsupported `outputStyle` values (other than 'expanded' or 'compressed'), `precision`, or `sourceComments` to the deprecated `render()`/`renderSync()` functions in Dart Sass's legacy API.

fix

Remove the `outputStyle` option if it's not 'expanded' or 'compressed'. Remove `precision` and `sourceComments` options entirely, as they are not supported by Dart Sass's legacy API and will cause errors.

Cannot find module 'sass'

The 'sass' package is not installed, not listed in your project's dependencies, or cannot be resolved by your module loader.

fix

Run `npm install sass` or `yarn add sass` in your project directory. If using a global executable, ensure it's installed via `npm install -g sass` and your system's PATH variable is correctly configured.

Error: Undefined variable.

A Sass variable was used without being defined in the current scope or an imported file.

fix

Ensure all variables are defined before use. Check for typos in variable names or verify that the file containing the variable definition is correctly imported using `@use` or `@forward` (preferred) or `@import` (legacy).

Upgrade

Version history

2.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/sass/dart-sass ↗

packagehttps://www.npmjs.com/package/sass ↗

homepagehttps://sass-lang.com ↗