Skip to content

Options

StringOptions carries everything a single compile needs to know. It is immutable, built with a Lombok builder, and reusable across compiles:

var options = StringOptions.builder()
    .url(URI.create("virtual:root.scss"))
    .style(StringOptions.OutputStyle.COMPRESSED)
    .sourceMap(true)
    .build();

Passing null instead of an options object is allowed and means "all defaults".

One type for both entry points

The dart-sass JS API splits these settings into StringOptions (for string input) and Options (for file input). jsass merges them: the same builder feeds both compileString(…) and compilePath(…).

Every option below is unset by default; unset means dart-sass's own default applies.

Input

url

URI — the URL the source is considered to live at. It is what relative imports resolve against and what shows up in error messages and source maps. Set it for string compiles that use imports; a scheme of your own (virtual:root.scss) is a perfectly good answer.

inputSyntax

Syntax.SCSS (default), Syntax.INDENTED for the indented .sass syntax, or Syntax.CSS for plain CSS that is parsed but rejects Sass features.

charset

Character set of the generated CSS.

Output

Output style

style(OutputStyle.EXPANDED) — one selector and declaration per line, the dart-sass default — or style(OutputStyle.COMPRESSED) — everything on one line, as small as it gets.

Migrating from jsass 5

libsass had four styles. dart-sass dropped NESTED and COMPACT, so jsass 6 only exposes EXPANDED and COMPRESSED. EXPANDED is the closest replacement for both.

Source maps

StringOptions.builder()
    .sourceMap(true)
    .sourceMapIncludeSources(true)
    .build();

sourceMap(true) makes Output.getSourceMap() return the source-map JSON — it is null otherwise. sourceMapIncludeSources(true) embeds the original sources in it, which makes the map self-contained at the price of size.

Resolving imports

loadPaths

List<Path> of directories searched for @use / @import, in order.

.loadPaths(List.of(Path.of("src/main/scss"), Path.of("node_modules")))

jsass resolves these in Java rather than handing them to dart-sass, which keeps them working on the V8 engine as well. A path that would escape a load path via .. is skipped and the next load path is tried — one tainted entry does not abort the compile.

importer and importers

importer(…) sets the importer — the one that also resolves relative imports from the entry stylesheet. importers(List.of(…)) registers additional ones, tried in order. See importers.

Extending Sass

functions

Map<String, SassFunction> keyed by SCSS signature, e.g. "pow($base, $exp)". See custom functions.

logger

A SassLogger receiving @warn and @debug from your stylesheets.

Diagnostics

Deprecations

Option Type Effect
fatalDeprecations List<String> these deprecation IDs fail the compile instead of warning
silenceDeprecations List<String> these deprecation IDs are not reported at all
quietDeps Boolean suppress warnings originating in dependencies
verbose Boolean report every warning, not just the first few per type

The IDs are dart-sass's own, such as import or color-functions — see the Sass deprecation list.

Message formatting

alertAscii(true) keeps warnings and errors to ASCII characters; alertColor(true) / false forces ANSI colors on or off.

Timeouts

.timeout(Duration.ofSeconds(5))

Bounds this compile. Unset, the compiler's defaultTimeout applies, and failing that a built-in 30 seconds. The value must be positive — build() throws IllegalArgumentException otherwise. See engines.

Reusing and tweaking options

toBuilder() copies an existing options object so you can change one thing:

var dev = StringOptions.builder().sourceMap(true).build();
var prod = dev.toBuilder()
    .sourceMap(false)
    .style(StringOptions.OutputStyle.COMPRESSED)
    .build();