Migration from v2 #

Node Support #

Vite no longer supports Node v12, which reached its EOL. Node 14.18+ is now required.

Modern Browser Baseline change #

The production bundle assumes support for modern JavaScript. By default, Vite targets browsers which support the native ES Modules and native ESM dynamic import and import.meta:

• Chrome >=87
• Firefox >=78
• Safari >=13
• Edge >=88

A small fraction of users will now require using @vitejs/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)
  • dedupe (switch to resolve.dedupe)
  • build.base (switch to base)
  • build.brotliSize (switch to build.reportCompressedSize)
  • build.cleanCssOptions (Vite now uses esbuild for CSS minification)
  • build.polyfillDynamicImport (use @vitejs/plugin-legacy for browsers without dynamic import support)
  • optimizeDeps.keepNames (switch to optimizeDeps.esbuildOptions.keepNames)

Achitecture 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 to set it to 3000.

Vite's default dev server host is now localhost. You can use server.host to set it to 127.0.0.1.

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.

To get back the v2 strategy, you can use legacy.devDepsScanner.

Build Changes #

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.

If you need to get back to the v2 strategy, you can use legacy.buildRollupPluginCommonjs.

SSR Changes #

Vite v3 uses ESM for the SSR build by default. When using ESM, the SSR externalization heuristics are no longer needed. By default, all dependencies are externalized. You can use 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.

Also build.rollupOptions.output.inlineDynamicImports 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.

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.

  npm add -D terser
  

import.meta.glob #

• Raw import.meta.glob switched from { assert: { type: 'raw' }} to { as: 'raw' }

• Keys of import.meta.glob are now relative to the current module.

  // file: /foo/index.js
  const modules = import.meta.glob('../foo/*.js')
  
  // transformed:
  const modules = {
  -  '../foo/bar.js': () => {}
  +  './bar.js': () => {}
  }
  

• 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.

WebAssembly support #

import init from 'example.wasm' syntax is dropped to prevent future collision with "ESM integration for Wasm". You can use ?init which is similar to the previous behavior.

-import init from 'example.wasm'
+import init from 'example.wasm?init'

-init().then((instance) => {
+init().then(({ exports }) => {
  exports.test()
})

Advanced #

There are some changes which only affects plugin/tool creators.

• [#5868] refactor: remove deprecated api for 3.0
  • printHttpServerUrls is removed
  • server.app, server.transformWithEsbuild are removed
  • import.meta.hot.acceptDeps is removed
• [#6901] fix: sequential injection of tags in transformIndexHtml
  • 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
  • ssrLoadModule's fixStacktrace option's default is now false
• [#8178] feat!: migrate to ESM
  • 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
  • Type of callback of import.meta.hot.accept is now stricter. It is now (mod: (Record<string, any> & { [Symbol.toStringTag]: 'Module' }) | undefined) => void (was (mod: any) => void).

Also there are other breaking changes which only affect few users.

• [#5018] feat: enable generatedCode: 'es2015' for rollup build
  • Transpile to ES5 is now necessary even if the user code only includes ES5.
• [#7877] fix: vite client types
  • /// <reference lib="dom" /> 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
  • process.env.* is now preserved in library mode
• [#8280] feat: non-blocking esbuild optimization at build time
  • server.force option was removed in favor of optimizeDeps.force option.
• [#8550] fix: dont handle sigterm in middleware mode
  • When running in middleware mode, Vite no longer kills process on SIGTERM.
• [#8647] feat: print resolved address for localhost
  • server.printUrls and previewServer.printUrls are now async

Migration from v1 #

Check the Migration from v1 Guide 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.