sass

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 how stylesheets are loaded and 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 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.

• compile and compileAsync take a path to a Sass file and return the result of compiling that file to CSS. These functions accept an additional 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);
  Copy

• compileString and 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 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);
  Copy

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 LegacyFileOptions or a string of Sass code by passing in a LegacyStringOptions.

• renderSync runs synchronously. It's by far the fastest option when using Dart Sass, but at the cost of only supporting synchronous importer and function plugins.

  const sass = require('sass'); // or require('node-sass');
  
  const result = sass.renderSync({file: "style.scss"});
  console.log(result.css.toString());
  Copy

• render runs asynchronously and calls a callback when it finishes. It's much slower when using Dart Sass, but it supports asynchronous importer and 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());
    }
  });
  Copy