Migrating UsageMigrating Usage permalink

EntrypointsEntrypoints permalink

The legacyJSAPI had two entrypoints for compiling Sass:render andrenderSync, which took in an options object that included eitherfile (tocompile a file) ordata (to compile a string). The modernAPI has four:compile andcompileAsync for compiling a file andcompileString andcompileStringAsync for compiling a string. These functions take a path orsource string as their first argument and then an object of all other optionsas their second argument. Unlikerender, which used a callback,compileAsyncandcompileStringAsync return a promise instead.

See theusage documentation for more details.

ImportersImporters permalink

Importers in the legacyAPI consisted of a single function that took in thedependency ruleURL and theURL of the containing stylesheet (as well as adone callback for asynchronous importers) and return an object with eitherafile path on disk or thecontents of the stylesheet to be loaded.

ModernAPIImporters instead contain two methods:canonicalize, which takesin a ruleURL and returns the canonical form of thatURL; andload, whichtakes in a canonicalURL and returns an object with the contentsof the loaded stylesheet. This split ensures that the same module is onlyloaded once and that relative URLs work consistently. Asynchronous importershave both of these methods return promises.

There’s also a specialFileImporter that redirects all loads to existingfiles on disk, which should be used when migrating from legacy importers thatreturned afile instead ofcontents.

Custom FunctionsCustom Functions permalink

In the legacyJSAPI, custom functions took a separateJS argument for eachSass argument, with an additionaldone callback for asynchronous customfunctions. In the modernAPI, custom functions instead take a singleJS argumentthat contains a list of all Sass arguments, with asynchronous custom functionsreturning a promise.

The modernAPI also uses a much more robustValue class that supports allSass value types, type assertions, and easy map and list lookups.

BundlersBundlers permalink

If you’re using a bundler or other tool that calls the SassAPI rather thanusing it directly, you may need to change the configuration you pass to thattool to tell it to use the modern API.

Webpack should already use the modernAPI by default, but if you’re gettingwarnings, setapi to"modern" or"modern-compiler".SeeWebpack’s documentation for more details.

Vite 6 uses the modernAPI by default. Previous versions of Vite still use thelegacyAPI, however from Vite 5.4 you can switch it by settingapi to"modern" or"modern-compiler". SeeVite’s documentation for more details.

For other tools, check their documentation or issue tracker for informationabout supporting the modern Sass API.

Silencing WarningsSilencing Warnings permalink

While the legacyJSAPI was marked as deprecated in Dart Sass 1.45.0 alongsidethe release of the modernAPI, we began emitting warnings for using it startingin Dart Sass 1.79.0. If you’re not yet able to migrate to the modernAPI butwant to silence the warnings for now, you can passlegacy-js-api in thesilenceDeprecations option:

const sass=require('sass');const result= sass.renderSync({silenceDeprecations:['legacy-js-api'],...});

This will silence the warnings for now, but the legacyAPI will be removedentirely in Dart Sass 2.0.0, so you should still plan to migrate off of it soon.