forked from vitejs/vite
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: migration from v2 guide (vitejs#8390)
Co-authored-by: Shinigami <chrissi92@hotmail.de> Co-authored-by: Tony Trinh <tony19@gmail.com>
- Loading branch information
3 people
committed
May 31, 2022
1 parent
9af61b5
commit cfc37ac
Showing
2 changed files
with
32 additions
and
111 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,133 +1,54 @@ | ||
| # 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). | ||
| - `optimizeDeps.keepNames` (switch to [`optimizeDeps.esbuildOptions.keepNames`](../config/dep-optimization-options.md#optimizedepsesbuildoptions)) | ||
| - `build.base` (switch to [`base`](../config/shared-options.md#base)) | ||
| - `alias` (switch to [`resolve.alias`](../config/shared-options.md#resolvealias)) | ||
| - `dedupe` (switch to [`resolve.dedupe`](../config/shared-options.md#resolvededupe)) | ||
| - `polyfillDynamicImport` (use [`@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) for browsers without dynamic import support) | ||
|
|
||
| - [`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 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 Behavior Change | ||
| To get back the v2 strategy, you can use [`optimizeDeps.devScan`](../config/dep-optimization-options.md#optimizedepsdevscan). | ||
|
|
||
| [`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: | ||
| ## Build Changes | ||
|
|
||
| ```diff | ||
| - alias: { '/@foo/': path.resolve(__dirname, 'some-special-dir') } | ||
| + alias: { '/@foo': path.resolve(__dirname, 'some-special-dir') } | ||
| ``` | ||
| 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`] is no longer used. | ||
|
|
||
| Alternatively, you can use the `[{ find: RegExp, replacement: string }]` option format for more precise control. | ||
| If you need to get back to the v2 strategy, you can use [`optimizeDeps.disabled: 'build'`](../config/dep-optimization-options.md#optimizedepsdisabled). | ||
|
|
||
| ## Vue Support | ||
| ## SSR Changes | ||
|
|
||
| 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: | ||
| 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. | ||
|
|
||
| ```js | ||
| import vue from '@vitejs/plugin-vue' | ||
| import { defineConfig } from 'vite' | ||
| 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. | ||
|
|
||
| export default defineConfig({ | ||
| plugins: [vue()] | ||
| }) | ||
| ``` | ||
| ## General Changes | ||
|
|
||
| ### Custom Blocks Transforms | ||
| - [Raw `import.meta.glob`](features.md#glob-import-as) switched from `{ assert: { type: 'raw' }}` to `{ as: 'raw' }` | ||
|
|
||
| A custom plugin can be used to transform Vue custom blocks like the one below: | ||
| - 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. | ||
|
|
||
| ```ts | ||
| // vite.config.js | ||
| import vue from '@vitejs/plugin-vue' | ||
| import { defineConfig } from 'vite' | ||
| ## Migration from v1 | ||
|
|
||
| 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} | ||
| }` | ||
| } | ||
| } | ||
|
|
||
| export default defineConfig({ | ||
| plugins: [vue(), vueI18nPlugin] | ||
| }) | ||
| ``` | ||
|
|
||
| ## React Support | ||
|
|
||
| React Fast Refresh support is now provided via [`@vitejs/plugin-react`](https://github.com/vitejs/vite/tree/main/packages/plugin-react). | ||
|
|
||
| ## HMR API Change | ||
|
|
||
| `import.meta.hot.acceptDeps()` have been deprecated. [`import.meta.hot.accept()`](./api-hmr#hot-accept-deps-cb) can now accept single or multiple deps. | ||
|
|
||
| ## Manifest Format Change | ||
|
|
||
| The build manifest now uses the following format: | ||
|
|
||
| ```json | ||
| { | ||
| "index.js": { | ||
| "file": "assets/index.acaf2b48.js", | ||
| "imports": [...] | ||
| }, | ||
| "index.css": { | ||
| "file": "assets/index.7b7dbd85.css" | ||
| } | ||
| "asset.png": { | ||
| "file": "assets/asset.0ab0f9cd.png" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| For entry JS chunks, it also lists its imported chunks which can be used to render preload directives. | ||
|
|
||
| ## For Plugin Authors | ||
|
|
||
| Vite 2 uses a completely redesigned plugin interface which extends Rollup plugins. Please read the new [Plugin Development Guide](./api-plugin). | ||
|
|
||
| Some general pointers on migrating a v1 plugin to v2: | ||
|
|
||
| - `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 | ||
|
|
||
| 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. |