-
-
Notifications
You must be signed in to change notification settings - Fork 6.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
208 changed files
with
3,208 additions
and
1,712 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,133 +1,113 @@ | ||
| # Migration from v1 | ||
| # Migration from v2 | ||
|
|
||
| ## Config Options Change | ||
| ## Node Support | ||
|
|
||
| - The following options have been removed and should be implemented via [plugins](./api-plugin): | ||
| Vite no longer supports Node v12, which reached its EOL. Node 14.6+ is now required. | ||
|
|
||
| - `resolvers` | ||
| - `transforms` | ||
| - `indexHtmlTransforms` | ||
| ## Modern Browser Baseline change | ||
|
|
||
| - `jsx` and `enableEsbuild` have been removed; Use the new [`esbuild`](/config/#esbuild) option instead. | ||
| The production bundle assumes support for modern JavaScript. By default, Vite targets browsers which support the [native ES Modules](https://caniuse.com/es6-module) and [native ESM dynamic import](https://caniuse.com/es6-module-dynamic-import) and [`import.meta`](https://caniuse.com/mdn-javascript_statements_import_meta): | ||
|
|
||
| - [CSS related options](/config/#css-modules) are now nested under `css`. | ||
| - Chrome >=87 | ||
| - Firefox >=78 | ||
| - Safari >=13 | ||
| - Edge >=88 | ||
|
|
||
| - All [build-specific options](/config/#build-options) are now nested under `build`. | ||
| A small fraction of users will now require using [@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy), which will automatically generate legacy chunks and corresponding ES language feature polyfills. | ||
|
|
||
| - `rollupInputOptions` and `rollupOutputOptions` are replaced by [`build.rollupOptions`](/config/#build-rollupoptions). | ||
| - `esbuildTarget` is now [`build.target`](/config/#build-target). | ||
| - `emitManifest` is now [`build.manifest`](/config/#build-manifest). | ||
| - The following build options have been removed since they can be achieved via plugin hooks or other options: | ||
| - `entry` | ||
| - `rollupDedupe` | ||
| - `emitAssets` | ||
| - `emitIndex` | ||
| - `shouldPreload` | ||
| - `configureBuild` | ||
| ## Config Options Changes | ||
|
|
||
| - All [server-specific options](/config/#server-options) are now nested under | ||
| `server`. | ||
| - The following options that were already deprecated in v2 have been removed: | ||
|
|
||
| - `hostname` is now [`server.host`](/config/#server-host). | ||
| - `httpsOptions` has been removed. [`server.https`](/config/#server-https) can directly accept the options object. | ||
| - `chokidarWatchOptions` is now [`server.watch`](/config/#server-watch). | ||
| - `alias` (switch to [`resolve.alias`](../config/shared-options.md#resolvealias)) | ||
| - `dedupe` (switch to [`resolve.dedupe`](../config/shared-options.md#resolvededupe)) | ||
| - `build.base` (switch to [`base`](../config/shared-options.md#base)) | ||
| - `build.brotliSize` (switch to [`build.reportCompressedSize`](../config/build-options.md#build-reportcompressedsize)) | ||
| - `build.cleanCssOptions` (Vite now uses esbuild for CSS minification) | ||
| - `build.polyfillDynamicImport` (use [`@vitejs/plugin-legacy`](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) for browsers without dynamic import support) | ||
| - `optimizeDeps.keepNames` (switch to [`optimizeDeps.esbuildOptions.keepNames`](../config/dep-optimization-options.md#optimizedepsesbuildoptions)) | ||
|
|
||
| - [`assetsInclude`](/config/#assetsinclude) now expects `string | RegExp | (string | RegExp)[]` instead of a function. | ||
| ## Dev Server Changes | ||
|
|
||
| - All Vue specific options are removed; Pass options to the Vue plugin instead. | ||
| Vite's default dev server port is now 5173. You can use [`server.port`](../config/server-options.md#server-port) to set it to 3000. | ||
|
|
||
| ## Alias Behavior Change | ||
| Vite optimizes dependencies with esbuild to both convert CJS-only deps to ESM and to reduce the number of modules the browser needs to request. In v3, the default strategy to discover and batch dependencies has changed. Vite no longer pre-scans user code with esbuild to get an initial list of dependencies on cold start. Instead, it delays the first dependency optimization run until every imported user module on load is processed. | ||
|
|
||
| [`alias`](/config/#resolve-alias) is now being passed to `@rollup/plugin-alias` and no longer require start/ending slashes. The behavior is now a direct replacement, so 1.0-style directory alias key should remove the ending slash: | ||
| To get back the v2 strategy, you can use [`optimizeDeps.devScan`](../config/dep-optimization-options.md#optimizedepsdevscan). | ||
|
|
||
| ```diff | ||
| - alias: { '/@foo/': path.resolve(__dirname, 'some-special-dir') } | ||
| + alias: { '/@foo': path.resolve(__dirname, 'some-special-dir') } | ||
| ``` | ||
| ## Build Changes | ||
|
|
||
| Alternatively, you can use the `[{ find: RegExp, replacement: string }]` option format for more precise control. | ||
| In v3, Vite uses esbuild to optimize dependencies by default. Doing so, it removes one of the most significant differences between dev and prod present in v2. Because esbuild converts CJS-only dependencies to ESM, [`@rollupjs/plugin-commonjs`](https://github.com/rollup/plugins/tree/master/packages/commonjs) is no longer used. | ||
|
|
||
| ## Vue Support | ||
| If you need to get back to the v2 strategy, you can use [`optimizeDeps.disabled: 'build'`](../config/dep-optimization-options.md#optimizedepsdisabled). | ||
|
|
||
| Vite 2.0 core is now framework agnostic. Vue support is now provided via [`@vitejs/plugin-vue`](https://github.com/vitejs/vite/tree/main/packages/plugin-vue). Simply install it and add it in the Vite config: | ||
| ## SSR Changes | ||
|
|
||
| ```js | ||
| import vue from '@vitejs/plugin-vue' | ||
| import { defineConfig } from 'vite' | ||
| Vite v3 uses ESM for the SSR build by default. When using ESM, the [SSR externalization heuristics](https://vitejs.dev/guide/ssr.html#ssr-externals) are no longer needed. By default, all dependencies are externalized. You can use [`ssr.noExternal`](../config/ssr-options.md#ssrnoexternal) to control what dependencies to include in the SSR bundle. | ||
|
|
||
| export default defineConfig({ | ||
| plugins: [vue()] | ||
| }) | ||
| ``` | ||
| If using ESM for SSR isn't possible in your project, you can set `ssr.format: 'cjs'` to generate a CJS bundle. In this case, the same externalization strategy of Vite v2 will be used. | ||
|
|
||
| ### Custom Blocks Transforms | ||
|
|
||
| A custom plugin can be used to transform Vue custom blocks like the one below: | ||
|
|
||
| ```ts | ||
| // vite.config.js | ||
| import vue from '@vitejs/plugin-vue' | ||
| import { defineConfig } from 'vite' | ||
|
|
||
| const vueI18nPlugin = { | ||
| name: 'vue-i18n', | ||
| transform(code, id) { | ||
| if (!/vue&type=i18n/.test(id)) { | ||
| return | ||
| } | ||
| if (/\.ya?ml$/.test(id)) { | ||
| code = JSON.stringify(require('js-yaml').load(code.trim())) | ||
| } | ||
| return `export default Comp => { | ||
| Comp.i18n = ${code} | ||
| }` | ||
| } | ||
| } | ||
| ## General Changes | ||
|
|
||
| export default defineConfig({ | ||
| plugins: [vue(), vueI18nPlugin] | ||
| }) | ||
| ``` | ||
| - JS file extensions in SSR and lib mode now use a valid extension (`js`, `mjs`, or `cjs`) for output JS entries and chunks based on their format and the package type. | ||
|
|
||
| ## React Support | ||
| ### `import.meta.glob` | ||
|
|
||
| React Fast Refresh support is now provided via [`@vitejs/plugin-react`](https://github.com/vitejs/vite/tree/main/packages/plugin-react). | ||
| - [Raw `import.meta.glob`](features.md#glob-import-as) switched from `{ assert: { type: 'raw' }}` to `{ as: 'raw' }` | ||
| - Keys of `import.meta.glob` are now relative to the current module. | ||
|
|
||
| ## HMR API Change | ||
| ```diff | ||
| // file: /foo/index.js | ||
| const modules = import.meta.glob('../foo/*.js') | ||
|
|
||
| `import.meta.hot.acceptDeps()` have been deprecated. [`import.meta.hot.accept()`](./api-hmr#hot-accept-deps-cb) can now accept single or multiple deps. | ||
| // transformed: | ||
| const modules = { | ||
| - '../foo/bar.js': () => {} | ||
| + './bar.js': () => {} | ||
| } | ||
| ``` | ||
|
|
||
| ## Manifest Format Change | ||
| - When using an alias with `import.meta.glob`, the keys are always absolute. | ||
| - `import.meta.globEager` is now deprecated. Use `import.meta.glob('*', { eager: true })` instead. | ||
|
|
||
| The build manifest now uses the following format: | ||
| ### WebAssembly support | ||
|
|
||
| ```json | ||
| { | ||
| "index.js": { | ||
| "file": "assets/index.acaf2b48.js", | ||
| "imports": [...] | ||
| }, | ||
| "index.css": { | ||
| "file": "assets/index.7b7dbd85.css" | ||
| } | ||
| "asset.png": { | ||
| "file": "assets/asset.0ab0f9cd.png" | ||
| } | ||
| } | ||
| `import init from 'example.wasm'` syntax is dropped to prevent future collision with ["ESM integration for Wasm"](https://github.com/WebAssembly/esm-integration). | ||
| You can use `?init` which is similar to the previous behavior. | ||
|
|
||
| ```diff | ||
| -import init from 'example.wasm' | ||
| +import init from 'example.wasm?init' | ||
|
|
||
| -init().then((instance) => { | ||
| +init().then(({ exports }) => { | ||
| exports.test() | ||
| }) | ||
| ``` | ||
|
|
||
| For entry JS chunks, it also lists its imported chunks which can be used to render preload directives. | ||
| ## Advanced | ||
|
|
||
| There are some changes which only affects plugin/tool creators. | ||
|
|
||
| ## For Plugin Authors | ||
| - [[#5868] refactor: remove deprecated api for 3.0](https://github.com/vitejs/vite/pull/5868) | ||
| - `printHttpServerUrls` is removed | ||
| - `server.app`, `server.transformWithEsbuild` are removed | ||
| - `import.meta.hot.acceptDeps` is removed | ||
| - [[#7995] chore: do not fixStacktrace](https://github.com/vitejs/vite/pull/7995) | ||
| - `ssrLoadModule`'s `fixStacktrace` option's default is now `false` | ||
| - [[#8178] feat!: migrate to ESM](https://github.com/vitejs/vite/pull/8178) | ||
| - `formatPostcssSourceMap` is now async | ||
| - `resolvePackageEntry`, `resolvePackageData` are no longer available from CJS build (dynamic import is needed to use in CJS) | ||
|
|
||
| Vite 2 uses a completely redesigned plugin interface which extends Rollup plugins. Please read the new [Plugin Development Guide](./api-plugin). | ||
| Also there are other breaking changes which only affect few users. | ||
|
|
||
| Some general pointers on migrating a v1 plugin to v2: | ||
| - [[#5018] feat: enable `generatedCode: 'es2015'` for rollup build](https://github.com/vitejs/vite/pull/5018) | ||
| - Transpile to ES5 is now necessary even if the user code only includes ES5. | ||
| - [[#7877] fix: vite client types](https://github.com/vitejs/vite/pull/7877) | ||
| - `/// <reference lib="dom" />` is removed from `vite/client.d.ts`. `{ "lib": ["dom"] }` or `{ "lib": ["webworker"] }` is necessary in `tsconfig.json`. | ||
| - [[#8280] feat: non-blocking esbuild optimization at build time](https://github.com/vitejs/vite/pull/8280) | ||
| - `server.force` option was removed in favor of `force` option. | ||
|
|
||
| - `resolvers` -> use the [`resolveId`](https://rollupjs.org/guide/en/#resolveid) hook | ||
| - `transforms` -> use the [`transform`](https://rollupjs.org/guide/en/#transform) hook | ||
| - `indexHtmlTransforms` -> use the [`transformIndexHtml`](./api-plugin#transformindexhtml) hook | ||
| - Serving virtual files -> use [`resolveId`](https://rollupjs.org/guide/en/#resolveid) + [`load`](https://rollupjs.org/guide/en/#load) hooks | ||
| - Adding `alias`, `define` or other config options -> use the [`config`](./api-plugin#config) hook | ||
| ## Migration from v1 | ||
|
|
||
| Since most of the logic should be done via plugin hooks instead of middlewares, the need for middlewares is greatly reduced. The internal server app is now a good old [connect](https://github.com/senchalabs/connect) instance instead of Koa. | ||
| Check the [Migration from v1 Guide](https://v2.vitejs.dev/guide/migration.html) in the Vite v2 docs first to see the needed changes to port your app to Vite v2, and then proceed with the changes on this page. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.