Skip to content

Commit f8322d7

Browse files
sapphi-redsapphi-red
committed
wip: migration guide
1 parent 4168e80 commit f8322d7

File tree

1 file changed

+137
-39
lines changed

1 file changed

+137
-39
lines changed

‎docs/guide/migration.md‎

Lines changed: 137 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,156 @@
1-
# Migration from v6
1+
# Migration from v7
22

3-
## Node.js Support
3+
## New Features
44

5-
Vite no longer supports Node.js 18, which reached its EOL. Node.js 20.19+ / 22.12+ is now required.
5+
::: tip Temporary section
6+
7+
This section will be moved to the release post before the stable release.
8+
9+
:::
10+
11+
### Built-in tsconfig `paths` Support
12+
13+
**_TODO: write this section_**
14+
15+
### `emitDecoratorMetadata` Support
16+
17+
**_TODO: write this section_**
618

719
## Default Browser Target change
820

9-
The default browser value of `build.target` is updated to a newer browser.
21+
**_TODO: implement this change later_**
1022

11-
- Chrome 87 → 107
12-
- Edge 88 → 107
13-
- Firefox 78 → 104
14-
- Safari 14.0 → 16.0
23+
The default browser value of `build.target`, `'baseline-widely-available'`, is updated to a newer browser.
1524

