Vite Knowledge Patch

Vite Knowledge Patch

Use this skill when configuring, upgrading, extending, or troubleshooting Vite. Start with the migration checks, then open the topic reference that matches the task.

Reference index

Upgrade blockers first

Verify the Node.js runtime

Inspect the actual runtime locally and in CI:

node --version

Vite 7 requires Node.js 20.19+ or 22.12+. Node.js 18 is below that floor, and Node.js 21 was already unsupported by Vite 6. Do not treat an arbitrary Node.js 20 or 22 release as sufficient; the minor version matters.

These minimum versions provide unflagged require(esm). Vite can therefore ship as ESM-only while keeping its JavaScript API loadable from CommonJS.

Remove deleted APIs

Search an upgrading project for both removed surfaces:

rg "splitVendorChunkPlugin|legacy API" .

Vite 7 removes:

• Sass legacy API support.
• splitVendorChunkPlugin.

Migrate either dependency before expecting the upgraded build to work.

Recheck the default browser target

The default build.target changed from 'modules' to 'baseline-widely-available', fixed for each Vite major. For Vite 7, that default means Chrome 107, Edge 107, Firefox 104, and Safari 16.0.

Set build.target explicitly when the application's browser contract differs from those defaults. Leaving the target unset does not preserve the previous output compatibility.

Pair Vite with a supported Vitest

Vite 7 support begins with Vitest 3.2. Upgrade older Vitest installations when upgrading Vite instead of treating the unsupported pairing as an application failure.

High-value configuration

Try bundled development for large browser applications

The experimental bundled development mode serves bundled ESM while retaining HMR. It can reduce per-module request overhead that slows startup and reloads in large applications.

Enable it from the CLI:

vite --experimental-bundle

Or enable it in configuration:

import { defineConfig } from 'vite'

export default defineConfig({
  experimental: { bundledDev: true },
})

The mode remains experimental and limited. Validate framework integration, worker updates, and development behavior before adopting it for a team.

Stabilize chunk relationships with an import map

build.chunkImportMap prevents a changed chunk hash from cascading into every chunk that imports it. This can preserve more cached files between deployments.

import { defineConfig } from 'vite'

export default defineConfig({
  build: { chunkImportMap: true },
})

Do not combine this option with experimental.renderBuiltUrl; they are incompatible. Client chunk import maps can be used with sharedPlugins: true.

Use an ephemeral development-server port

Set server.port to 0 to ask Vite for a random available port. This is useful for isolated tests and concurrent development servers.

import { defineConfig } from 'vite'

export default defineConfig({
  server: { port: 0 },
})

Read the selected address from the running server instead of assuming a fixed port.

Import WebAssembly exports directly

WebAssembly ESM integration supports direct named exports from .wasm files:

import { add } from './add.wasm'

console.log(add(1, 2))

A ?init wrapper is not required for this direct ESM form.

Extend asset discovery for custom HTML

Use html.additionalAssetSources when custom elements or nonstandard attributes contain asset URLs:

import { defineConfig } from 'vite'

export default defineConfig({
  html: {
    additionalAssetSources: {
      'html-import': { srcAttributes: 'src' },
      img: { srcAttributes: ['data-src-dark', 'data-src-light'] },
    },
  },
})

Those files then enter Vite's normal asset-processing pipeline.

Match globbed files without case sensitivity

Pass caseSensitive: false to import.meta.glob when filename case should not affect the match:

const modules = import.meta.glob('./dir/module*.js', {
  caseSensitive: false,
})

Use the expanded Lightning CSS integration

With css.transformer: 'lightningcss', CSS files can import external CSS files and plugins can register file dependencies. These capabilities close two previous compatibility gaps with the PostCSS transformer.

import { defineConfig } from 'vite'

export default defineConfig({
  css: { transformer: 'lightningcss' },
})

Framework and bundler integration

The experimental Environment API lets framework and plugin authors implement development integrations that more closely match production. Normal single-client SPA behavior is unchanged, and existing custom SSR applications remain backward compatible.

For coordinated build work, the API exposes a buildApp hook so plugins can coordinate builds across multiple environments. Keep experimental integration code isolated behind framework or plugin boundaries.

To evaluate the future Rolldown-based bundler, replace the vite package with rolldown-vite. It is intended as a drop-in trial package before Rolldown becomes the default; test plugin and build behavior before committing to it.

Working checklist

1. Verify the exact Node.js minor version used locally and in CI.
2. Search for removed Sass and chunk-splitting APIs.
3. Decide whether the default browser target matches the product contract.
4. Upgrade Vitest to a supported pairing when necessary.
5. Keep experimental options explicit and test their incompatibilities.
6. Check configured top-level inputs against development-server filesystem access and plugin resolution.
7. Open the relevant reference file before editing configuration or plugin code.