sass

Index

Compile

compile

  • Compatibility:
    Dart Sass
    since 1.45.0
    Node Sass

    Synchronously compiles the Sass file at path to CSS. If it succeeds it returns a CompileResult, and if it fails it throws an Exception.

    This only allows synchronous Importers and CustomFunctions.

    example
    const sass = require('sass');

    const result = sass.compile("style.scss");
    console.log(result.css);

    Parameters

    • path: string
    • Optional options: Options<"sync">

    Returns CompileResult

compileAsync

  • Compatibility:
    Dart Sass
    since 1.45.0
    Node Sass

    Asynchronously compiles the Sass file at path to CSS. Returns a promise that resolves with a CompileResult if it succeeds and rejects with an Exception if it fails.

    This only allows synchronous or asynchronous Importers and CustomFunctions.

    ⚠️ Heads up!

    When using Dart Sass, compile is almost twice as fast as compileAsync, due to the overhead of making the entire evaluation process asynchronous.

    example
    const sass = require('sass');

    const result = await sass.compileAsync("style.scss");
    console.log(result.css);

    Parameters

    • path: string
    • Optional options: Options<"async">

    Returns Promise<CompileResult>

compileString

  • Compatibility:
    Dart Sass
    since 1.45.0
    Node Sass

    Synchronously compiles a stylesheet whose contents is source to CSS. If it succeeds it returns a CompileResult, and if it fails it throws an Exception.

    This only allows synchronous Importers and CustomFunctions.

    example
    const sass = require('sass');

    const result = sass.compileString(`
    h1 {
    font-size: 40px;
    code {
    font-face: Roboto Mono;
    }
    }`);
    console.log(result.css);

    Parameters

    Returns CompileResult

compileStringAsync

  • Compatibility:
    Dart Sass
    since 1.45.0
    Node Sass

    Asynchronously compiles a stylesheet whose contents is source to CSS. Returns a promise that resolves with a CompileResult if it succeeds and rejects with an Exception if it fails.

    This only allows synchronous or asynchronous Importers and CustomFunctions.

    ⚠️ Heads up!

    When using Dart Sass, compile is almost twice as fast as compileAsync, due to the overhead of making the entire evaluation process asynchronous.

    example
    const sass = require('sass');

    const result = await sass.compileStringAsync(`
    h1 {
    font-size: 40px;
    code {
    font-face: Roboto Mono;
    }
    }`);
    console.log(result.css);

    Parameters

    Returns Promise<CompileResult>

Options

OutputStyle

OutputStyle: "expanded" | "compressed"

Possible output styles for the compiled CSS:

  • "expanded" (the default for Dart Sass) writes each selector and declaration on its own line.

  • "compressed" removes as many extra characters as possible, and writes the entire stylesheet on a single line.

StringOptions

StringOptions<sync>: StringOptionsWithImporter<sync> | StringOptionsWithoutImporter<sync>

Options that can be passed to compileString or compileStringAsync.

Type parameters

Syntax

Syntax: "scss" | "indented" | "css"

Syntaxes supported by Sass:

  • 'scss' is the SCSS syntax.
  • 'indented' is the indented syntax
  • 'css' is plain CSS, which is parsed like SCSS but forbids the use of any special Sass features.

Custom Function

CustomFunction

CustomFunction<sync>: (args: Value[]) => PromiseOr<Value, sync>

Type parameters

Type declaration

    • A callback that implements a custom Sass function. This can be passed to Options.functions.

      const result = sass.compile('style.scss', {
      functions: {
      "sum($arg1, $arg2)": (args) => {
      const value1 = args[0].assertNumber('arg1').value;
      const value2 = args[1].assertNumber('arg2')
      .convertValueToMatch(arg1, 'arg2', 'arg1');
      return new sass.SassNumber(value1 + value2).coerceToMatch(arg1);
      }
      }
      });
      throws

      any - This function may throw an error, which the Sass compiler will treat as the function call failing. If the exception object has a message property, it will be used as the wrapped exception's message; otherwise, the exception object's toString() will be used. This means it's safe for custom functions to throw plain strings.

      Parameters

      Returns PromiseOr<Value, sync>

      The function's result. This may be in the form of a Promise, but if it is the function may only be passed to compileAsync and compileStringAsync, not compile or compileString.

ListSeparator

ListSeparator: "," | "/" | " " | null

Possible separators used by Sass lists. The special separator null is only used for lists with fewer than two elements, and indicates that the separator has not yet been decided for this list.

sassFalse

sassFalse: SassBoolean

Sass's false value.

sassNull

sassNull: Value

Sass's null value.

sassTrue

sassTrue: SassBoolean

Sass's true value.

Other

PromiseOr

PromiseOr<T, sync>: sync extends "async" ? T | Promise<T> : T

A utility type for choosing between synchronous and asynchronous return values.

This is used as the return value for plugins like CustomFunction, Importer, and FileImporter so that TypeScript enforces that asynchronous plugins are only passed to compileAsync and compileStringAsync, not compile or compileString.

