diff --git a/docs/config/shared-options.md b/docs/config/shared-options.md index 0ea4aeeb63bcd9..34c07baff8e5d3 100644 --- a/docs/config/shared-options.md +++ b/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:** diff --git a/docs/guide/migration.md b/docs/guide/migration.md index f4c11d580c9164..aab7b16c390d31 100644 --- a/docs/guide/migration.md +++ b/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. diff --git a/packages/vite/src/node/plugins/css.ts b/packages/vite/src/node/plugins/css.ts index 958c923e146831..1acab05082d114 100644 --- a/packages/vite/src/node/plugins/css.ts +++ b/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['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) } diff --git a/playground/backend-integration/vite.config.js b/playground/backend-integration/vite.config.js index 9824d40f9f3efb..9e0a914234b7bf 100644 --- a/playground/backend-integration/vite.config.js +++ b/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'], - }, - }, - }, }) diff --git a/playground/css-sourcemap/vite.config.js b/playground/css-sourcemap/vite.config.js index 4269c6735c86c8..e51cf320ad76e1 100644 --- a/playground/css-sourcemap/vite.config.js +++ b/playground/css-sourcemap/vite.config.js @@ -31,9 +31,6 @@ export default defineConfig({ } }, }, - sass: { - silenceDeprecations: ['legacy-js-api', 'import'], - }, }, }, build: { diff --git a/playground/css/vite.config.js b/playground/css/vite.config.js index 158a5130061b46..cbec6b9585b820 100644 --- a/playground/css/vite.config.js +++ b/playground/css/vite.config.js @@ -61,6 +61,7 @@ export default defineConfig({ }, preprocessorOptions: { scss: { + api: 'legacy', additionalData: `$injectedColor: orange;`, importer: [ function (url) { diff --git a/playground/multiple-entrypoints/vite.config.js b/playground/multiple-entrypoints/vite.config.js index c0d24577cca033..3202cebc0ce4aa 100644 --- a/playground/multiple-entrypoints/vite.config.js +++ b/playground/multiple-entrypoints/vite.config.js @@ -37,11 +37,4 @@ export default defineConfig({ }, }, }, - css: { - preprocessorOptions: { - scss: { - silenceDeprecations: ['legacy-js-api'], - }, - }, - }, })