The Sass JavaScriptAPI can be used to to drive Sass Compilations fromJavaScript. It even allows an application to controlhow stylesheets are loaded anddefine custom functions.

Thesass package on npm is a pure-JavaScript package built from theDartSass implementation, and includes Dart Sass'scommand-line interface.

Thesass-embedded package on npm is a JavaScript wrapper around a nativeDart executable, and in general is faster thansass.

Bothsass andsass-embedded provide the same JavaScriptAPI using the sameunderlyingDart Sass implementation, but have speed and platform tradeoffs.

Usage

The JavaScriptAPI provides two entrypoints for compiling Sass toCSS, each ofwhich has a synchronous variant that returns a plainCompileResult andan asynchronous variant that returns aPromise.The asynchronous variantsare much slower, but they allow custom importers and functions to run asynchronously.

• compile andcompileAsync take a path to a Sass file and returnthe result of compiling that file toCSS. These functions accept an additionalOptions argument.

  constsass =require('sass');
  
  constresult =sass.compile("style.scss");
  console.log(result.css);
  
  constcompressed =sass.compile("style.scss", {style:"compressed"});
  console.log(compressed.css);Copy

• compileString andcompileStringAsync take a string thatrepresents the contents of a Sass file and return the result of compiling thatfile toCSS. These functions accept an additionalStringOptions argument.

  constsass =require('sass');
  
  constinput =`
  h1 {
    font-size: 40px;
    code {
      font-face: Roboto Mono;
    }
  }`;
  
  constresult =sass.compileString(input);
  console.log(result.css);
  
  constcompressed =sass.compileString(input, {style:"compressed"});
  console.log(compressed.css);Copy

Integrations

Most popular Node.js build systems have integrations available for theJS API:

• Webpack uses thesass-loader package.
• Gulp uses thegulp-sass package.
• Broccoli uses thebroccoli-sass-source-maps package.
• Ember uses theember-cli-sass package.
• Grunt uses thegrunt-sass package.

LegacyAPI

Thesass package also supports an olderAPI. Although thisAPI is deprecated,it will continue to be supported until the release of version 2.0.0 of thesass package. The legacyAPI is also supported by thenode-sass package,which is a native extension wrapper for the deprecatedLibSass implementation.

The legacyAPI has two entrypoints for compiling Sass toCSS. Each one cancompile either a Sass file by passing inLegacyFileOptions or a stringof Sass code by passing in aLegacyStringOptions.

• renderSync runs synchronously. It'sby far the fastest option whenusing Dart Sass, but at the cost of only supporting synchronousimporter andfunction plugins.

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

• render runs asynchronously and calls a callback when it finishes. It'smuch slower when using Dart Sass, but it supports asynchronousimporter andfunction plugins.

  constsass =require('sass');// or require('node-sass');
  
  sass.render({
  file:"style.scss"
  },function(err,result) {
  if (err) {
  // ...
    }else {
  console.log(result.css.toString());
    }
  });Copy

Speed

While multiple factors go into how long Sass compilations take, there aregeneral speed trends that can help you minimize your compilation time.

With thesass package

With thesass package, the synchronous calls will be faster than asynchronouscalls due to the overhead of making the entire evaluation process asynchronous.While theCompiler andAsyncCompiler class are available, theyaren't faster than than the module-level compilation methods when usingsass.

With thesass-embedded package

Thesass-embedded package provides significant speed improvements in certainsituations, and is generally faster thansass for large or frequentcompilations. When using the module-level compilation methods, asynchronouscalls are generally faster than synchronous ones due to the overhead ofemulating synchronous messaging with worker threads and concurrent compilationsbeing blocked on the main thread.

TheCompiler andAsyncCompiler classes provide significantimprovements when using thesass-embedded package. These classes persist andreuse a single Dart process across multiple compilations, avoiding the need torepeatedly start up and tear down a process.

When compiling a single file usingsass-embedded, there is not much differencebetween the synchronous and asynchronous methods. When running multiplecompilations at the same time, anAsyncCompiler will be considerablyfaster than a synchronousCompiler.

Other factors like Functions, Importers and the complexity ofyour Sass files may also impact what compilation methods work best for yourparticular use case.