Sass Blog

New JS API Release Candidate is Live

2021年11月21日T00:15:00+00:00

The new JavaScript API that we announced a few months ago is now fully implemented in Dart Sass and ready for you to try! The new API is designed to be more idiomatic, performant, and usable than the old one, and we hope it’ll be adopted swiftly by tooling packages.

Because this is such a substantial addition, we want to give users a chance to kick the tires a bit before we set it in stone, so we’ve released it as a release candidate in Dart Sass 1.45.0-rc.1. Download it, try it out, and let us know what you think by filing issues or sending us a tweet. Unless major changes are necessary, we plan to make a stable release some time next week.

How to use it permalinkHow to use it

The new API comes with four new entrypoint functions: compile() and compileAsync() take Sass file paths and return the result of compiling them to CSS, while compileString() and compileStringAsync() take a string of Sass source and compile it to CSS. Unlike the old API, the async functions all return Promises. As with the old API, the synchronous functions are substantially faster than their async counterparts, so we recommend using them if at all possible.

const sass = require('sass');
const result = sass.compileString(`
h1 {
 font-size: 40px;
 code {
 font-face: Roboto Mono;
 }
}`);
console.log(result.css);

Check out the API docs for more details on the API, including the brand-new importer and custom function APIs.

What about the old API? permalinkWhat about the old API?

Once the new API has a stable release, we’ll officially consider the old API to be deprecated. Since it’s still widely-used, we’ll continue to maintain it for a good long while going forward. Expect it to start printing a deprecation warning in a year or so, and to be disabled for good once we release Dart Sass 2.0.0.

Request for Comments: New JS API

2021年08月05日T23:30:00+00:00

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 permalink`FileImporter`

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:

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.

The Discontinuation of node-fibers

2021年03月26日T23:00:00+00:00

We have recently received the unfortunate but not entirely surprising news that the node-fibers package has reached its end-of-life and will not be updated for compatibility with Node 16. Dart Sass has historically allowed JavaScript users to pass in node-fibers to improve the performance of the asynchronous render() method, but going forward this will unfortunately no longer be an option in Node 16 and on.

There are a number of alternative options for reclaiming this lost performance, some of them which are available today, some which are in development, and some which are theoretical but could be made real with pull requests from users like you. Sadly, none of the options that are ready today are drop-in solutions with the same level of ease-of-use as node-fibers, so if that performance is crucial to you we recommend staying on Node 14 for the time being.

What Happened? permalinkWhat Happened?

In order to understand how we got here, it’s important to know two pieces of history. First, why does Dart Sass use node-fibers in the first place? And second, why is node-fibers dying?

This section is fairly technical, so feel free to skip ahead if you don’t care about the gory details.

Fibers in Sass permalinkFibers in Sass

Dart Sass inherited its JavaScript API from the now-deprecated Node Sass. This API has two main functions for compiling Sass files: renderSync() which synchronously returned the compiled CSS, and render() which instead takes a callback to which it passes the compiled CSS asynchronously. Only render() allowed asynchronous plugins, including widely-used importers such as webpack’s sass-loader, so render() became very widely used in practice.

For Node Sass, the performance difference between render() and renderSync() was negligible, because it was built on C++ code which had few restrictions on how it handled asynchrony. However, Dart Sass runs as pure JavaScript, which makes it subject to JavaScript’s strict async rules. Asynchrony in JavaScript is contagious, which means that if any function (such as an importer plugin) is asynchronous, then everything that calls it must be asynchronous, and so on until the entire program is asynchronous.

And asynchrony in JavaScript isn’t free. Every asynchronous function call has to allocate callbacks, store them somewhere, and take a trip back to the event loop before invoking those callbacks, and that all takes time. In fact, it takes enough time that the asynchronous render() in Dart Sass tends to be 2-3x slower than renderSync().

