sass-embedded

What is sass-embedded?

The sass-embedded npm package provides a way to compile Sass (Syntactically Awesome Style Sheets) using the Embedded Sass protocol. This allows for faster compilation and better integration with JavaScript environments.

What are sass-embedded's main functionalities?

Compile Sass to CSS

This feature allows you to compile Sass code into CSS. The example demonstrates how to compile a simple Sass string into CSS using the `compileString` method.

const sass = require('sass-embedded');

const result = sass.compileString(`
$primary-color: #333;
body {
  color: $primary-color;
}
`);

console.log(result.css);

Compile Sass from a file

This feature allows you to compile Sass from a file. The example shows how to read a Sass file, compile it, and then write the resulting CSS to an output file.

const sass = require('sass-embedded');
const fs = require('fs');

const result = sass.compile('path/to/your/file.scss');

fs.writeFileSync('path/to/output.css', result.css);

Custom Importers

This feature allows you to define custom importers to handle `@import` statements in Sass files. The example demonstrates how to create a custom importer that replaces the content of an import with a specific string.

const sass = require('sass-embedded');

const result = sass.compileString(`
@import 'custom';
body {
  color: red;
}
`, {
  importers: [
    {
      findFileUrl(url) {
        if (url === 'custom') {
          return new URL('data:text/plain,body { color: blue; }');
        }
        return null;
      }
    }
  ]
});

console.log(result.css);

Other packages similar to sass-embedded

node-sass

node-sass is a library that provides binding for Node.js to LibSass, the C version of the popular stylesheet preprocessor, Sass. It is similar to sass-embedded in that it allows you to compile Sass to CSS, but it uses a different underlying technology (LibSass vs. Embedded Sass). node-sass is known for its speed but can be more difficult to set up due to native dependencies.

sass

sass is the official JavaScript implementation of Sass, written in Dart and compiled to JavaScript. It is similar to sass-embedded in terms of functionality, providing a way to compile Sass to CSS. However, it does not use the Embedded Sass protocol and can be slower in some cases compared to sass-embedded.

README

Embedded Sass Host

This package is an alternative to the sass package. It supports the same JS API as sass and is maintained by the same team, but where the sass package is pure JavaScript, sass-embedded is instead a JavaScript wrapper around a native Dart executable. This means sass-embedded will generally be much faster especially for large Sass compilations, but it can only be installed on the platforms that Dart supports: Windows, Mac OS, and Linux.

Despite being different packages, both sass and sass-embedded are considered "Dart Sass" since they have the same underlying implementation. Since the first stable release of the sass-embedded package, both packages are released at the same time and share the same version number.

Usage

This package provides the same JavaScript API as the sass package, and can be used as a drop-in replacement:

const sass = require('sass-embedded');

const result = sass.compile(scssFilename);

// OR

const result = await sass.compileAsync(scssFilename);

Unlike the sass package, the asynchronous API in sass-embedded will generally be faster than the synchronous API since the Sass compilation logic is happening in a different process.

See the Sass website for full API documentation.

Legacy API

The sass-embedded package also supports the older JavaScript API that's fully compatible with Node Sass (with a few exceptions listed below), with support for both the render() and renderSync() functions. This API is considered deprecated and will be removed in Dart Sass 2.0.0, so it should be avoided in new projects.

Sass's support for the legacy JavaScript API has the following limitations:

• Only the "expanded" and "compressed" values of outputStyle are supported.

• The sass-embedded package doesn't support the precision option. Dart Sass defaults to a sufficiently high precision for all existing browsers, and making this customizable would make the code substantially less efficient.

• The sass-embedded package doesn't support the [sourceComments] option. Source maps are the recommended way of locating the origin of generated selectors.

• The sass-embedded package doesn't support the indentWidth, indentType, or linefeed options. It implements the legacy API as a wrapper around the new API, and the new API has dropped support for these options.

How Does It Work?

The sass-embedded runs the Dart Sass embedded compiler as a separate executable and uses the Embedded Sass Protocol to communicate with it over its stdin and stdout streams. This protocol is designed to make it possible not only to start a Sass compilation, but to control aspects of it that are exposed by an API. This includes defining custom importers, functions, and loggers, all of which are invoked by messages from the embedded compiler back to the host.

Although this sort of two-way communication with an embedded process is inherently asynchronous in Node.js, this package supports the synchronous compile() API using a custom synchronous message-passing library that's implemented with the Atomics.wait() primitive. We hope to release this library as a stand-alone package at some point in the future.

---

Disclaimer: this is not an official Google product.

Changelog

1.78.0

• The meta.feature-exists function is now deprecated. This deprecation is named feature-exists.

• Fix a crash when using @at-root without any queries or children in the indented syntax.

JS API

• Backport the deprecation options (fatalDeprecations, futureDeprecations, and silenceDeprecations) to the legacy JS API. The legacy JS API is itself deprecated, and you should move off of it if possible, but this will allow users of bundlers and other tools that are still using the legacy API to still control deprecation warnings.

• Fix a bug where accessing SourceSpan.url would crash when a relative URL was passed to the Sass API.

Embedded Sass

• Explicitly expose a sass executable from the sass-embedded npm package. This was intended to be included in 1.63.0, but due to the way platform-specific dependency executables are installed it did not work as intended. Now users can run npx sass for local installs or just sass when sass-embedded is installed globally.

• Add linux-riscv64, linux-musl-riscv64, and android-riscv64 support for the sass-embedded npm package.

• Fix an edge case where the Dart VM could hang when shutting down when requests were in flight.

• Fix a race condition where the embedded host could fail to shut down if it was closed around the same time a new compilation was started.

• Fix a bug where parse-time deprecation warnings could not be controlled by the deprecation options in some circumstances.