Resolving Dart Sass 'legacy-js-api' Deprecation Warning in Vite

{
  "dependencies": {
    "sass": "^1.79.1"
  }
}

Problem Statement

The Dart Sass deprecation warning occurs when migrating projects to Vite:

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

This happens because:

1. Your project uses the deprecated sass.render() API
2. Vite defaults to the legacy Sass API
3. @import rules may be using outdated syntax

The warning appears in both development and build processes.

---

Recommended Solutions

1. Update Vite Configuration

Modify your vite.config.js/vite.config.ts:

import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        // Modern API options:
        api: 'modern-compiler',  // Preferred option
        // OR alternative:
        // api: 'modern'
      }
    }
  }
});

Why This Works

• Sets Sass to use modern sass.compile() API instead of legacy sass.render()
• Addresses the root cause rather than hiding the warning
• Compatible with Dart Sass ^2.0.0

2. Migrate Sass Syntax (Advanced Projects)

For complete future-proofing:

1. Update dependencies:

npm install sass@latest vite@latest --save-dev

2. Install migrator tool:

npm install -g sass-migrator

3. Migrate all SCSS files:

find . -type f -name "*.scss" -exec sass-migrator module --migrate-deps {} +

Key changes from migration:

• Replaces @import with @use and @forward
• Eliminates global namespace conflicts
• Ensures modern Sass module compatibility

3. Handling Global Styles (Optional)

For projects with shared variables:

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
        additionalData: `@use "@/styles/variables.scss" as *;`
      }
    }
  },
  resolve: {
    alias: {
      '@': '/src'  // Path alias for imports
    }
  }
})

---

Framework-Specific Implementations

Nuxt.js Configuration

export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        sass: {  // Note: 'sass' instead of 'scss'
          api: 'modern'
        }
      }
    }
  }
});

Quasar Framework Solution

Replace Sass imports with compiled CSS:

- import 'quasar/src/css/index.sass'
+ import 'quasar/dist/quasar.css'

---

Temporary Workaround (Not Recommended)

To hide warnings without fixing the root cause:

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

Why This Is Risky

• Masks warnings without solving the problem
• Will fail when Dart Sass 2.0.0 removes legacy APIs
• Not a sustainable solution

---

Best Practices Summary

1. Use modern Sass API (api: 'modern-compiler') in Vite config
2. Migrate legacy Sass using sass-migrator
3. Replace global imports with module-based @use
4. Avoid Node version downgrades - not a viable solution

{
  "devDependencies": {
    "sass": "^1.89.0",  // Current latest
    "vite": "^5.2.0"
  }
}

Version Compatibility

These solutions work with:

• Vite ≥ v3.0.0
• Sass ≥ v1.33.0
• Node.js v18+

For full migration guidelines, refer to the official Sass Documentation.