Type parameters

  • T

  • sync: "sync" | "async"

    If this is 'sync', this can only be a T. If it's 'async', this can be either a T or a Promise<T>.

info

info: string

Information about the Sass implementation. This always begins with a unique identifier for the Sass implementation, followed by U+0009 TAB, followed by its npm package version. Some implementations include additional information as well, but not in any standardized format.

  • For Dart Sass, the implementation name is dart-sass.
  • For Node Sass, the implementation name is node-sass.
  • For the embedded host, the implementation name is sass-embedded.

Legacy

LegacyAsyncFunction

LegacyAsyncFunction: ((this: LegacyPluginThis, done: (result: LegacyValue) => void) => void) | ((this: LegacyPluginThis, arg1: LegacyValue, done: LegacyAsyncFunctionDone) => void) | ((this: LegacyPluginThis, arg1: LegacyValue, arg2: LegacyValue, done: LegacyAsyncFunctionDone) => void) | ((this: LegacyPluginThis, arg1: LegacyValue, arg2: LegacyValue, arg3: LegacyValue, done: LegacyAsyncFunctionDone) => void) | ((this: LegacyPluginThis, arg1: LegacyValue, arg2: LegacyValue, arg3: LegacyValue, arg4: LegacyValue, done: LegacyAsyncFunctionDone) => void) | ((this: LegacyPluginThis, arg1: LegacyValue, arg2: LegacyValue, arg3: LegacyValue, arg4: LegacyValue, arg5: LegacyValue, done: LegacyAsyncFunctionDone) => void) | ((this: LegacyPluginThis, arg1: LegacyValue, arg2: LegacyValue, arg3: LegacyValue, arg4: LegacyValue, arg5: LegacyValue, arg6: LegacyValue, done: LegacyAsyncFunctionDone) => void) | ((this: LegacyPluginThis, args: [LegacyValue[], LegacyAsyncFunctionDone]) => void)

An asynchronous callback that implements a custom Sass function. This can be passed to LegacySharedOptions.functions, but only for render.

An asynchronous function must return undefined. Its final argument will always be a callback, which it should call with the result of the function once it's done running.

If this throws an error, Sass will treat that as the function failing with that error message.

sass.render({
file: 'style.scss',
functions: {
"sum($arg1, $arg2)": (arg1, arg2, done) => {
if (!(arg1 instanceof sass.types.Number)) {
throw new Error("$arg1: Expected a number");
} else if (!(arg2 instanceof sass.types.Number)) {
throw new Error("$arg2: Expected a number");
}
done(new sass.types.Number(arg1.getValue() + arg2.getValue()));
}
}
}, (result, error) => {
// ...
});

This is passed one argument for each argument that's declared in the signature that's passed to LegacySharedOptions.functions. If the signature takes arbitrary arguments, they're passed as a single argument list in the last argument before the callback.

deprecated

This only works with the legacy render and renderSync APIs. Use CustomFunction with compile, compileString, compileAsync, and compileStringAsync instead.

LegacyAsyncFunctionDone

LegacyAsyncFunctionDone: (result: LegacyValue | Error) => void

Type declaration

LegacyAsyncImporter

LegacyAsyncImporter: (this: LegacyImporterThis, url: string, prev: string, done: (result: LegacyImporterResult) => void) => void

Type declaration

    • An asynchronous callback that implements custom Sass loading logic for @import rules and @use rules. This can be passed to LegacySharedOptions.importer for either render or renderSync.

      An asynchronous importer must return undefined, and then call done with the result of its LegacyImporterResult once it's done running.

      See LegacySharedOptions.importer for more detailed documentation.

      sass.render({
      file: "style.scss",
      importer: [
      function(url, prev, done) {
      if (url != "big-headers") done(null);

      done({
      contents: 'h1 { font-size: 40px; }'
      });
      }
      ]
      });
      deprecated

      This only works with the legacy render and renderSync APIs. Use Importer with compile, compileString, compileAsync, and compileStringAsync instead.

      Parameters

      • this: LegacyImporterThis
      • url: string

        The @use or @import rule’s URL as a string, exactly as it appears in the stylesheet.

      • prev: string

        A string identifying the stylesheet that contained the @use or @import. This string’s format depends on how that stylesheet was loaded:

        • If the stylesheet was loaded from the filesystem, it’s the absolute path of its file.
        • If the stylesheet was loaded from an importer that returned its contents, it’s the URL of the @use or @import rule that loaded it.
        • If the stylesheet came from the data option, it’s the string "stdin".
      • done: (result: LegacyImporterResult) => void

        The callback to call once the importer has finished running.

      Returns void

LegacyFunction

LegacyFunction<sync>: sync extends "async" ? LegacySyncFunction | LegacyAsyncFunction : LegacySyncFunction

