Skip to content

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

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.

WARNING

These options are marked as experimental and deprecated. They may be removed in a future v3 minor without respecting semver. Please pin the Vite version when using them.

  • legacy.devDepsScanner
  • legacy.buildRollupPluginCommonjs
  • legacy.buildSsrCjsExternalHeuristics

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((exports) => {
+init().then(({ exports }) => {
  exports.test()
})

Advanced

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

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

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.

Released under the MIT License.