Enter fibers. Fibers are a very cool concept, available in languages like Ruby and C++, that give the programmer more control over asynchronous functions. They can even allow a chunk of synchronous code (such as the Sass compiler) to call asynchronous callbacks (such as the webpack plugin). The node-fibers package did some arcane magick with the V8 virtual machine to implement Fibers in JavaScript, which allowed Dart Sass to use the fast synchronous code to implement the asynchronous render() API. And for a time, it was great.

The Death of Fibers permalinkThe Death of Fibers

Unfortunately, the arcane magick that node-fibers used involved accessing some parts of V8 that were not officially part of its public API. There was no guarantee that the interfaces they were using would stay the same from release to release, and indeed they tended to change fairly regularly. For a long time, those changes were small enough that it was possible to release a new version of node-fibers that supported them, but with Node.js 16 the luck ran out.

The latest version of V8 involves some major overhauls to its internals. These will eventually allow it to implement some cool improvements, so its hard to begrudge, but a side effect is that the APIs node-fibers was using are completely gone without an obvious replacement. This is no one’s fault: since those interfaces weren’t part of V8’s public API, they were under no obligation to keep them stable. Sometimes in software that’s just the way things go.

Reclaiming Performance permalinkReclaiming Performance

There are a few options for getting back the performance that’s lost by no longer being able to pass node-fibers to sass.render(). In order from nearest to longest term:

Avoid Asynchronous Plugins permalinkAvoid Asynchronous Plugins

This is something you can do today. If it’s at all possible to make the plugins you pass in to Sass synchronous, you can use the renderSync() method which doesn’t need fibers to go fast. This may require rewriting some existing plugins, but it will pay dividends immediately.

Embedded Dart Sass permalinkEmbedded Dart Sass

While it’s not ready for prime-time yet, the Sass team is working on a project called “embedded Dart Sass”. This involves running Dart Sass as a subprocess, rather than a library, and communicating with it using a special protocol. This provides several important improvements over the existing alternatives:

Unlike running sass from the command line, this will still work with plugins like the webpack importer. In fact, we plan to match the existing JavaScript API as closely as possible. This will probably run asynchronous plugins even faster than synchronous ones.
Unlike the existing JS-compiled version, this will use the Dart VM. Due to the more static nature of the Dart language, the Dart VM runs Sass substantially faster than Node.js, which will provide about a 2x speed improvement for large stylesheets.

The Node.js host for Embedded Sass is still in active development, but there’s a beta release available (with minimal features) if you want to kick the tires.

Worker Threads permalinkWorker Threads

We’ve explored the possibility of running the pure-JS Dart Sass in a Node.js worker thread. Worker threads work a bit like fibers in that they make it possible for synchronous code to wait for asynchronous callbacks to run. Unfortunately, they’re also extremely restrictive about what sorts of information can be passed across the thread boundary, which makes it much harder to use them to wrap a complex API like Sass’s.

At the moment, the Sass team is focused on Embedded Sass, so we don’t have the spare bandwidth to dive into worker threads as an alternative. That said, we’d be happy to help a motivated user implement this. If you’re interested, follow up on the GitHub issue!

Reanimating node-fibers permalinkReanimating `node-fibers`

There’s one other potential solution, although it would take true dedication to turn into reality. It would in principle be possible to add a new API to V8 that would officially support the hooks node-fibers needs to do its good work. This would allow the package to return gloriously to life and Sass to make render() fast on into the future.

The Sass team has contacted both the V8 team and the owner of node-fibers, and both of them are amenable to this idea in principle. While neither one has the time to see it through to completion themselves, they’ve expressed willingness to help an engineer who’s willing to give it a shot.

This isn’t a contribution for the faint of heart, though: it requires knowledge of C++, a willingness to learn at least the basics of the node-fibers codebase and V8’s isolate APIs, and skills in both API design and human interaction to negotiate a stable API that will meet the needs of node-fibers and that the V8 team feels comfortable committing to maintain. But if you’re interested, please don’t hesitate to reach out!

Request for Comments: First-Class Calc

2021年03月15日T09:35:00+00:00

