LegacyFileOptions<sync>

Compatibility (SASS_PATH):

Dart Sass

since 1.15.0

Node Sass

since 3.9.0

➤

This array of strings option provides load paths for Sass to look for stylesheets. Earlier load paths will take precedence over later ones.

sass.renderSync({
  file: "style.scss",
  includePaths: ["node_modules/bootstrap/dist/css"]
});
Copy

Load paths are also loaded from the SASS_PATH environment variable, if it’s set. This variable should be a list of paths separated by ; (on Windows) or : (on other operating systems). Load paths from the includePaths option take precedence over load paths from SASS_PATH.

$ SASS_PATH=node_modules/bootstrap/dist/css sass style.scss style.css
Copy

Compatibility:

Dart Sass

since 1.39.0

Node Sass

✗

By default, if the CSS document contains non-ASCII characters, Sass adds a @charset declaration (in expanded output mode) or a byte-order mark (in compressed mode) to indicate its encoding to browsers or other consumers. If charset is false, these annotations are omitted.

Compatibility:

Dart Sass

✓

Node Sass

since 3.0.0

Whether the generated CSS should use spaces or tabs for indentation.

const result = sass.renderSync({
  file: "style.scss",
  indentType: "tab",
  indentWidth: 1
});

result.css.toString();
// "h1 {\n\tfont-size: 40px;\n}\n"
Copy

Default Value

'space'

Compatibility:

Dart Sass

✓

Node Sass

since 3.0.0

How many spaces or tabs (depending on indentType) should be used per indentation level in the generated CSS. It must be between 0 and 10 (inclusive).

Default Value

2

Compatibility:

Dart Sass

✓

Node Sass

since 3.0.0

Which character sequence to use at the end of each line in the generated CSS. It can have the following values:

• 'lf' uses U+000A LINE FEED.
• 'lfcr' uses U+000A LINE FEED followed by U+000D CARRIAGE RETURN.
• 'cr' uses U+000D CARRIAGE RETURN.
• 'crlf' uses U+000D CARRIAGE RETURN followed by U+000A LINE FEED.

Default Value

'lf'

The output style of the compiled CSS. There are four possible output styles:

• "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.

• "nested" (the default for Node Sass, not supported by Dart Sass) indents CSS rules to match the nesting of the Sass source.

• "compact" (not supported by Dart Sass) puts each CSS rule on its own single line.

Example

const source = `
h1 {
  font-size: 40px;
  code {
    font-face: Roboto Mono;
  }
}`;

let result = sass.renderSync({
  data: source,
  outputStyle: "expanded"
});
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// h1 code {
//   font-face: Roboto Mono;
// }

result = sass.renderSync({
  data: source,
  outputStyle: "compressed"
});
console.log(result.css.toString());
// h1{font-size:40px}h1 code{font-face:Roboto Mono}

result = sass.renderSync({
  data: source,
  outputStyle: "nested"
});
console.log(result.css.toString());
// h1 {
//   font-size: 40px; }
//   h1 code {
//     font-face: Roboto Mono; }

result = sass.renderSync({
  data: source,
  outputStyle: "compact"
});
console.log(result.css.toString());
// h1 { font-size: 40px; }
// h1 code { font-face: Roboto Mono; }
Copy

Additional built-in Sass functions that are available in all stylesheets. This option takes an object whose keys are Sass function signatures and whose values are LegacyFunctions. Each function should take the same arguments as its signature.

Functions are passed subclasses of LegacyValue, and must return the same.

Example

sass.render({
  data: `
h1 {
  font-size: pow(2, 5) * 1px;
}`,
  functions: {
    // This function uses the synchronous API, and can be passed to either
    // renderSync() or render().
    'pow($base, $exponent)': function(base, exponent) {
      if (!(base instanceof sass.types.Number)) {
        throw "$base: Expected a number.";
      } else if (base.getUnit()) {
        throw "$base: Expected a unitless number.";
      }

      if (!(exponent instanceof sass.types.Number)) {
        throw "$exponent: Expected a number.";
      } else if (exponent.getUnit()) {
        throw "$exponent: Expected a unitless number.";
      }

      return new sass.types.Number(
          Math.pow(base.getValue(), exponent.getValue()));
    },

    // This function uses the asynchronous API, and can only be passed to
    // render().
    'sqrt($number)': function(number, done) {
      if (!(number instanceof sass.types.Number)) {
        throw "$number: Expected a number.";
      } else if (number.getUnit()) {
        throw "$number: Expected a unitless number.";
      }

      done(new sass.types.Number(Math.sqrt(number.getValue())));
    }
  }
}, function(err, result) {
  console.log(result.css.toString());
  // h1 {
  //   font-size: 32px;
  // }
});
Copy

Compatibility:

Dart Sass

✓

Node Sass

since 3.0.0

➤

Compatibility (Import order):

Dart Sass

since 1.20.2

Node Sass

✗

➤

Additional handler(s) for loading files when a @use rule or an @import rule is encountered. It can either be a single LegacyImporter function, or an array of LegacyImporters.

Importers take the URL of the @import or @use rule and return a LegacyImporterResult indicating how to handle that rule. For more details, see LegacySyncImporter and LegacyAsyncImporter.

