sass

Compile

compile

compile(path: string, options?: Options<"sync">): CompileResult

- Defined in js-api-doc/compile.d.ts:58
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

compileAsync(path: string, options?: Options<"async">): Promise<CompileResult>

- Defined in js-api-doc/compile.d.ts:84
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

compileString(source: string, options?: StringOptions<"sync">): CompileResult

- Defined in js-api-doc/compile.d.ts:114
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
- source: string
- Optional options: StringOptions<"sync">
Returns CompileResult

compileStringAsync

compileStringAsync(source: string, options?: StringOptions<"async">): Promise<CompileResult>

- Defined in js-api-doc/compile.d.ts:149
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
- source: string
- Optional options: StringOptions<"async">
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.

This is a StringOptionsWithImporter if it has a StringOptionsWithImporter.importer field, and a StringOptionsWithoutImporter otherwise.

Type parameters

sync: "sync" | "async"

This lets the TypeScript checker verify that asynchronous Importers, FileImporters, and CustomFunctions aren't passed to compile or compileString.

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

sync: "sync" | "async"

A CustomFunction<'sync'> must return synchronously, but in return it can be passed to compile and compileString in addition to compileAsync and compileStringAsync.

A CustomFunction<'async'> may either return synchronously or asynchronously, but it can only be used with compileAsync and compileStringAsync.

Type declaration

- (args: Value[]): PromiseOr<Value, sync>
- 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 arg1 = args[0].assertNumber('arg1');
      const value1 = 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
  - args: Value[]
    
    An array of arguments passed by the function's caller. If the function takes arbitrary arguments, the last element will be a SassArgumentList.
  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

- (result: LegacyValue | Error): void
- The function called by a LegacyAsyncFunction to indicate that it's finished.
  
  deprecated
  This only works with the legacy render and renderSync APIs. Use CustomFunction with compile, compileString, compileAsync, and compileStringAsync instead.
  
  Parameters
  - result: LegacyValue | Error
    
    If this is a LegacyValue, that indicates that the function call completed successfully. If it's a types.Error, that indicates that the function call failed.
  Returns void

LegacyAsyncImporter

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

Type declaration

- (this: LegacyImporterThis, url: string, prev: string, done: (result: LegacyImporterResult) => void): void
- 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.
    - - (result: LegacyImporterResult): void
      - Parameters
        result: LegacyImporterResult
        Returns void
  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

- (this: LegacyPluginThis, …args: LegacyValue[]): LegacyValue
- A synchronous callback that implements a custom Sass function. This can be passed to LegacySharedOptions.functions for either render or renderSync.
  If this throws an error, Sass will treat that as the function failing with that error message.
```
const result = sass.renderSync({
  file: 'style.scss',
  functions: {
    "sum($arg1, $arg2)": (arg1, arg2) => {
      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");
      }
      return new sass.types.Number(arg1.getValue() + arg2.getValue());
    }
  }
});
```
  deprecated
  This only works with the legacy render and renderSync APIs. Use CustomFunction with compile, compileString, compileAsync, and compileStringAsync instead.
  Parameters
  - this: LegacyPluginThis
  - Rest …args: LegacyValue[]
    
    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.
  Returns LegacyValue

LegacySyncImporter

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

Type declaration

- (this: LegacyImporterThis, url: string, prev: string): LegacyImporterResult
- 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

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

render(options: LegacyOptions<"async">, callback: (exception?: LegacyException, result?: LegacyResult) => void): void

- Defined in js-api-doc/legacy/render.d.ts:136
This function asynchronously compiles a Sass file to CSS, and calls callback with a LegacyResult if compilation succeeds or LegacyException if it fails.
⚠️ Heads up!

When using Dart Sass, renderSync is almost twice as fast as render by default, due to the overhead of making the entire evaluation process asynchronous.
```
const sass = require('sass'); // or require('node-sass');

sass.render({
  file: "style.scss"
}, function(err, result) {
  // ...
});
```
deprecated
Use compileAsync or compileStringAsync instead.
Parameters
- options: LegacyOptions<"async">
- callback: (exception?: LegacyException, result?: LegacyResult) => void
  - - (exception?: LegacyException, result?: LegacyResult): void
    - Parameters
      - Optional exception: LegacyException
      - Optional result: LegacyResult
      Returns void
Returns void

renderSync

renderSync(options: LegacyOptions<"sync">): LegacyResult

- Defined in js-api-doc/legacy/render.d.ts:111
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
- options: LegacyOptions<"sync">
Returns LegacyResult

Index

Compile

Options

Logger

Importer

Custom Function

Other

Legacy

Compile

compile

Parameters

path: string

Optional options: Options<"sync">

Returns CompileResult

compileAsync

⚠️ Heads up!

Parameters

path: string

Optional options: Options<"async">

Returns Promise<CompileResult>

compileString

Parameters

source: string

Optional options: StringOptions<"sync">

Returns CompileResult

compileStringAsync

⚠️ Heads up!

Parameters

source: string

Optional options: StringOptions<"async">

Returns Promise<CompileResult>

Options

OutputStyle

StringOptions

Type parameters

sync: "sync" | "async"

Syntax

Custom Function

CustomFunction

Type parameters

sync: "sync" | "async"

Type declaration

Parameters

args: Value[]

Returns PromiseOr<Value, sync>

ListSeparator

sassFalse

sassNull

sassTrue

Other

PromiseOr

Type parameters

T

sync: "sync" | "async"

info

Legacy

LegacyAsyncFunction

LegacyAsyncFunctionDone

Type declaration

Parameters

result: LegacyValue | Error

Returns void

LegacyAsyncImporter

Type declaration

Parameters

this: LegacyImporterThis

url: string

prev: string

done: (result: LegacyImporterResult) => void

Parameters

result: LegacyImporterResult

Returns void

Returns void

LegacyFunction

Type parameters

sync: "sync" | "async"

LegacyImporter

Type parameters

sync = "sync" | "async"

LegacyImporterResult