sass/js-api-doc

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