{"id":11980,"library":"sass","title":"Sass (Pure JavaScript Implementation)","description":"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.","status":"active","version":"1.99.0","language":"javascript","source_language":"en","source_url":"https://github.com/sass/dart-sass","tags":["javascript","style","scss","sass","preprocessor","css","typescript"],"install":[{"cmd":"npm install sass","lang":"bash","label":"npm"},{"cmd":"yarn add sass","lang":"bash","label":"yarn"},{"cmd":"pnpm add sass","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Use named imports for modern API functions like `compile` and `compileAsync`. This is the synchronous API for processing SCSS/Sass files or strings.","wrong":"import sass from 'sass';\nconst result = sass.compile(...);","symbol":"compile","correct":"import { compile } from 'sass';"},{"note":"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.","wrong":"const sass = require('sass');\nconst result = sass.compileAsync(...);","symbol":"compileAsync","correct":"import { compileAsync } from 'sass';"},{"note":"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.","wrong":"const sass = require('sass'); // While functional, ESM is the preferred module system for modern Node.js development.","symbol":"sass (namespace/default)","correct":"import * as sass from 'sass';"},{"note":"The `Logger` class provides functionality for custom logging within the Sass compilation process, available since version 1.98.0.","wrong":null,"symbol":"Logger","correct":"import { Logger } from 'sass';"}],"quickstart":{"code":"import { compile, compileAsync } from 'sass';\nimport * as fs from 'fs/promises';\nimport * as path from 'path';\n\nasync function runSassExample() {\n  const scssContent = `\n    $primary-color: #337ab7;\n    $font-stack: Helvetica, sans-serif;\n\n    body {\n      font: 100% $font-stack;\n      color: #333;\n    }\n\n    .button {\n      background-color: $primary-color;\n      color: white;\n      padding: 10px 15px;\n      border: none;\n      &:hover {\n        background-color: darken($primary-color, 10%);\n      }\n    }\n  `;\n\n  const tempScssFile = path.join(process.cwd(), 'styles.scss');\n  const tempCssFileSync = path.join(process.cwd(), 'styles-sync.css');\n  const tempCssFileAsync = path.join(process.cwd(), 'styles-async.css');\n\n  try {\n    await fs.writeFile(tempScssFile, scssContent);\n    console.log(`Wrote temporary SCSS to ${tempScssFile}`);\n\n    // Synchronous compilation (often faster for local files than async)\n    const syncResult = compile(tempScssFile);\n    await fs.writeFile(tempCssFileSync, syncResult.css);\n    console.log(`\\nCompiled SCSS synchronously to ${tempCssFileSync}:\\n${syncResult.css}`);\n\n    // Asynchronous compilation (generally preferred for non-blocking I/O, but can be slower for simple local files)\n    const asyncResult = await compileAsync(tempScssFile);\n    await fs.writeFile(tempCssFileAsync, asyncResult.css);\n    console.log(`\\nCompiled SCSS asynchronously to ${tempCssFileAsync}:\\n${asyncResult.css}`);\n\n  } catch (error) {\n    console.error('Sass compilation failed:', error);\n  } finally {\n    // Clean up temporary files\n    await fs.unlink(tempScssFile).catch(() => {});\n    await fs.unlink(tempCssFileSync).catch(() => {});\n    await fs.unlink(tempCssFileAsync).catch(() => {});\n    console.log('\\nCleaned up temporary files.');\n  }\n}\n\nrunSassExample();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"deprecated","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`).","message":"The 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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"This `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use the deprecated legacy `render` or `renderSync` functions from the `sass` package.","error":"Error: `render()` and `renderSync()` are no longer supported. Use `compile()` or `compileAsync()` instead."},{"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.","cause":"Passing unsupported `outputStyle` values (other than 'expanded' or 'compressed'), `precision`, or `sourceComments` to the deprecated `render()`/`renderSync()` functions in Dart Sass's legacy API.","error":"TypeError: Cannot read properties of undefined (reading 'css') (when using legacy API options)"},{"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.","cause":"The 'sass' package is not installed, not listed in your project's dependencies, or cannot be resolved by your module loader.","error":"Cannot find module 'sass'"},{"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).","cause":"A Sass variable was used without being defined in the current scope or an imported file.","error":"Error: Undefined variable."}],"ecosystem":"npm"}