One of the absolutely most-requested features in Sass is the ability to more easily work with calc() expressions. These expressions have historically been parsed opaquely: between the parentheses, you can put any text at all, and Sass will just treat it as an unquoted string. This has simplified Sass’s parser, since we don’t have to support the specific calc() microsyntax, and it’s meant that we automatically support new features like the use of CSS variables within calc().

However, it comes at a substantial usability cost as well. Because each calc() is totally opaque to Sass’s parser, users can’t simply use Sass variables in place of values; they have to interpolate variables explicitly. And once a calc() expression has been created, there’s no way to manipulate it with Sass the way you can manipulate a plain number.

We’re looking to change that with a new proposal we call “First-Class Calc”. This proposal changes calc() (and other supported mathematical functions) from being parsed as unquoted strings to being parsed in-depth, and sometimes (although not always) producing a new data type known as a “calculation”. This data type represents mathematical expressions that can’t be resolved at compile-time, such as calc(10% + 5px), and allows those expressions to be combined gracefully within further mathematical functions.

To be more specific: a calc() expression will be parsed according to the CSS syntax, with additional support for Sass variables, functions, and (for backwards compatibility) interpolation. Sass will perform as much math as possible at compile-time, and if the result is a single number it will return it as a normal Sass number type. Otherwise, it will return a calculation that represents the (simplified) expression that can be resolved in the browser.

For example:

calc(1px + 10px) will return the number 11px.
Similarly, if $length is 10px, calc(1px + $length) will return 11px.
However, calc(1px + 10%) will return the calc calc(1px + 10%).
If $length is calc(1px + 10%), calc(1px + $length) will return calc(2px + 10%).
Sass functions can be used directly in calc(), so calc(1% + math.round(15.3px)) returns calc(1% + 15px).

Note that calculations cannot generally be used in place of numbers. For example, 1px + calc(1px + 10%) will produce an error, as will math.round(calc(1px + 10%)). This is because calculations can’t be used interchangeably with numbers (you can’t pass a calculation to math.sqrt()), so we want to make sure mathematical functions are explicit about whether or not they support calculations by either wrapping all of their math in calc() or using normal Sass arithmetic.

For backwards compatibility, calc() expressions that contain interpolation will continue to be parsed using the old highly-permissive syntax, although this behavior will eventually be deprecated and removed. These expressions will still return calculation values, but they’ll never be simplified or resolve to plain numbers.

Let us know what you think! permalinkLet us know what you think!

If you’re interested in learning more about this proposal, read it in full on GitHub. It’s open for comments and revisions for the next month, so if you’d like to see something change please file an issue and we can discuss it!

LibSass is Deprecated

2020年10月26日T20:00:00+00:00

After much discussion among the Sass core team, we’ve come to the conclusion that it’s time to officially declare that LibSass and the packages built on top of it, including Node Sass, are deprecated. For several years now, it’s been clear that there’s simply not enough engineering bandwidth behind LibSass to keep it up-to-date with the latest developments in the Sass language (for example, the most recent new language feature was added in November 2018). As much as we’ve hoped to see this pattern turn around, even the excellent work of long-time LibSass contributors Michael Mifsud and Marcel Greter couldn’t keep up with the fast pace of language development in both CSS and Sass.

I’ll go into detail about what this means below, but here are the major points:

We no longer recommend LibSass for new Sass projects. Use Dart Sass instead.
We recommend all existing LibSass users make plans to eventually move onto Dart Sass, and that all Sass libraries make plans to eventually drop support for LibSass.
We’re no longer planning to add any new features to LibSass, including compatibility with new CSS features.
LibSass and Node Sass will continue to be maintained indefinitely on a best-effort basis, including fixing major bugs and security issues and maintaining compatibility with the latest Node versions.

Why deprecate? permalinkWhy deprecate?

For several years now, Sass has managed to exist in an ambiguous kind of state where LibSass was an officially-supported implementation in theory, but its feature surface was static in practice. As time has gone on, it’s becoming increasingly clear that this state causes substantial concrete problems for Sass users. For example, we regularly see users confused as to why plain-CSS min() and max() don’t work and assuming Sass as a whole is at fault, when in fact it’s only LibSass that doesn’t support that feature.