16-
These browser versions align with [Baseline](https://web-platform-dx.github.io/web-features/) Widely Available feature sets as of 2025-05-01. In other words, they were all released before 2022-11-01.
25+
- Chrome 107 → 111
26+
- Edge 107 → 111
27+
- Firefox 104 → 114
28+
- Safari 16.0 → 16.4
1729

18-
In Vite 5, the default target was named `'modules'`, but this is no longer available. Instead, a new default target `'baseline-widely-available'` is introduced.
30+
These browser versions align with [Baseline](https://web-platform-dx.github.io/web-features/) Widely Available feature sets as of 2026-01-01. In other words, they were all released before 2026-01-01.
1931

20-
## General Changes
32+
## Rolldown Integration
33+
34+
**_TODO: write this section_**
35+
36+
### Gradual migration
37+
38+
`rolldown-vite` package implements Vite 7 with Rolldown integration, but without the other Vite 8 changes. This can be used as a intermediate step to migrate to Vite 8. See [the Rolldown Integration guide](https://v7.vite.dev/guide/rolldown) in the Vite 7 docs to switch to `rolldown-vite` from Vite 7.
39+
40+
For users migrating from `rolldown-vite` to Vite 8, you can undo the dependencies changes in `package.json` and update to Vite 8.
41+
42+
### Dependency Optimizer now uses Rolldown
43+
44+
_**TODO: write this section**_
45+
46+
### JS Transformation by Oxc
47+
48+
_**TODO: write this section**_
49+
50+
`esbuild` option, `oxc` option...
51+
52+
Note that if you use a plugin that uses `transformWithEsbuild` function, you need to install `esbuild` as a dev dependency as it's now an optional dependency. `transformWithEsbuild` function is now deprecated and will be removed in the future.
53+
54+
TODO: No Native Decorator Support
55+
TODO: `supported` option https://github.com/rolldown/rolldown/issues/6212
56+
57+
### JS Minification by Oxc
58+
59+
Oxc Minifier is now used for JS minification by default. You can use `build.minify: 'esbuild'` option to switch back to esbuild. Note that you need to install `esbuild` as a dev dependency as it's now an optional dependency.
60+
61+
TODO: explain that `mangleProps` / `reserveProps` / `mangleQuoted` / `mangleCache` options are not supported by Oxc but are supported by esbuild.
62+
TODO: write about different assumptions (https://esbuild.github.io/content-types/#javascript-caveats)
63+
64+
### CSS Minification by LightningCSS
2165

22-
### Removed Sass legacy API support
66+
LightningCSS is now used for CSS minification by default. You can use `build.cssMinify: 'esbuild'` option to switch back to esbuild. Note that you need to install `esbuild` as a dev dependency as it's now an optional dependency.
2367

24-
As planned, support for the Sass legacy API is removed. Vite now only supports the modern API. You can remove the `css.preprocessorOptions.sass.api` / `css.preprocessorOptions.scss.api` option.
68+
### Consistent CJS Interop
69+
70+
**_TODO: write this section_**
71+
72+
https://github.com/rolldown/rolldown/issues/6269
73+
https://github.com/rolldown/rolldown/issues/6438
74+
https://esbuild.github.io/content-types/#default-interop
75+
76+
### Module Resolution Using Format Sniffing
77+
78+
When both `browser` and `module` fields are present in `package.json`, Vite used to resolve the field based on the content of the file, trying to pick the ESM file for browsers. This was introduced because some packages were using the `module` field to point to ESM files for Node.js and some other packages were using the `browser` field to point to UMD files for browsers. Given that the modern `exports` field solved this problem and is now adopted by many packages, Vite no longer uses this heuristic and always respects the order of the `resolve.mainFields` option. If you were relying on this behavior, you can use the `resolve.alias` option to map the field to the desired file or apply a patch with your package manager (e.g. `patch-package`, `pnpm patch`).
79+
80+
### Deprecate `build.rollupOptions.output.manualChunks`
81+
82+
**_TODO: write this section_**
83+
84+
### Require Calls For Externalized Modules
85+
86+
`require` calls for externalized modules are now preserved as `require` calls and not converted to `import` statements.
87+
88+
https://rolldown.rs/in-depth/bundling-cjs#require-external-modules
89+
90+
_**TODO: write this section**_
91+
92+
### `import.meta.url` in UMD / IIFE
93+
94+
_**TODO: write this section**_
95+
96+
https://github.com/rolldown/rolldown/issues/3301
97+
98+
### Removed `build.rollupOptions.watch.chokidar` option
99+
100+
_**TODO: write this section**_
101+
102+
`build.rollupOptions.watch.chokidar` option is removed. Please migrate to `build.rollupOptions.watch.notify` option.
103+
104+
### Deprecations
105+
106+
The following options are deprecated.
107+
108+
- `build.rollupOptions`: please use `build.rolldownOptions` instead.
109+
- `esbuild`: please use `oxc` option instead.
110+
- `worker.rollupOptions`: please use `worker.rolldownOptions` instead.
111+
- `optimizeDeps.esbuildOptions`: please use `optimizeDeps.rolldownOptions` instead.
112+
113+
## General Changes
25114

26115
## Removed deprecated features
27116

28-
- `splitVendorChunkPlugin` (deprecated in v5.2.7)
29-
- This plugin was originally provided to ease migration to Vite v2.9.
30-
- The `build.rollupOptions.output.manualChunks` option can be used to control the chunking behavior if needed.
31-
- Hook-level `enforce` / `transform` for `transformIndexHtml` (deprecated in v4.0.0)
32-
- It was changed to align the interface with [Rollup's object hooks](https://rollupjs.org/plugin-development/#build-hooks:~:text=Instead%20of%20a%20function%2C%20hooks%20can%20also%20be%20objects.).
33-
- `order` should be used instead of `enforce`, and `handler` should be used instead of `transform`.
117+
**_TODO: implement these changes later_**
34118

35119
## Advanced
36120

37121
There are other breaking changes which only affect few users.
38122

39-
- [[#19979] chore: declare version range for peer dependencies](https://github.com/vitejs/vite/pull/19979)
40-
- Specified the peer dependencies version range for CSS preprocessors.
41-
- [[#20013] refactor: remove no-op `legacy.proxySsrExternalModules`](https://github.com/vitejs/vite/pull/20013)
42-
- `legacy.proxySsrExternalModules` property had no effect since Vite 6. It is now removed.
43-
- [[#19985] refactor!: remove deprecated no-op type only properties](https://github.com/vitejs/vite/pull/19985)
44-
- The following unused properties are now removed: `ModuleRunnerOptions.root`, `ViteDevServer._importGlobMap`, `ResolvePluginOptions.isFromTsImporter`, `ResolvePluginOptions.getDepsOptimizer`, `ResolvePluginOptions.shouldExternalize`, `ResolvePluginOptions.ssrConfig`
45-
- [[#19986] refactor: remove deprecated env api properties](https://github.com/vitejs/vite/pull/19986)
46-
- These properties were deprecated from the beginning. It is now removed.
47-
- [[#19987] refactor!: remove deprecated `HotBroadcaster` related types](https://github.com/vitejs/vite/pull/19987)
48-
- These types were introduced as part of the now-deprecated Runtime API. It is now removed: `HMRBroadcaster`, `HMRBroadcasterClient`, `ServerHMRChannel`, `HMRChannel`
49-
- [[#19996] fix(ssr)!: don't access `Object` variable in ssr transformed code](https://github.com/vitejs/vite/pull/19996)
50-
- `__vite_ssr_exportName__` is now required for the module runner runtime context.
51-
- [[#20045] fix: treat all `optimizeDeps.entries` values as globs](https://github.com/vitejs/vite/pull/20045)
52-
- `optimizeDeps.entries` now does not receive literal string paths. Instead, it always receives globs.
53-
- [[#20222] feat: apply some middlewares before `configureServer` hook](https://github.com/vitejs/vite/pull/20222), [[#20224] feat: apply some middlewares before `configurePreviewServer` hook](https://github.com/vitejs/vite/pull/20224)
54-
- Some middlewares are now applied before the `configureServer` / `configurePreviewServer` hook. Note that if you don't expect a certain route to apply the [`server.cors`](../config/server-options.md#server-cors) / [`preview.cors`](../config/preview-options.md#preview-cors) option, make sure to remove the related headers from the response.
55-
56-
## Migration from v5
57-
58-
Check the [Migration from v5 Guide](https://v6.vite.dev/guide/migration.html) in the Vite v6 docs first to see the needed changes to port your app to Vite 6, and then proceed with the changes on this page.
123+
- **[TODO: fix before stable release (better if it's fixed before first beta)]** https://github.com/vitejs/rolldown-vite/issues/461 (blocking sveltekit)
124+
- **[TODO: fix before stable release (better if it's fixed before first beta)]** https://github.com/rolldown/rolldown/issues/5867
125+
- **[TODO: fix before stable release]** https://github.com/rolldown/rolldown/issues/5726 (affects nuxt, qwik)
126+
- **[TODO: fix before stable release]** https://github.com/rolldown/rolldown/issues/3403 (affects sveltekit)
127+
- **[TODO: fix before stable release]** https://github.com/vitejs/rolldown-vite/issues/465
128+
- **[TODO: fix before stable release]** https://github.com/vitejs/rolldown-vite/issues/450
129+
- **[TODO: fix before stable release]** Legacy chunks are emitted as an asset file instead of a chunk file due to the lack of prebuilt chunk emit feature ([rolldown#4304](https://github.com/rolldown/rolldown/issues/4034)). This means the chunk related options does not apply to legacy chunks and the manifest file will not include legacy chunks as a chunk file.
130+
- **[TODO: fix before stable release]** resolver cache breaks minor cases in Vitest ([rolldown-vite#466](https://github.com/vitejs/rolldown-vite/issues/466), [vitest#8754](https://github.com/vitest-dev/vitest/issues/8754#issuecomment-3441115032))
131+
- **[TODO: fix before stable release]** The resolver does not work with yarn pnp ([rolldown-vite#324](https://github.com/vitejs/rolldown-vite/issues/324), [rolldown-vite#392](https://github.com/vitejs/rolldown-vite/issues/392))
132+
- **[TODO: fix before stable release]** native plugin ordering issue ([rolldown-vite#373](https://github.com/vitejs/rolldown-vite/issues/373))
133+
- **[TODO: fix before stable release]** `@vite-ignore` comment edge case ([rolldown-vite#426](https://github.com/vitejs/rolldown-vite/issues/426))
134+
- **[TODO: fix before stable release]** https://github.com/rolldown/rolldown/issues/3403
135+
- ext glob support ([rolldown-vite#365](https://github.com/vitejs/rolldown-vite/issues/365))
136+
- `define` does not share reference for objects: When you pass an object as a value to `define`, each variable will have a separate copy of the object.
137+
- `bundle` object changes (`bundle` is an object passed in `generateBundle` / `writeBundle` hooks, returned by `build` function):
138+
- Assigning to `bundle[foo]` is not supported. This is discouraged by Rollup as well. Please use `this.emitFile()` instead.
139+
- the reference is not shared across the hooks ([rolldown-vite#410](https://github.com/vitejs/rolldown-vite/issues/410))
140+
- `structuredClone(bundle)` errors with `DataCloneError: #<Object> could not be cloned`. This is not supported anymore. Please clone it with `structuredClone({ ...bundle })`. ([rolldown-vite#128](https://github.com/vitejs/rolldown-vite/issues/128))
141+
- **[TODO: clarify this in Rolldown's docs and link it from here]** All parallel hooks in Rollup works as sequential hooks.
142+
- **[TODO: clarify this in Rolldown's docs and link it from here]** `"use strict";` is not injected sometimes.
143+
- Transforming to lower than ES5 with plugin-legacy is not supported ([rolldown-vite#452](https://github.com/vitejs/rolldown-vite/issues/452))
144+
- Passing the same browser with multiple versions of it to `build.target` option now errors: esbuild selects the latest version of it, which was probably not what you intended.
145+
- Missing support by Rolldown: The following features are not supported by Rolldown and is no longer supported by Vite.
146+
- `build.rollupOptions.output.format: 'system'` ([rolldown#2387](https://github.com/rolldown/rolldown/issues/2387))
147+
- `build.rollupOptions.output.format: 'amd'` ([rolldown#2387](https://github.com/rolldown/rolldown/issues/2528))
148+
- Complete support for TypeScript legacy namespace ([oxc-project/oxc#14227](https://github.com/oxc-project/oxc/issues/14227))
149+
- `shouldTransformCachedModule` hook ([rolldown#4389](https://github.com/rolldown/rolldown/issues/4389))
150+
- `resolveImportMeta` hook ([rolldown#1010](https://github.com/rolldown/rolldown/issues/1010))
151+
- `renderDynamicImport` hook ([rolldown#4532](https://github.com/rolldown/rolldown/issues/4532))
152+
- `resolveFileUrl` hook
153+
154+
## Migration from v6
155+
156+
Check the [Migration from v6 Guide](https://v7.vite.dev/guide/migration.html) in the Vite v7 docs first to see the needed changes to port your app to Vite 7, and then proceed with the changes on this page.

0 commit comments

Comments
 (0)