How to Fix Dart Sass Legacy JS API Deprecation Warning in Vite

Problem: Dart Sass Legacy JS API Deprecation Warning

If you've recently switched a project from create-react-app to Vite and are encountering this warning:

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

You're not alone. This issue occurs because the default API used by Vite is set to legacy, which conflicts with Dart Sass's move toward modern APIs in version 2.0.0.

This blog explains how to fix or suppress these warnings and ensure your application runs smoothly during development and production builds.

Why Is This Happening?

The Dart Sass library is phasing out the legacy sass.render() API in favor of modern sass.compile() and sass.compileString() methods. If your project or its dependencies use the legacy API, you'll see these warnings.

Solution: Update Vite Configurations

To resolve this warning, you need to explicitly define the modern API in your Vite configuration.

Step 1: Modify vite.config.[js/ts]

Add the following code to your vite.config.[js/ts] file:

import { defineConfig } from 'vite'

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler', // or 'modern'
      },
    },
  },
})

Step 2: Suppress Warnings (Optional)

If you only want to suppress the warning without changing the API, you can add the following:

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        silenceDeprecations: ['legacy-js-api'],
      },
    },
  },
})

Step 3: Using the Correct Key (sass vs scss)

For frameworks like Nuxt.js or SvelteKit, you might need to use sass instead of scss in the preprocessorOptions key. Example for Nuxt.js:

export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        sass: {
          api: 'modern',
        },
      },
    },
  },
})

Alternative Solutions

Update Dart Sass Dependencies

Make sure you are using the latest version of Dart Sass. You can update it using:

npm install sass@latest

Check for Legacy API in Your Code or Dependencies

Search for sass.render() in your code or dependencies. Replace it with sass.compile() or sass.compileString() as per the new API requirements. Refer to the Dart Sass JS API Documentation for details.

Downgrade Node.js (Last Resort)

If you encounter compatibility issues with newer Node.js versions, consider downgrading to a stable version like 18.x.x using Node Version Manager (NVM):

nvm install 18
nvm use 18

FAQ

Why do I need to specify api: 'modern-compiler' in Vite?

Vite defaults to the legacy API for compatibility. Explicitly setting the modern API ensures your project aligns with Dart Sass's latest changes.

What happens if I suppress the warnings?

Suppressing warnings hides the log messages but does not solve the root cause. It's better to migrate to the modern API to future-proof your application.

Can I still use Node-Sass?

No, Node-Sass is deprecated and no longer actively maintained. Switching to Dart Sass is recommended for long-term support and compatibility.