Skip to content

Migration from v2

Node.js Support

Vite no longer supports Node.js 12 / 13 / 15, which reached its EOL. Node.js 14.18+ / 16+ 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, 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:

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 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 to set it to 127.0.0.1 to keep the same host as Vite v2.

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') to prevent this. See server.host for more details.

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()
})

Automatic https Certificate Generation

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 to the project plugins.

import basicSsl from '@vitejs/plugin-basic-ssl'

export default {
  plugins: [basicSsl()]
}

Experimental

Using esbuild deps optimization at build time

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 is no longer needed in this case since esbuild converts CJS-only dependencies to ESM.

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: [] }

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. (fcf4d98d)