Sass "legacy JS API is deprecated" - Fix Dart Sass Warnings

By Kaveh Alemi·Latchkey

Dart Sass deprecated its legacy render/renderSync JS API in favor of the modern compile/compileString API. Tooling that still calls the old API prints a deprecation warning that floods CI logs and will eventually break on a future Sass major.

What this error means

Builds print Deprecation Warning: The legacy JS API is deprecated and will be removed in Dart Sass 2.0.0. per file or per run. It is a warning today, but strict log-failing CI or a future Sass upgrade turns it into a failure.

sass output

Deprecation Warning [legacy-js-api]: The legacy JS API is deprecated and will
be removed in Dart Sass 2.0.0.

More info: https://sass-lang.com/d/legacy-js-api

Common causes

Bundler integration uses the legacy API

An older Vite/Webpack Sass integration (or a custom script) calls sass.render/renderSync, the deprecated path, instead of the modern compile API.

Old sass-loader / Vite version

A stale sass-loader or Vite version defaults to the legacy API. Updating the integration switches it to the modern one.

How to fix it

Update the bundler Sass integration

Newer sass-loader/Vite use the modern API by default - upgrade them and sass.

Terminal

npm install -D sass@latest sass-loader@latest
# Vite: opt into the modern API explicitly
# css: { preprocessorOptions: { scss: { api: 'modern-compiler' } } }

Use the modern API in custom scripts

Replace renderSync with compile/compileString.

scripts/build-css.mjs

import * as sass from 'sass'
const result = sass.compile('src/styles/main.scss')
// instead of sass.renderSync({ file: ... })

How to prevent it

Keep sass and the bundler Sass integration current.
Opt into the modern Sass compiler API in your bundler config.
Migrate custom scripts off render/renderSync before Sass 2.0.

Frequently asked questions

What causes ""legacy JS API is deprecated""?

An older Vite/Webpack Sass integration (or a custom script) calls sass.render/renderSync, the deprecated path, instead of the modern compile API.

How do I fix "legacy JS API is deprecated"?

Newer sass-loader/Vite use the modern API by default - upgrade them and sass.