Sass (Pure JavaScript Implementation)

Common errors

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

  cause 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)

  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.
  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'

  cause 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.

  cause 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).

Warnings

• deprecated 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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`).
• gotcha 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.
  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.

Install

• npm install sass npm
• yarn add sass yarn
• pnpm add sass pnpm

Imports

• compile
  wrong:

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

  correct:

  import { compile } from 'sass';

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

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

  correct:

  import { compileAsync } from 'sass';

  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)
  wrong:

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

  correct:

  import * as sass from 'sass';

  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.

Quickstart

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();