Skip to content

Latest commit

 

History

History
115 lines (77 loc) · 6.2 KB

migration.md

File metadata and controls

115 lines (77 loc) · 6.2 KB
Raw

Migration from v2

Node Support

Vite no longer supports Node v12, which reached its EOL. Node 14.6+ 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

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 optimizeDeps.devScan.

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 optimizeDeps.disabled: 'build'.

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 ssr.format: 'cjs' to generate a CJS bundle. In this case, the same externalization strategy of Vite v2 will be used.

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.

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.

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.