Interface Options<sync>

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

Functions are passed JavaScript representations of Sass value types, and must return the same.

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 Value.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 SassNumber.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 Value.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. Value.sassIndexToListIndex and SassString.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. SassString.sassIndexToStringIndex can be used to do this automatically, and the SassString.sassLength getter can be used to access a string's length in code points.

Loads are resolved by trying, in order:

• The importer that was used to load the current stylesheet, with the loaded URL resolved relative to the current stylesheet's canonical URL.

• Each Importer or FileImporter in importers, in order.

• Each load path in loadPaths, in order.

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

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

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

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!