LegacyFileOptions<sync>

If file is passed without data, Sass will load the stylesheet at file and compile it to CSS.

Type Parameters

Hierarchy

Input

data? file includePaths?

Output

charset? indentType? indentWidth? linefeed? outputStyle?

Plugins

functions? importer? pkgImporter?

Messages

logger? quietDeps? verbose?

Source Maps

omitSourceMapUrl? outFile? sourceMap? sourceMapContents? sourceMapEmbed? sourceMapRoot?

Input

Optional data

data?: undefined

See file for documentation of passing file along with data.

file

file: string
Compatibility (Plain CSS files):
Dart Sass
since 1.11.0
Node Sass
partial

Node Sass and older versions of Dart Sass support loading files with the extension .css, but contrary to the specification they’re treated as SCSS files rather than being parsed as CSS. This behavior has been deprecated and should not be relied on. Any files that use Sass features should use the .scss extension.

All versions of Node Sass and Dart Sass otherwise support the file option as described below.

The path to the file for Sass to load and compile. If the file’s extension is .scss, it will be parsed as SCSS; if it’s .sass, it will be parsed as the indented syntax; and if it’s .css, it will be parsed as plain CSS. If it has no extension, it will be parsed as SCSS.

Example

sass.renderSync({file: "style.scss"});

Optional includePaths

includePaths?: string[]
Compatibility (SASS_PATH):
Dart Sass
since 1.15.0
Node Sass
since 3.9.0

Earlier versions of Dart Sass and Node Sass didn’t support the SASS_PATH environment variable.

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"]
});

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

Output

Optional charset

charset?: boolean
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.

Optional indentType

indentType?: "space" | "tab"
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"

Default Value

'space'

Optional indentWidth

indentWidth?: number
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

Optional linefeed

linefeed?: "cr" | "crlf" | "lf" | "lfcr"
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'

Optional outputStyle

outputStyle?: "expanded" | "compact" | "compressed" | "nested"

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; }

Plugins

Optional functions

functions?: {
    [key: string]: LegacyFunction<sync>;
}

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.

⚠️ Heads up!

When writing custom functions, it’s important to ensure that all the arguments are the types you expect. Otherwise, users’ stylesheets could crash in hard-to-debug ways or, worse, compile to meaningless CSS.

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;
  // }
});

Type declaration

Optional importer

importer?: LegacyImporter<sync> | LegacyImporter<sync>[]
Compatibility:
Dart Sass
✓
Node Sass
since 3.0.0

Versions of Node Sass before 3.0.0 don’t support arrays of importers, nor do they support importers that return Error objects.

Versions of Node Sass before 2.0.0 don’t support the importer option at all.

Compatibility (Import order):
Dart Sass
since 1.20.2
Node Sass
✗

Versions of Dart Sass before 1.20.2 preferred resolving imports using includePaths before resolving them using custom importers.

All versions of Node Sass currently pass imports to importers before loading them relative to the file in which the @import appears. This behavior is considered incorrect and should not be relied on because it violates the principle of locality, which says that it should be possible to reason about a stylesheet without knowing everything about how the entire system is set up. If a user tries to import a stylesheet relative to another stylesheet, that import should always work. It shouldn’t be possible for some configuration somewhere else to break it.

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) {
  // ...
});

Optional pkgImporter

pkgImporter?: NodePackageImporter
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()
});

Messages

Optional logger

logger?: Logger
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.

Optional quietDeps

quietDeps?: boolean
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!

⚠️ Heads up!

If render or renderSync is called without file or file, all stylesheets it loads will be considered dependencies. Since it doesn’t have a path of its own, everything it loads is coming from a load path rather than a relative import.

Default Value

false

Optional verbose

verbose?: boolean
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

Source Maps

Optional omitSourceMapUrl

omitSourceMapUrl?: boolean

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;
// }

Default Value

false

Optional outFile

outFile?: string

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.

⚠️ Heads up!

Despite the name, Sass does not write the CSS output to this file. The caller must do that themselves.

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

Optional sourceMap

sourceMap?: string | boolean

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 * /

Default Value

false

Optional sourceMapContents

sourceMapContents?: boolean

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

Default Value

false

Optional sourceMapEmbed

sourceMapEmbed?: boolean

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

Default Value

false

Optional sourceMapRoot

sourceMapRoot?: string

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