Loads are resolved by trying, in order:

• Loading a file from disk relative to the file in which the @use or @import appeared.

• Each custom importer.

• Loading a file relative to the current working directory.

• Each load path in includePaths.

• Each load path specified in the SASS_PATH environment variable, which should be semicolon-separated on Windows and colon-separated elsewhere.

Example

sass.render({
  file: "style.scss",
  importer: [
    // This importer uses the synchronous API, and can be passed to either
    // renderSync() or render().
    function(url, prev) {
      // This generates a stylesheet from scratch for `@use "big-headers"`.
      if (url != "big-headers") return null;

      return {
        contents: `
h1 {
  font-size: 40px;
}`
      };
    },

    // This importer uses the asynchronous API, and can only be passed to
    // render().
    function(url, prev, done) {
      // Convert `@use "foo/bar"` to "node_modules/foo/sass/bar".
      const components = url.split('/');
      const innerPath = components.slice(1).join('/');
      done({
        file: `node_modules/${components.first}/sass/${innerPath}`
      });
    }
  ]
}, function(err, result) {
  // ...
});
Copy

Compatibility:

Dart Sass

since 2.0

Node Sass

✗

If this option is set to an instance of NodePackageImporter, Sass will use the built-in Node.js package importer to resolve Sass files with a pkg: URL scheme. Details for library authors and users can be found in the NodePackageImporter documentation.

Example

sass.renderSync({
  data: '@use "pkg:vuetify";',
  pkgImporter: new sass.NodePackageImporter()
});
Copy

A set of deprecations to treat as fatal.

If a deprecation warning of any provided type is encountered during compilation, the compiler will error instead.

If a Version is provided, then all deprecations that were active in that compiler version will be treated as fatal.

Compatiblity

dart: "1.78.0", node: false

A set of future deprecations to opt into early.

Future deprecations passed here will be treated as active by the compiler, emitting warnings as necessary.

Compatiblity

dart: "1.78.0", node: false

Compatibility:

Dart Sass

since 1.43.0

Node Sass

✗

An object to use to handle warnings and/or debug messages from Sass.

By default, Sass emits warnings and debug messages to standard error, but if warn or debug is set, this will invoke them instead.

The special value silent can be used to easily silence all messages.

Compatibility:

Dart Sass

since 1.35.0

Node Sass

✗

If this option is set to true, Sass won’t print warnings that are caused by dependencies. A “dependency” is defined as any file that’s loaded through includePaths or importer. Stylesheets that are imported relative to the entrypoint are not considered dependencies.

This is useful for silencing deprecation warnings that you can’t fix on your own. However, please also notify your dependencies of the deprecations so that they can get fixed as soon as possible!

Default Value

false

A set of active deprecations to ignore.

If a deprecation warning of any provided type is encountered during compilation, the compiler will ignore it instead.

Compatiblity

dart: "1.78.0", node: false

Compatibility:

Dart Sass

since 1.35.0

Node Sass

✗

By default, Dart Sass will print only five instances of the same deprecation warning per compilation to avoid deluging users in console noise. If you set verbose to true, it will instead print every deprecation warning it encounters.

Default Value

false

If true, Sass won't add a link from the generated CSS to the source map.

const result = sass.renderSync({
  file: "style.scss",
  sourceMap: "out.map",
  omitSourceMapUrl: true
})
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
Copy

Default Value

false

The location that Sass expects the generated CSS to be saved to. It’s used to determine the URL used to link from the generated CSS to the source map, and from the source map to the Sass source files.

result = sass.renderSync({
  file: "style.scss",
  sourceMap: true,
  outFile: "out.css"
})
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// /*# sourceMappingURL=out.css.map * /
Copy

Whether or not Sass should generate a source map. If it does, the source map will be available as map (unless sourceMapEmbed is true).

If this option is a string, it’s the path that the source map is expected to be written to, which is used to link to the source map from the generated CSS and to link from the source map to the Sass source files. Note that if sourceMap is a string and outFile isn’t passed, Sass assumes that the CSS will be written to the same directory as the file option if it’s passed.

If this option is true, the path is assumed to be outFile with .map added to the end. If it’s true and outFile isn’t passed, it has no effect.

Example

let result = sass.renderSync({
  file: "style.scss",
  sourceMap: "out.map"
})
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// /*# sourceMappingURL=out.map * /

result = sass.renderSync({
  file: "style.scss",
  sourceMap: true,
  outFile: "out.css"
})
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// /*# sourceMappingURL=out.css.map * /
Copy

Default Value

false

Whether to embed the entire contents of the Sass files that contributed to the generated CSS in the source map. This may produce very large source maps, but it guarantees that the source will be available on any computer no matter how the CSS is served.

Example

sass.renderSync({
  file: "style.scss",
  sourceMap: "out.map",
  sourceMapContents: true
})
Copy

Default Value

false

Whether to embed the contents of the source map file in the generated CSS, rather than creating a separate file and linking to it from the CSS.

Example

sass.renderSync({
  file: "style.scss",
  sourceMap: "out.map",
  sourceMapEmbed: true
});
Copy

Default Value

false

If this is passed, it's prepended to all the links from the source map to the Sass source files.