4.0 KiB
The sass
package on npm is a pure-JavaScript package built from the Dart
Sass implementation. In addition to Dart Sass's command-line interface, it
provides a JavaScript API that can be used to drive Sass compilations from
JavaScript. It even allows an application to control {@link Options.importers |
how stylesheets are loaded} and {@link Options.functions | define custom
functions}.
Usage
The JavaScript API provides two entrypoints for compiling Sass to CSS, each of
which has a synchronous variant that returns a plain {@link CompileResult} and
an asynchronous variant that returns a Promise
. The asynchronous variants
are much slower, but they allow custom importers and functions to run
asynchronously.
-
{@link compile} and {@link compileAsync} take a path to a Sass file and return the result of compiling that file to CSS. These functions accept an additional {@link Options} argument.
const sass = require('sass'); const result = sass.compile("style.scss"); console.log(result.css); const compressed = sass.compile("style.scss", {style: "compressed"}); console.log(compressed.css);
-
{@link compileString} and {@link compileStringAsync} take a string that represents the contents of a Sass file and return the result of compiling that file to CSS. These functions accept an additional {@link StringOptions} argument.
const sass = require('sass'); const input = ` h1 { font-size: 40px; code { font-face: Roboto Mono; } }`; const result = sass.compileString(input); console.log(result.css); const compressed = sass.compileString(input, {style: "compressed"}); console.log(compressed.css);
Integrations
Most popular Node.js build systems have integrations available for the JS API:
- Webpack uses the
sass-loader
package. - Gulp uses the
gulp-sass
package. - Broccoli uses the
broccoli-sass-source-maps
package. - Ember uses the
ember-cli-sass
package. - Grunt uses the
grunt-sass
package.
Legacy API
The sass
package also supports an older API. Although this API is deprecated,
it will continue to be supported until the release of version 2.0.0 of the
sass
package. The legacy API is also supported by the node-sass
package,
which is a native extension wrapper for the deprecated LibSass implementation.
The legacy API has two entrypoints for compiling Sass to CSS. Each one can compile either a Sass file by passing in {@link LegacyFileOptions} or a string of Sass code by passing in a {@link LegacyStringOptions}.
-
{@link renderSync} runs synchronously. It's by far the fastest option when using Dart Sass, but at the cost of only supporting synchronous {@link LegacyImporter | importer} and {@link LegacyFunction | function} plugins.
const sass = require('sass'); // or require('node-sass'); const result = sass.renderSync({file: "style.scss"}); console.log(result.css.toString());
-
{@link render} runs asynchronously and calls a callback when it finishes. It's much slower when using Dart Sass, but it supports asynchronous {@link LegacyImporter | importer} and {@link LegacyFunction | function} plugins.
const sass = require('sass'); // or require('node-sass'); sass.render({ file: "style.scss" }, function(err, result) { if (err) { // ... } else { console.log(result.css.toString()); } });