I’m excited to officially unveil something that’s been in the works for quite a
while now: a (proposal for a) brand new JavaScript API for Sass. This API has
been redesigned from the ground up based on lessons learned from both the Node
Sass API and various other historical Sass APIs in other languages through the
years, and it addresses many of the shortcomings of the existing API.
The API has four main components, all of which I’ll cover in this post:
The core compilation API
The logger API
The importer API
The function API
As you read on, remember that this API is still just a proposal. We want to hear
from you, our users, whether it meets your needs and how we can improve it
before we lock it in to a full release. So go ahead and make your voices known
on the issue tracker!
Why a New API? permalinkWhy a New API?
The existing JavaScript API is showing its age. It predates Dart Sass, having
been originally designed for the node-sass package, which wrapped the
now-deprecated implementation. (That’s why we call it the “Node Sass
API”!) It grew organically and often messily along with LibSass, and ended up
with more than a few awkward legacy behaviors. Many of these behaviors are more
of a pain for implementation than anything else, but a few of them made life
quite difficult:
The importer API was built around file paths rather than URLs, and was tightly
coupled to the physical filesystem. This made it impossible to override all
file-based loads and present a fully virtual filesystem, and caused custom
Node importers to interact poorly with the new module system.
The function API was built around mutable value objects, which runs counter to
Sass’s immutable nature. It also provided no utility methods (such as looking
up a key in a map) to make it easier to implement idiomatic custom functions,
and didn’t provide access to crucial information about values such as whether
strings were quoted.
All of the asynchronous functions were callback-based rather than
promise-based.
The new API addresses these issues and more with a modern, idiomatic API that
will make working with Sass from JS a breeze.
Compilation permalinkCompilation
At the heart of the API are four functions that do the actual Sass compilation,
two synchronous and two asynchronous. They’re presented here in TypeScript
syntax to clarify exactly what they take and return, but you can always call
them from plain JS:
function compile(
path: string,
options?: Options<'sync'>
): CompileResult;
function compileString(
source: string,
options?: StringOptions<'sync'>
): CompileResult;
function compileAsync(
path: string,
options?: Options<'async'>
): Promise<CompileResult>;
function compileStringAsync(
source: string,
options?: StringOptions<'async'>
): Promise<CompileResult>;
The compile() and compileAsync() functions load a Sass file from a path on
disk, whereas compileString() and compileStringAsync() compile Sass source
code passed in as a string. All these take the following options:
alertAscii: Whether errors and warnings should use only ASCII characters (as
opposed to, for example, Unicode box-drawing characters).
alertColor: Whether errors and warnings should use terminal colors.
loadPaths: A list of file paths to use to look up files to load, just like
includePaths in the old API.
importers: A list of custom importers to use to load Sass
source files.
functions: An object whose keys are Sass function signatures and whose
values are custom functions.
quietDeps: Whether to silence deprecation warnings in dependencies.
logger: The custom logger to use to emit warnings and debug
messages.
sourceMap: Whether to generate a source map during compilation.
style: The output style, 'compressed' or 'expanded'.
verbose: Whether to emit every deprecation warning encountered.
The compileString() and compileStringAsync() functions take a few additional
options:
syntax: The syntax of the file, 'scss' (the default), 'indented', or
'css'.
url: The canonical URL of the file.
importer: The custom importer to treat as the file’s source.
If this is passed, this importer will be used to resolve relative loads from
this stylesheet.
All these functions return an object with the following fields:
css: The compiled CSS, as a string.
loadedUrls: All the URLs loaded during the compilation, in no particular
order.
sourceMap: The source map for the file if sourceMap: true was passed, as
a decoded object.
As with the Node Sass API, the synchronous functions will be substantially
faster than their asynchronous counterparts. Unfortunately the new API will not
support the fibers option for speeding up asynchronous compilation, since the
fibers package has been discontinued.
Loggers permalinkLoggers
The logger API gives you more fine-grained control over how and when warnings
and debug messages are emitted. Unlike other aspects of this proposal, a
logger option will also be added to the old API to allow you to control your
messages there without needing to upgrade to the new API immediately.
A logger implements the following interface:
interface Logger {
warn?(
message: string,
options: {
deprecation: boolean;
span?: SourceSpan;
stack?: string;
}
): void;
debug?(
message: string,
options: {span: SourceSpan}
): void;
}
The warn function handles warnings, including both warnings from the compiler
itself and from @warn rules. It’s passed:
The warning message
A flag indicating whether it’s specifically a deprecation warning
A span indicating where the warning was located, if it comes from a specific
location
The Sass stack trace at the point at which the warning was encountered, if it
was encountered during execution
The debug function handles only @debug rules, and is just passed the message
and the rule’s span. For more information on the SourceSpan type, see the
Logger proposal.
Sass will also provide a built-in logger, Logger.silent, that never emits any
messages. This will allow you to easily run Sass in “quiet mode” where no
warnings are ever surfaced.
Importers permalinkImporters
Rather than modeling importers as single-function callbacks, the new API models
them as objects that expose two methods: one that canonicalizes a URL, and one
that loads a canonical URL.
// Importers for compileAsync() and compileStringAsync() are the same, except
// they may return Promises as well.
interface Importer {
canonicalize(
url: string,
options: {fromImport: boolean}
): URL | null;
load(canonicalUrl: URL): ImporterResult | null;
}
Note that even stylesheets that are loaded directly from the filesystem through
compile() or loadPaths are treated as though they’re loaded by an importer.
This built-in filesystem importer canonicalizes all paths to file: URLs, and
loads those URLs from the physical filesystem.
Canonicalizing permalinkCanonicalizing
The first step determines the canonical URL for a stylesheet. Each stylesheet
has exactly one canonical URL that in turn refers to exactly one stylesheet. The
canonical URL must be absolute, including a scheme, but the specific structure
is up to the importer. In most cases, the stylesheet in question will exist on
disk and the importer will just return a file: URL for it.
The canonicalize() method takes a URL string that may be either relative or
absolute. If the importer recognizes that URL, it returns a corresponding
absolute URL (including a scheme). This is the canonical URL for the
stylesheet in question. Although the input URL may omit a file extension or
an initial underscore, the canonical URL must be fully resolved.
For a stylesheet that’s loaded from the filesystem, the canonical URL will be
the absolute file: URL of the physical file on disk. If it’s generated
in-memory, the importer should choose a custom URL scheme to guarantee that
its canonical URLs don’t conflict with any other importer’s.
For example, if you’re loading Sass files from a database, you might use the
scheme db:. The canonical URL for a stylesheet associated with key styles
in the database might be db:styles.
This function also takes a fromImport option that indicates whether the
importer is being invoked from an @import rule (as opposed to @use,
@forward, or meta.load-css()).
Having a canonical URL for each stylesheet allows Sass to ensure that the
same stylesheet isn’t loaded multiple times in the new module system.
Canonicalizing Relative Loads permalinkCanonicalizing Relative Loads
When a stylesheet tries to load a relative URL, such as @use "variables", it’s
not clear from the document itself whether that refers to a file that exists
relative to the stylesheet or to another importer or load path. Here’s how the
importer API resolves that ambiguity:
First, the relative URL is resolved relative to the canonical URL of the
stylesheet that contained the @use (or @forward or @import). For
example, if the canonical URL is file:///path/to/my/_styles.scss, then the
resolved URL will be file:///path/to/my/variables.
This URL is then passed to the canonicalize() method of the importer that
loaded the old stylesheet. (That means it’s important for your importers to
support absolute URLs!) If the importer recognizes it, it returns the
canonical value which is then passed to that importer’s load(); otherwise,
it returns null.
If the old stylesheet’s importer didn’t recognize the URL, it’s passed to all
the importers‘ canonicalize functions in the order they appear in options,
then checked for in all the loadPaths. If none of those recognizes it, the
load fails.
It’s important that local relative paths take precedence over other importers or
load paths, because otherwise your local stylesheets could get unexpectedly
broken by a dependency adding a file with a conflicting name.
Loading permalinkLoading
The second step actually loads the text of the stylesheet. The load()
method takes a canonical URL that was returned by canonicalize() and
returns the contents of the stylesheet at that URL. This is only called once
per compilation for each canonical URL; future loads of the same URL will
re-use either the existing module (for @use and @forward) or the parse
tree (for @import).
The load() method returns an object with the following fields:
css: The text of the loaded stylesheet.
syntax: The syntax of the file: 'scss', 'indented', or 'css'.
sourceMapUrl: An optional browser-accessible URL to include in source maps
when referring to this file.
FileImporter permalinkFileImporter
This proposal also adds a special type of importer known as a FileImporter.
This importer makes the common case of redirecting loads to somewhere on the
physical filesystem easier. It doesn’t require the caller to implement
load(), since that’s always going to be the same for files on disk.
interface FileImporter {
findFileUrl(
url: string,
options: {fromImport: boolean}
): FileImporterResult | null;
}
The findFileUrl() method takes a relative URL and returns an object with the
following fields:
url: The absolute file: URL of the file to load. This URL doesn’t need to
be fully canonicalized: the Sass compiler will take care of resolving
partials, file extensions, index files, and so on.
sourceMapUrl: An optional browser-accessible URL to include in source maps
when referring to this file.
Functions permalinkFunctions
The new function API’s function type is very similar to the old API’s:
type CustomFunctionCallback = (args: Value[]) => Value;
The only differences are:
Async functions return a Promise<Value> rather than calling a callback.
The value types themselves are different.
The second point is pretty substantial, though! The new value types are much
more fleshed out than the old versions. Let’s start with the parent class:
abstract class Value {
/**
* Returns the values of `this` when interpreted as a list.
*
* - For a list, this returns its elements.
* - For a map, this returns each of its key/value pairs as a `SassList`.
* - For any other value, this returns a list that contains only that value.
*/
get asList(): List<Value>;
/** Whether `this` is a bracketed Sass list. */
get hasBrackets(): boolean;
/** Whether `this` is truthy (any value other than `null` or `false`). */
get isTruthy(): boolean;
/** Returns JS's null if this is `sassNull`, or `this` otherwise. */
get realNull(): null | Value;
/** If `this` is a list, return its separator. Otherwise, return `null`. */
get separator(): ListSeparator;
/**
* Converts the Sass index `sassIndex` to a JS index into the array returned
* by `asList`.
*
* Sass indices start counting at 1, and may be negative in order to index
* from the end of the list.
*/
sassIndexToListIndex(sassIndex: Value): number;
/**
* Returns `this` if it's a `SassBoolean`, and throws an error otherwise.
*
* The `name` parameter is used for error reporting. It should match the name
* of a parameter passed to the custom function (without the `$`).
*/
assertBoolean(name?: string): SassBoolean;
/**
* Returns `this` if it's a `SassColor`, and throws an error otherwise.
*
* The `name` parameter is used for error reporting. It should match the name
* of a parameter passed to the custom function (without the `$`).
*/
assertColor(name?: string): SassColor;
/**
* Returns `this` if it's a `SassFunction`, and throws an error otherwise.
*
* The `name` parameter is used for error reporting. It should match the name
* of the parameter passed to the custom function (without the `$`).
*/
assertFunction(name?: string): SassFunction;
/**
* Returns `this` if it's a `SassMap` (or converts it to a `SassMap` if it's
* an empty list), and throws an error otherwise.
*
* The `name` parameter is used for error reporting. It should match the name
* of the parameter passed to the custom function (without the `$`).
*/
assertMap(name?: string): SassMap;
/**
* Returns `this` if it's a `SassNumber`, and throws an error otherwise.
*
* The `name` parameter is used for error reporting. It should match the name
* of a parameter passed to the custom function (without the `$`).
*/
assertNumber(name?: string): SassNumber;
/**
* Returns `this` if it's a `SassString`, and throws an error otherwise.
*
* The `name` parameter is used for error reporting. It should match the name
* of a parameter passed to the custom function (without the `$`).
*/
assertString(name?: string): SassString;
/**
* Returns the value of `this` if it can be interpreted as a map.
*
* - If this is a map, returns its contents.
* - If this is an empty list, returns an empty map.
* - Otherwise, returns `null`.
*/
tryMap(): OrderedMap<Value, Value> | null;
/** Returns whether `this == other` in SassScript. */
equals(other: Value): boolean;
}
There are a couple important things to note here:
Because CSS doesn’t have a strong syntactic differentiation between a single
element and a list containing one element, any Sass value may be treated as
though it’s a list. The Value makes it easy to follow this convention by
making the asList(), hasBrackets(), and separator() getters available
for every Value.
The list returned this was and the map returned by asMap() are immutable
types from the immutable package. This reflects Sass’s built-in
immutability of all its types. Although these values can’t be modified
directly, their APIs make it easy and efficient to create new values with
changes applied.
Sass’s list-indexing conventions are different than JavaScript’s. The
sassIndexToListIndex() function makes it easy to convert from Sass index to
JS index.
In Sass, any value may be used in a boolean context, with false
and null counting as “falsey” values. The isTruthy getter makes this
convention easy to follow.
The assert*() functions make it easy to ensure that you’re being passed the
arguments you expect, and to throw an idiomatic error if you’re not. They’re
particularly useful for TypeScript users since they’ll automatically narrow
the type of the Value.
Most Sass values have their own subclasses, but there are three singleton values
that are just available as constants: sassTrue, sassFalse, and sassNull
represent Sass’s true, false, and null values respectively.
Colors permalinkColors
The new API’s SassColor class provides access to colors in RGB, HSL, and HWB
format. As with built-in Sass color functions, any attribute can be accessed on
any color regardless of how it was initially created.
class SassColor extends Value {
/** Creates an RGB color. */
static rgb(
red: number,
green: number,
blue: number,
alpha?: number
): SassColor;
/** Creates an HSL color. */
static hsl(
hue: number,
saturation: number,
lightness: number,
alpha?: number
): SassColor;
/** Creates an HWB color. */
static hwb(
hue: number,
whiteness: number,
blackness: number,
alpha?: number
): SassColor;
/** The color's red channel. */
get red(): number;
/** The color's green channel. */
get green(): number;
/** The color's blue channel. */
get blue(): number;
/** The color's hue. */
get hue(): number;
/** The color's saturation. */
get saturation(): number;
/** The color's lightness. */
get lightness(): number;
/** The color's whiteness. */
get whiteness(): number;
/** The color's blackeness. */
get blackness(): number;
/** The color's alpha channel. */
get alpha(): number;
/**
* Returns a copy of `this` with the RGB channels updated to match `options`.
*/
changeRgb(options: {
red?: number;
green?: number;
blue?: number;
alpha?: number;
}): SassColor;
/**
* Returns a copy of `this` with the HSL values updated to match `options`.
*/
changeHsl(options: {
hue?: number;
saturation?: number;
lightness?: number;
alpha?: number;
}): SassColor;
/**
* Returns a copy of `this` with the HWB values updated to match `options`.
*/
changeHwb(options: {
hue?: number;
whiteness?: number;
blackness?: number;
alpha?: number;
}): SassColor;
/** Returns a copy of `this` with `alpha` as its alpha channel. */
changeAlpha(alpha: number): SassColor;
}
Numbers permalinkNumbers
The SassNumber class stores its numerator and denominator units as arrays
rather than strings. In addition, it provides methods for asserting that it has
specific units (assertNoUnits(), assertUnit()) and for converting it to
specific units (convert(), convertToMatch(), convertValue(),
convertValueToMatch(), coerce(), coerceValue(), coerceValueToMatch()).
Sass’s numeric logic is also subtly different from JS, since Sass considers
numbers that differ by less than the 10th decimal digit to be identical. This
API provides a number of methods that help convert between this and JavaScript’s
numeric logic.
class SassNumber extends Value {
/** Creates a Sass number with no units or a single numerator unit. */
constructor(value: number, unit?: string);
/** Creates a Sass number with multiple numerator and/or denominator units. */
static withUnits(
value: number,
options?: {
numeratorUnits?: string[] | List<string>;
denominatorUnits?: string[] | List<string>;
}
): SassNumber;
/** This number's value. */
get value(): number;
/**
* Whether `value` is an integer according to Sass's numeric logic.
*
* The integer value can be accessed using `asInt`.
*/
get isInt(): boolean;
/**
* If `value` is an integer according to Sass's numeric logic, returns the
* corresponding JS integer, or `null` if `value` isn't an integer.
*/
get asInt(): number | null;
/** This number's numerator units. */
get numeratorUnits(): List<string>;
/** This number's denominator units. */
get denominatorUnits(): List<string>;
/** Whether `this` has numerator or denominator units. */
get hasUnits(): boolean;
/**
* If `value` is an integer according to Sass's numeric logic, returns the
* corresponding JS integer, or throws an error if `value` isn't an integer.
*
* The `name` parameter is used for error reporting. It should match the name
* of the parameter passed to the custom function (without the `$`).
*/
assertInt(name?: string): number;
/**
* If `value` is between `min` and `max` according to Sass's numeric logic,
* returns it clamped to that range. Otherwise, throws an error.
*
* The `name` parameter is used for error reporting. It should match the name
* of the parameter passed to the custom function (without the `$`).
*/
assertInRange(min: number, max: number, name?: string): number;
/**
* Returns `this` if it has no units. Otherwise, throws an error.
*
* The `name` parameter is used for error reporting. It should match the name
* of a parameter passed to the custom function (without the `$`).
*/
assertNoUnits(name?: string): SassNumber;
/**
* Returns `this` if it has `unit` as its single (numerator) unit. Otherwise,
* throws an error.
*
* The `name` parameter is used for error reporting. It should match the name
* of a parameter passed to the custom function (without the `$`).
*/
assertUnit(name?: stringunit: string): SassNumber;
/** Returns whether `this` has the single numerator unit `unit`. */
hasUnit(unit: string): boolean;
/** Returns whether this number's units are compatible with `unit`. */
compatibleWithUnit(unit: string): boolean;
/**
* If this number's units are compatible with `newNumerators` and
* `newDenominators`, returns a new number with those units that's equal to
* `this`. Otherwise, throws an error.
*
* Note that unitless numbers are only compatible with other unitless numbers.
*/
convert(
newNumerators: string[] | List<string>,
newDenominators: string[] | List<string>
): SassNumber;
/**
* If this number's units are compatible with `other`'s, returns a new number
* with `other`'s units that's equal to `this`. Otherwise, throws an error.
*
* Note that unitless numbers are only compatible with other unitless numbers.
*/
convertToMatch(other: SassNumber): SassNumber;
/** Equivalent to `convert(newNumerators, newDenominators).value`. */
convertValue(
newNumerators: string[] | List<string>,
newDenominators: string[] | List<string>
): number;
/** Equivalent to `convertToMatch(other).value`. */
convertValueToMatch(other: SassNumber): number;
/**
* Like `convert()`, but if `this` is unitless returns a copy of it with the
* same value and the given units.
*/
coerce(
newNumerators: string[] | List<string>,
newDenominators: string[] | List<string>
): SassNumber;
/**
* Like `convertToMatch()`, but if `this` is unitless returns a copy of it
* with the same value and `other`'s units.
*/
coerceToMatch(other: SassNumber): SassNumber;
/** Equivalent to `coerce(newNumerators, newDenominators).value`. */
coerceValue(
newNumerators: string[] | List<string>,
newDenominators: string[] | List<string>
): number;
/** Equivalent to `coerceToMatch(other).value`. */
coerceValueToMatch(other: SassNumber): number;
}
Strings permalinkStrings
The SassString class provides access to information about whether or not the
string is quoted. As with lists, JS’s notion of indexes differs from Sass’s, so
it also provides the sassIndexToStringIndex() method to convert a JS index
into a Sass index.
class SassString extends Value {
/** Creates a string with the given `text`. */
constructor(
text: string,
options?: {
/** @default true */
quotes: boolean;
}
);
/** Creates an empty string`. */
static empty(options?: {
/** @default true */
quotes: boolean;
}): SassString;
/** The contents of `this`. */
get text(): string;
/** Whether `this` has quotes. */
get hasQuotes(): boolean;
/** The number of Unicode code points in `text`. */
get sassLength(): number;
/**
* Converts the Sass index `sassIndex` to a JS index into `text`.
*
* Sass indices start counting at 1, and may be negative in order to index
* from the end of the list. In addition, Sass indexes strings by Unicode code
* point, while JS indexes them by UTF-16 code unit.
*/
sassIndexToStringIndex(sassIndex: Value): number;
}
Lists permalinkLists
As mentioned above, most list functions are on the Value superclass to make it
easy to follow the Sass convention of treating all values as lists. However, the
SassList class can still be constructed to make new lists:
class SassList extends Value {
/** Creates a Sass list with the given `contents`. */
constructor(
contents: Value[] | List<Value>,
options?: {
/** @default ',' */
separator?: ListSeparator;
/** @default false */
brackets?: boolean;
}
);
/** Creates an empty Sass list. */
static empty(options?: {
/** @default null */
separator?: ListSeparator;
/** @default false */
brackets?: boolean;
}): SassList;
}
Maps permalinkMaps
The SassMap class simply exposes its contents as an OrderedMap from the
immutable package.
class SassMap extends Value {
/** Creates a Sass map with the given `contents`. */
constructor(contents: OrderedMap<Value, Value>);
/** Creates an empty Sass map. */
static empty(): SassMap;
/** Returns this map's contents. */
get contents(): OrderedMap<Value, Value>;
}
Functions permalinkFunctions
The SassFunction class is fairly restrictive: it just allows a new first-class
function to be created with a synchronous callback. These functions can’t be
invoked by custom functions—but they still provide more power than the old API!
class SassFunction extends Value {
/**
* Creates a Sass function value with the given `signature` that calls
* `callback` when it's invoked.
*/
constructor(
signature: string,
callback: CustomFunctionCallback
);
}
More Information permalinkMore Information
If you want to know more about these proposals and see their most up-to-date
forms, they’re available on GitHub to view in full:
Compile API proposal
Logger proposal
Importer proposal
Functions and values proposal
We’re eager for feedback, so please let us know what you think! The proposals
in question will be open for at least a month after this blog post goes live,
and possibly more depending on how lively the discussion around them is.
