diff --git a/docs/guide/migration.md b/docs/guide/migration.md index 3fa4683a5b4d1f..b967b584b54188 100644 --- a/docs/guide/migration.md +++ b/docs/guide/migration.md @@ -1,147 +1,60 @@ -# Migration from v2 +# Migration from v3 -## Node.js Support +## Rollup 3 -Vite no longer supports Node.js 12 / 13 / 15, which reached its EOL. Node.js 14.18+ / 16+ is now required. +Vite is now using [Rollup 3](https://github.com/vitejs/vite/issues/9870), which allowed us to simplify Vite's internal asset handling and has many improvements. See the [Rollup 3 release notes here](https://github.com/rollup/rollup/releases). -## Modern Browser Baseline change - -The production bundle assumes support for modern JavaScript. By default, Vite targets browsers which support the [native ES Modules](https://caniuse.com/es6-module), [native ESM dynamic import](https://caniuse.com/es6-module-dynamic-import), and [`import.meta`](https://caniuse.com/mdn-javascript_operators_import_meta): - -- Chrome >=87 -- Firefox >=78 -- Safari >=13 -- Edge >=88 - -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. - -## Config Options Changes - -The following options that were already deprecated in v2 have been removed: - -- `alias` (switch to [`resolve.alias`](../config/shared-options.md#resolve-alias)) -- `dedupe` (switch to [`resolve.dedupe`](../config/shared-options.md#resolve-dedupe)) -- `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#optimizedeps-esbuildoptions)) - -## Architecture Changes and Legacy Options - -This section describes the biggest architecture changes in Vite v3. To allow projects to migrate from v2 in case of a compat issue, legacy options have been added to revert to the Vite v2 strategies. - -### Dev Server Changes - -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. - -Vite's default dev server host is now `localhost`. In Vite v2, Vite was listening to `127.0.0.1` by default. Node.js under v17 normally resolves `localhost` to `127.0.0.1`, so for those versions, the host won't change. For Node.js 17+, you can use [`server.host`](../config/server-options.md#server-host) to set it to `127.0.0.1` to keep the same host as Vite v2. +Rollup 3 is mostly compatible with Rollup 2. If you are using custom [`rollupOptions`](../config/build-options.md#rollup-options) in your project and encounter issues, refer to the [Rollup migration guide](https://rollupjs.org/guide/en/#migration) to upgrade your config. -Note that Vite v3 now prints the correct host. This means Vite may print `127.0.0.1` as the listening host when `localhost` is used. You can set [`dns.setDefaultResultOrder('verbatim')`](https://nodejs.org/api/dns.html#dns_dns_setdefaultresultorder_order) to prevent this. See [`server.host`](../config/server-options.md#server-host) for more details. - -### SSR Changes - -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#ssr-noexternal) to control what dependencies to include in the SSR bundle. - -If using ESM for SSR isn't possible in your project, you can set `legacy.buildSsrCjsExternalHeuristics` to generate a CJS bundle using the same externalization strategy of Vite v2. +## Modern Browser Baseline change -Also [`build.rollupOptions.output.inlineDynamicImports`](https://rollupjs.org/guide/en/#outputinlinedynamicimports) now defaults to `false` when `ssr.target` is `'node'`. `inlineDynamicImports` changes execution order and bundling to a single file is not needed for node builds. +The modern browser build now targets `safari14` by default for wider ES2020 compatibility (bumped from `safari13`). This means that modern builds can now use [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) and that the [nullish coalescing operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing) isn't transpiled anymore. If you need to support older browsers, you can add [`@vitejs/plugin-legacy`](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) as usual. ## General Changes -- 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. -- Terser is now an optional dependency. If you are using `build.minify: 'terser'`, you need to install it. - ```shell - npm add -D terser - ``` - -### `import.meta.glob` - -- [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. +### Encoding - ```diff - // file: /foo/index.js - const modules = import.meta.glob('../foo/*.js') +The build default charset is now utf8 (see [#10753](https://github.com/vitejs/vite/issues/10753) for details). - // transformed: - const modules = { - - '../foo/bar.js': () => {} - + './bar.js': () => {} - } - ``` +### Importing CSS as a string -- 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. +In Vite 3, importing the default export of a `.css` file could introduce a double loading of CSS. -### WebAssembly Support - -`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((exports) => { -+init().then(({ exports }) => { - exports.test() -}) +```ts +import cssString from './global.css' ``` -### Automatic https Certificate Generation +This double loading could occur since a `.css` file will be emitted and it's likely that the CSS string will also be used by the application code — for example, injected by the framework runtime. From Vite 4, the `.css` default export [has been deprecated](https://github.com/vitejs/vite/issues/11094). The `?inline` query suffix modifier needs to be used in this case, as that doesn't emit the imported `.css` styles. -A valid certificate is needed when using `https`. In Vite v2, if no certificate was configured, a self-signed certificate was automatically created and cached. -Since Vite v3, we recommend manually creating your certificates. If you still want to use the automatic generation from v2, this feature can be enabled back by adding [@vitejs/plugin-basic-ssl](https://github.com/vitejs/vite-plugin-basic-ssl) to the project plugins. - -```js -import basicSsl from '@vitejs/plugin-basic-ssl' - -export default { - plugins: [basicSsl()], -} +```ts +import stuff from './global.css?inline' ``` -## Experimental - -### Using esbuild deps optimization at build time +### `dotenv` update -In v3, Vite allows the use of esbuild to optimize dependencies during build time. If enabled, it removes one of the most significant differences between dev and prod present in v2. [`@rollup/plugin-commonjs`](https://github.com/rollup/plugins/tree/master/packages/commonjs) is no longer needed in this case since esbuild converts CJS-only dependencies to ESM. +Vite is now using dotenv 16 and dotenv-expand 9 (previously dotenv 14 and dotenv-expand 5). -If you want to try this build strategy, you can use `optimizeDeps.disabled: false` (the default in v3 is `disabled: 'build'`). `@rollup/plugin-commonjs` -can be removed by passing `build.commonjsOptions: { include: [] }` +If you have a value including `#` or `` ` ``, you will need to wrap them with quotes. See their changelog for more details ([`dotenv`](https://github.com/motdotla/dotenv/blob/master/CHANGELOG.md), [`dotenv-expand`](https://github.com/motdotla/dotenv-expand/blob/master/CHANGELOG.md)). ## Advanced There are some changes which only affect plugin/tool creators. -- [[#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 -- [[#6901] fix: sequential injection of tags in transformIndexHtml](https://github.com/vitejs/vite/pull/6901) - - `transformIndexHtml` now gets the correct content modified by earlier plugins, so the order of the injected tags now works as expected. -- [[#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) -- [[#8626] refactor: type client maps](https://github.com/vitejs/vite/pull/8626) - - Type of callback of `import.meta.hot.accept` is now stricter. It is now `(mod: (Record & { [Symbol.toStringTag]: 'Module' }) | undefined) => void` (was `(mod: any) => void`). +- [[#11036] feat(client)!: remove never implemented hot.decline](https://github.com/vitejs/vite/issues/11036) + - use `hot.invalidate` instead +- [[#9669] feat: align object interface for `transformIndexHtml` hook](https://github.com/vitejs/vite/issues/9669) + - use `order` instead of `enforce` Also there are other breaking changes which only affect few users. -- [[#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) - - `/// ` is removed from `vite/client.d.ts`. `{ "lib": ["dom"] }` or `{ "lib": ["webworker"] }` is necessary in `tsconfig.json`. -- [[#8090] feat: preserve process env vars in lib build](https://github.com/vitejs/vite/pull/8090) - - `process.env.*` is now preserved in library mode -- [[#8280] feat: non-blocking esbuild optimization at build time](https://github.com/vitejs/vite/pull/8280) - - `server.force` option was removed in favor of `optimizeDeps.force` option. -- [[#8550] fix: dont handle sigterm in middleware mode](https://github.com/vitejs/vite/pull/8550) - - When running in middleware mode, Vite no longer kills process on `SIGTERM`. +- [[#11101] feat(ssr)!: remove dedupe and mode support for CJS](https://github.com/vitejs/vite/pull/11101) + - You should migrate to the default ESM mode for SSR, CJS SSR support may be removed in the next Vite major. +- [[#10475] feat: handle static assets in case-sensitive manner](https://github.com/vitejs/vite/pull/10475) + - Your project shouldn't rely on an OS ignoring file names casing. +- [[#10996] fix!: make `NODE_ENV` more predictable](https://github.com/vitejs/vite/pull/10996) + - Refer to the PR for an explanation about this change. +- [[#10903] refactor(types)!: remove facade type files](https://github.com/vitejs/vite/pull/10903) -## Migration from v1 +## Migration from v2 -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. +Check the [Migration from v2 Guide](https://v3.vitejs.dev/guide/migration.html) in the Vite v3 docs first to see the needed changes to port your app to Vite v3, and then proceed with the changes on this page.