StringOptions<sync>

Options that can be passed to compileString or compileStringAsync.

If the importer field isn't passed, the entrypoint file can load files relative to itself if a file:// URL is passed to the url field. If it is passed, the entrypoint file uses it to load files relative to itself.

Type Parameters

Hierarchy

Input

importer?: Importer<sync> | FileImporter<sync>

The importer to use to handle loads that are relative to the entrypoint stylesheet.

A relative load's URL is first resolved relative to url, then passed to importer. (It's passed as-is if url isn't passed.) If the importer doesn't recognize it, it's then passed to importers and loadPaths.

loadPaths?: string[]

Paths in which to look for stylesheets loaded by rules like @use and @import.

A load path loadPath is equivalent to the following FileImporter:

{
findFileUrl(url) {
// Load paths only support relative URLs.
if (/^[a-z]+:/i.test(url)) return null;
return new URL(url, pathToFileURL(loadPath));
}
}
syntax?: Syntax

The Syntax to use to parse the entrypoint stylesheet.

Default

'scss'

url?: URL
Compatibility (Undefined URL with importer):
Dart Sass
since 1.75.0
Node Sass

Earlier versions of Dart Sass required url to be defined when passing importer.

The canonical URL of the entrypoint stylesheet.

A relative load's URL is first resolved relative to url, then resolved to a file on disk if it's a file:// URL. If it can't be resolved to a file on disk, it's then passed to importers and loadPaths.

Output

charset?: boolean
Compatibility:
Dart Sass
since 1.54.0
Node Sass

If true, the compiler may prepend @charset "UTF-8"; or U+FEFF (byte-order marker) if it outputs non-ASCII CSS.

If false, the compiler never emits these byte sequences. This is ideal when concatenating or embedding in HTML <style> tags. (The output will still be UTF-8.)

Default Value

true

sourceMap?: boolean

Whether or not Sass should generate a source map. If it does, the source map will be available as sourceMap.

⚠️ Heads up!

Sass doesn’t automatically add a sourceMappingURL comment to the generated CSS. It’s up to callers to do that, since callers have full knowledge of where the CSS and the source map will exist in relation to one another and how they’ll be served to the browser.

Default Value

false

sourceMapIncludeSources?: boolean

Whether Sass should include the sources in the generated source map.

This option has no effect if sourceMap is false.

Default Value

false

style?: OutputStyle

The OutputStyle of the compiled CSS.

Example

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

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

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

Plugins

functions?: Record<string, CustomFunction<sync>>

Additional built-in Sass functions that are available in all stylesheets. This option takes an object whose keys are Sass function signatures like you'd write for the @function rule and whose values are CustomFunctions.

Functions are passed subclasses of Value, and must return the same. If the return value includes SassCalculations they will be simplified before being returned.

When writing custom functions, it's important to make them as user-friendly and as close to the standards set by Sass's core functions as possible. Some good guidelines to follow include:

  • Use Value.assert* methods, like assertString, to cast untyped Value objects to more specific types. For values that were passed directly as arguments, pass in the argument name as well. This ensures that the user gets good error messages when they pass in the wrong type to your function.

  • Individual classes may have more specific assert* methods, like assertInt, which should be used when possible.

  • In Sass, every value counts as a list. Rather than trying to detect the SassList type, you should use asList to treat all values as lists.

  • When manipulating values like lists, strings, and numbers that have metadata (comma versus space separated, bracketed versus unbracketed, quoted versus unquoted, units), the output metadata should match the input metadata.

  • When in doubt, lists should default to comma-separated, strings should default to quoted, and numbers should default to unitless.

  • In Sass, lists and strings use one-based indexing and use negative indices to index from the end of value. Functions should follow these conventions. sassIndexToListIndex and sassIndexToStringIndex can be used to do this automatically.

  • String indexes in Sass refer to Unicode code points while JavaScript string indices refer to UTF-16 code units. For example, the character U+1F60A SMILING FACE WITH SMILING EYES is a single Unicode code point but is represented in UTF-16 as two code units (0xD83D and 0xDE0A). So in JavaScript, "a😊b".charCodeAt(1) returns 0xD83D, whereas in Sass str-slice("a😊b", 1, 1) returns "😊". Functions should follow Sass's convention. sassIndexToStringIndex can be used to do this automatically, and the sassLength getter can be used to access a string's length in code points.

Example

sass.compileString(`
h1 {
font-size: pow(2, 5) * 1px;
}`, {
functions: {
// Note: in real code, you should use `math.pow()` from the built-in
// `sass:math` module.
'pow($base, $exponent)': function(args) {
const base = args[0].assertNumber('base').assertNoUnits('base');
const exponent =
args[1].assertNumber('exponent').assertNoUnits('exponent');

return new sass.SassNumber(Math.pow(base.value, exponent.value));
}
}
});
importers?: (NodePackageImporter | Importer<sync> | FileImporter<sync>)[]

Custom importers that control how Sass resolves loads from rules like @use and @import.

Loads are resolved by trying, in order:

If none of these return a Sass file, the load fails and Sass throws an error.

Messages

alertAscii?: boolean

If this is true, the compiler will exclusively use ASCII characters in its error and warning messages. Otherwise, it may use non-ASCII Unicode characters as well.

Default Value

false

alertColor?: boolean

If this is true, the compiler will use ANSI color escape codes in its error and warning messages. If it's false, it won't use these. If it's undefined, the compiler will determine whether or not to use colors depending on whether the user is using an interactive terminal.

fatalDeprecations?: (DeprecationOrId | Version)[]

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.74.0", node: false

futureDeprecations?: DeprecationOrId[]

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.74.0", node: false

logger?: Logger

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.

quietDeps?: boolean

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 loadPaths or importers. 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 compileString or compileStringAsync is called without url, 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

silenceDeprecations?: DeprecationOrId[]

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.

⚠️ Heads up!

The deprecated functionality you’re depending on will eventually break.

Compatiblity

dart: "1.74.0", node: false

verbose?: boolean

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