Official support for LibSass doesn’t just cause pain for individual users. Because LibSass doesn’t support the Sass module system that launched last year, major shared Sass libraries have been unable to use it for fear that their downstream users would be incompatible. By clearly indicating that all Sass users should eventually move off of LibSass, we hope to make it more feasible for these library authors to use more modern features.

LibSass has even inhibited the development of the Sass language itself. We’ve been unable to move forward with the proposal for treating / as a separator because any code they’d write would either produce deprecation warnings in Dart Sass or fail to compile in LibSass. By marking LibSass as deprecated, this becomes much more feasible, and Sass becomes much better at supporting the latest versions of CSS.

What does "deprecated" mean? permalinkWhat does "deprecated" mean?

We’re choosing to use the term “deprecated” because it carries a lot of weight in the programming community, and provides a strong signal that users should start planning to move away from LibSass. However, it doesn’t mean that the project is entirely dead. Michael Mifsud, the lead maintainer of LibSass and Node Sass, has affirmed that he plans to continue maintenance on the same level as the past few years. This means that although there will be no more features added (and as such LibSass will slowly drift further and further out of compatibility with the latest CSS and Sass syntax), there will continue to be maintenance releases indefinitely.

What about portability and performance? permalinkWhat about portability and performance?

LibSass today has two major benefits over Dart Sass:

Portability: since it’s written in C++, it’s easy to embed LibSass within other programming languages and provide a native-feeling API.
Performance: calling out to LibSass via the C++ API is very fast relative to the speeds of code written directly in scripting languages. In particular, this means LibSass is substantially faster in JavaScript than Dart Sass-compiled-to-JS (although it’s comparable to Dart Sass’s command-line executable).

We’re working on addressing both of those with the Sass embedded protocol, which runs a Sass compiler as a subprocess that can communicate with any host language via message-passing. The embedded protocol supports all the features of a native Sass API, including the ability to define custom importers and Sass functions, while also providing the high performance of the CLI app. Dart Sass has already implemented the compiler side of the embedded protocol, and a JavaScript host for it is in active development.

How do I migrate? permalinkHow do I migrate?

If you’re a user of Node Sass, migrating to Dart Sass is straightforward: just replace node-sass in your package.json file with sass. Both packages expose the same JavaScript API.

If you’re using the SassC command-line interface, you can switch to Dart Sass’s CLI. Note that this doesn’t have exactly the same interface as SassC, so you may need to change a few flags.

If you’re using LibSass through a wrapper library in another language, you can either switch to the Dart Sass CLI or ask the maintainer of the LibSass wrapper to convert it to a host for the Sass embedded protocol. The embedded protocol allows any language to provide a native API that calls out to Dart Sass.

Please note that because activity on LibSass has been low for several years, it has a number of outstanding bugs and behavioral variations from the Sass spec. You may need to make minor updates to stylesheets to make them compatible with Dart Sass. See this list of major compatibility issues for reference.

Thank you permalinkThank you

Finally, I want to thank everyone who’s put so much time and energy into LibSass and Node Sass over the years. It will always be a towering achievement, and Sass’s popularity outside of the Ruby community is undoubtedly due in large part to its existence. Many people have tried to implement Sass only to find that the language is much deeper and more complex than they expected, and LibSass alone among all of those implementations managed to become fully-featured enough to provide real value for thousands if not millions of users. These maintainers deserve to be proud of that work, and I hope they’ll always consider themselves part of the Sass community going forward.

Request for Comments: HWB Functions

2020年10月07日T00:00:00+00:00

The CSS working group has been up to all sorts of exciting stuff recently in the Color Level 4 spec, and the Sass team is starting to think about how to integrate those cool new features into Sass’s color model. We need more time to hammer out exactly the right designs for complex features like the Lab color space, but that doesn’t mean we can’t add a few new color goodies.

Today we’re announcing a proposal for one such feature: built-in Sass functions for HWB colors! Once this proposal (drafted by Sass core team member Miriam Suzanne) is accepted and implemented, you’ll be able to write colors in HWB syntax and adjust their whiteness and blackness the same way you can adjust a color’s saturation and lightness today.

