feat(css)!: change default sass api to modern/modern-compiler (#17937)

Co-authored-by: Bjorn Lu <bjornlu.dev@gmail.com>
Co-authored-by: sapphi-red <49056869+sapphi-red@users.noreply.github.com>

docs/config/shared-options.md

@@ -227,9 +227,12 @@ Note if an inline config is provided, Vite will not search for other PostCSS con
 
 Specify options to pass to CSS pre-processors. The file extensions are used as keys for the options. The supported options for each preprocessors can be found in their respective documentation:
 
-- `sass`/`scss` - top level option `api: "legacy" | "modern" | "modern-compiler"` (default `"legacy"`) allows switching which sass API to use. For the best performance, it's recommended to use `api: "modern-compiler"` with `sass-embedded` package. [Options (legacy)](https://sass-lang.com/documentation/js-api/interfaces/LegacyStringOptions), [Options (modern)](https://sass-lang.com/documentation/js-api/interfaces/stringoptions/).
-- `less` - [Options](https://lesscss.org/usage/#less-options).
-- `styl`/`stylus` - Only [`define`](https://stylus-lang.com/docs/js.html#define-name-node) is supported, which can be passed as an object.
+- `sass`/`scss`:
+  - Select the sass API to use with `api: "modern-compiler" | "modern" | "legacy"` (default `"modern-compiler"` if `sass-embedded` is installed, otherwise `"modern"`). For the best performance, it's recommended to use `api: "modern-compiler"` with the `sass-embedded` package. The `"legacy"` API is deprecated and will be removed in Vite 7.
+  - [Options (modern)](https://sass-lang.com/documentation/js-api/interfaces/stringoptions/)
+  - [Options (legacy)](https://sass-lang.com/documentation/js-api/interfaces/LegacyStringOptions).
+- `less`: [Options](https://lesscss.org/usage/#less-options).
+- `styl`/`stylus`: Only [`define`](https://stylus-lang.com/docs/js.html#define-name-node) is supported, which can be passed as an object.
 
 **Example:**
 

docs/guide/migration.md

@@ -20,6 +20,14 @@ From Vite 6, even when `json.stringify: true` is set, `json.namedExports` is not
 
 Vite 6 also introduces a new default value for `json.stringify` which is `'auto'`, which will only stringify large JSON files. To disable this behavior, set `json.stringify: false`.
 
+### Sass now uses modern API by default
+
+In Vite 5, the legacy API was used by default for Sass. Vite 5.4 added support for the modern API.
+
+From Vite 6, the modern API is used by default for Sass. If you wish to still use the legacy API, you can set [`css.preprocessorOptions.sass.api: 'legacy'` / `css.preprocessorOptions.scss.api: 'legacy'`](/config/shared-options#css-preprocessoroptions). But note that the legacy API support will be removed in Vite 7.
+
+To migrate to the modern API, see [the Sass documentation](https://sass-lang.com/documentation/breaking-changes/legacy-js-api/).
+
 ## Advanced
 
 There are other breaking changes which only affect few users.

packages/vite/src/node/plugins/css.ts

@@ -1979,8 +1979,8 @@ type PreprocessorAdditionalData =
 type SassPreprocessorOptions = {
   additionalData?: PreprocessorAdditionalData
 } & (
-  | ({ api?: 'legacy' } & SassLegacyPreprocessBaseOptions)
-  | ({ api: 'modern' | 'modern-compiler' } & SassModernPreprocessBaseOptions)
+  | ({ api: 'legacy' } & SassLegacyPreprocessBaseOptions)
+  | ({ api?: 'modern' | 'modern-compiler' } & SassModernPreprocessBaseOptions)
 )
 
 type LessPreprocessorOptions = {
@@ -2469,9 +2469,9 @@ const scssProcessor = (
     },
     async process(environment, source, root, options, resolvers) {
       const sassPackage = loadSassPackage(root)
-      // TODO: change default in v6
-      // options.api ?? sassPackage.name === "sass-embedded" ? "modern-compiler" : "modern";
-      const api = options.api ?? 'legacy'
+      const api =
+        options.api ??
+        (sassPackage.name === 'sass-embedded' ? 'modern-compiler' : 'modern')
 
       if (!workerMap.has(options.alias)) {
         workerMap.set(
@@ -3001,18 +3001,11 @@ const createPreprocessorWorkerController = (maxWorkers: number | undefined) => {
 
   const sassProcess: StylePreprocessor<SassStylePreprocessorInternalOptions>['process'] =
     (environment, source, root, options, resolvers) => {
-      let opts: SassStylePreprocessorInternalOptions
-      if (options.api === 'modern' || options.api === 'modern-compiler') {
-        opts = { ...options, syntax: 'indented' as const }
+      const opts: SassStylePreprocessorInternalOptions = { ...options }
+      if (opts.api === 'legacy') {
+        opts.indentedSyntax = true
       } else {
-        const narrowedOptions =
-          options as SassStylePreprocessorInternalOptions & {
-            api?: 'legacy'
-          }
-        opts = {
-          ...narrowedOptions,
-          indentedSyntax: true,
-        }
+        opts.syntax = 'indented'
       }
       return scss.process(environment, source, root, opts, resolvers)
     }

playground/backend-integration/vite.config.js

@@ -54,11 +54,4 @@ function BackendIntegrationExample() {
 export default defineConfig({
   base: '/dev/',
   plugins: [BackendIntegrationExample()],
-  css: {
-    preprocessorOptions: {
-      scss: {
-        silenceDeprecations: ['legacy-js-api'],
-      },
-    },
-  },
 })

playground/css-sourcemap/vite.config.js

@@ -31,9 +31,6 @@ export default defineConfig({
           }
         },
       },
-      sass: {
-        silenceDeprecations: ['legacy-js-api', 'import'],
-      },
     },
   },
   build: {

playground/css/vite.config.js

@@ -61,6 +61,7 @@ export default defineConfig({
     },
     preprocessorOptions: {
       scss: {
+        api: 'legacy',
         additionalData: `$injectedColor: orange;`,
         importer: [
           function (url) {

playground/multiple-entrypoints/vite.config.js

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