A callback that implements a custom Sass function. For renderSync, this must be a LegacySyncFunction which returns its result directly; for render, it may be either a LegacySyncFunction or a LegacyAsyncFunction which calls a callback with its result.

See LegacySharedOptions.functions for more details.

deprecated

This only works with the legacy render and renderSync APIs. Use CustomFunction with compile, compileString, compileAsync, and compileStringAsync instead.

Type parameters

  • sync: "sync" | "async"

LegacyImporter

LegacyImporter<sync>: sync extends "async" ? LegacySyncImporter | LegacyAsyncImporter : LegacySyncImporter

A callback that implements custom Sass loading logic for @import rules and @use rules. For renderSync, this must be a LegacySyncImporter which returns its result directly; for render, it may be either a LegacySyncImporter or a LegacyAsyncImporter which calls a callback with its result.

See LegacySharedOptions.importer for more details.

deprecated

This only works with the legacy render and renderSync APIs. Use Importer with compile, compileString, compileAsync, and compileStringAsync instead.

Type parameters

  • sync = "sync" | "async"

LegacyImporterResult

LegacyImporterResult: { file: string } | { contents: string } | Error | null

The result of running a LegacyImporter. It must be one of the following types:

  • An object with the key contents whose value is the contents of a stylesheet (in SCSS syntax). This causes Sass to load that stylesheet’s contents.

  • An object with the key file whose value is a path on disk. This causes Sass to load that file as though it had been imported directly.

  • null, which indicates that it doesn’t recognize the URL and another importer should be tried instead.

  • An Error object, indicating that importing failed.

deprecated

This only works with the legacy render and renderSync APIs. Use ImporterResult with compile, compileString, compileAsync, and compileStringAsync instead.

LegacyOptions

LegacyOptions<sync>: LegacyFileOptions<sync> | LegacyStringOptions<sync>

Options for render and renderSync. This can either be LegacyFileOptions to load a file from disk, or LegacyStringOptions to compile a string of Sass code.

See LegacySharedOptions for options that are shared across both file and string inputs.

deprecated

This only works with the legacy render and renderSync APIs. Use Options with compile, compileString, compileAsync, and compileStringAsync instead.

Type parameters

  • sync: "sync" | "async"

LegacySyncFunction

LegacySyncFunction: (this: LegacyPluginThis, args: LegacyValue[]) => LegacyValue

Type declaration

LegacySyncImporter

LegacySyncImporter: (this: LegacyImporterThis, url: string, prev: string) => LegacyImporterResult

Type declaration

    • A synchronous callback that implements custom Sass loading logic for @import rules and @use rules. This can be passed to LegacySharedOptions.importer for either render or renderSync.

      See LegacySharedOptions.importer for more detailed documentation.

      sass.renderSync({
      file: "style.scss",
      importer: [
      function(url, prev) {
      if (url != "big-headers") return null;

      return {
      contents: 'h1 { font-size: 40px; }'
      };
      }
      ]
      });
      deprecated

      This only works with the legacy render and renderSync APIs. Use Importer with compile, compileString, compileAsync, and compileStringAsync instead.

      Parameters

      • this: LegacyImporterThis
      • url: string

        The @use or @import rule’s URL as a string, exactly as it appears in the stylesheet.

      • prev: string

        A string identifying the stylesheet that contained the @use or @import. This string’s format depends on how that stylesheet was loaded:

        • If the stylesheet was loaded from the filesystem, it’s the absolute path of its file.
        • If the stylesheet was loaded from an importer that returned its contents, it’s the URL of the @use or @import rule that loaded it.
        • If the stylesheet came from the data option, it’s the string "stdin".

      Returns LegacyImporterResult

LegacyValue

LegacyValue: Null | Number | String | Boolean | Color | List | Map

A type representing all the possible values that may be passed to or returned from a LegacyFunction.

deprecated

This only works with the legacy render and renderSync APIs. Use Value with compile, compileString, compileAsync, and compileStringAsync instead.

FALSE

FALSE: Boolean<false>

A shorthand for sass.types.Boolean.FALSE.

deprecated

This only works with the legacy render and renderSync APIs. Use sassFalse with compile, compileString, compileAsync, and compileStringAsync instead.

NULL

NULL: Null

A shorthand for sass.types.Null.NULL.

deprecated

This only works with the legacy render and renderSync APIs. Use sassNull with compile, compileString, compileAsync, and compileStringAsync instead.

TRUE

TRUE: Boolean<true>

A shorthand for sass.types.Boolean.TRUE.

deprecated

This only works with the legacy render and renderSync APIs. Use sassTrue with compile, compileString, compileAsync, and compileStringAsync instead.

render

renderSync

  • This function synchronously compiles a Sass file to CSS. If it succeeds, it returns the result, and if it fails it throws an error.

    example
    const sass = require('sass'); // or require('node-sass');

    const result = sass.renderSync({file: "style.scss"});
    // ...
    deprecated

    Use compile or compileString instead.

    Parameters

    Returns LegacyResult