The Functions permalinkThe Functions

Here are the new and improved functions this proposal adds:

color.hwb() permalink`color.hwb()`

The color.hwb() function defines a color using its hue, whiteness, and blackness. Like the existing rgb() and hsl() functions, It can either use the space-separated syntax defined in the spec (hwb(270 20% 40%)) or the more Sass-y comma-separated syntax (hwb(270, 20%, 40%)). Because HWB colors use the same sRGB colorspace as all other Sass color values, colors created this way are fully compatible with all existing Sass color functions and will be emitted as their RGB equivalents for maximum browser compatibility.

Note that unlike rgb() and hsl(), the proposal doesn’t add this function to the global scope yet. This is because Sass has a policy of never adding support for new CSS syntax before at least one browser implements it. Specs have a tendency to change until they’re locked in by browsers, and if Sass ends up supporting something different than the browsers themselves that’s bad news!

color.whiteness() and color.blackness() permalink`color.whiteness()` and `color.blackness()`

These functions work like the color.saturation() and color.lightness() functions do for HSL colors. They even work for colors that weren’t created with color.hwb(), so you can use them to check how pale or dark any color is.

Because HWB colors have the same notion of “hue” as HSL colors, the existing color.hue() function already works perfectly!

color.scale(), color.adjust(), and color.change() permalink`color.scale()`, `color.adjust()`, and `color.change()`

All three color modification functions now support $whiteness and $blackness arguments. If you want a color (again no matter how it was created) to be 20% whiter, just pass it to color.scale($color, $whiteness: 20%) and there you go!

Sass Blog

New JS API Release Candidate is Live

How to use it permalinkHow to use it

What about the old API? permalinkWhat about the old API?

Request for Comments: New JS API

Why a New API? permalinkWhy a New API?

Compilation permalinkCompilation

Loggers permalinkLoggers

Importers permalinkImporters

Canonicalizing permalinkCanonicalizing

Canonicalizing Relative Loads permalinkCanonicalizing Relative Loads

Loading permalinkLoading

FileImporter permalinkFileImporter

Functions permalinkFunctions

Colors permalinkColors

Numbers permalinkNumbers

Strings permalinkStrings

Lists permalinkLists

Maps permalinkMaps

Functions permalinkFunctions

More Information permalinkMore Information

The Discontinuation of node-fibers

What Happened? permalinkWhat Happened?

Fibers in Sass permalinkFibers in Sass

The Death of Fibers permalinkThe Death of Fibers

Reclaiming Performance permalinkReclaiming Performance

Avoid Asynchronous Plugins permalinkAvoid Asynchronous Plugins

Embedded Dart Sass permalinkEmbedded Dart Sass

Worker Threads permalinkWorker Threads

Reanimating node-fibers permalinkReanimating node-fibers

Request for Comments: First-Class Calc

Let us know what you think! permalinkLet us know what you think!

LibSass is Deprecated

Why deprecate? permalinkWhy deprecate?

What does "deprecated" mean? permalinkWhat does "deprecated" mean?

What about portability and performance? permalinkWhat about portability and performance?

How do I migrate? permalinkHow do I migrate?

Thank you permalinkThank you

Request for Comments: HWB Functions

The Functions permalinkThe Functions

color.hwb() permalinkcolor.hwb()

color.whiteness() and color.blackness() permalinkcolor.whiteness() and color.blackness()

color.scale(), color.adjust(), and color.change() permalinkcolor.scale(), color.adjust(), and color.change()

Let us know what you think! permalinkLet us know what you think!

FileImporter permalink`FileImporter`

Reanimating node-fibers permalinkReanimating `node-fibers`

color.hwb() permalink`color.hwb()`

color.whiteness() and color.blackness() permalink`color.whiteness()` and `color.blackness()`

color.scale(), color.adjust(), and color.change() permalink`color.scale()`, `color.adjust()`, and `color.change()`