Vite

Vite

Quick navigation

• Getting started: references/getting-started.md
• Philosophy and rationale: references/philosophy.md, references/why-vite.md
• Features: references/features.md
• CLI: references/cli.md
• Plugins (usage): references/using-plugins.md
• Plugin API: references/api-plugin.md
• HMR API: references/api-hmr.md
• JavaScript API: references/api-javascript.md
• Config reference: references/config.md
• Dependency optimization: references/dep-pre-bundling.md
• Assets: references/assets.md
• Build: references/build.md
• Static deploy: references/static-deploy.md
• Env & modes: references/env-and-mode.md
• SSR: references/ssr.md
• Backend integration: references/backend-integration.md
• Troubleshooting: references/troubleshooting.md
• Performance: references/performance.md
• Rolldown: references/rolldown.md
• Migration: references/migration.md
• Breaking changes: references/breaking-changes.md
• Environment API: references/api-environment.md
• Environment instances: references/api-environment-instances.md
• Env plugins: references/api-environment-plugins.md
• Env frameworks: references/api-environment-frameworks.md
• Env runtimes: references/api-environment-runtimes.md

Core rules

• Prefer minimal configuration; extend only as needed.
• Keep index.html as a first-class entry point when using Vite defaults.
• Treat dev server settings and build settings separately.
• Document mode-dependent behavior for env variables and define.
• Use future config to opt-in to deprecation warnings before migration.

Recipes

• Scaffold a project with npm create vite@latest.
• Configure aliases, server options, and build outputs in vite.config.*.
• Load .env values into config with loadEnv when config needs them.
• Add plugins with plugins: [] and define apply or enforce when needed.
• Use HMR APIs for fine-grained updates when plugin or framework needs it.
• Use optimizeDeps.include/exclude when deps aren't discovered on startup.
• Use build.rollupOptions.input for multi-page apps.
• Enable deprecation warnings: future: { removeSsrLoadModule: 'warn' }.
• Use hotUpdate hook instead of handleHotUpdate for environment-aware HMR.
• Use this.environment instead of options.ssr in plugin hooks.

Release Highlights (8.0.0)

• Default browser target is raised again under baseline-widely-available.
• CommonJS default-import interop becomes more consistent and may expose packages that relied on older ambiguous behavior.
• Vite stops resolving browser vs module via format sniffing and follows configured resolve.mainFields more strictly.
• JS API build() now throws BundleError with nested .errors when multiple Rolldown-level errors are present.
• Rolldown transition becomes more explicit: build.rollupOptions / worker.rollupOptions are deprecated in favor of *.rolldownOptions.

Patch Notes (8.0.14 -> 8.0.16)

• Rolldown moves to 1.0.3 (was 1.0.2 in 8.0.14); if you maintain plugin or build guidance, validate it against the current Rolldown behavior instead of assuming early 8.0.x patch semantics.
• Dev server now sends HTTP 408 on request timeout instead of hanging the connection (8.0.15).
• launch-editor-middleware rejects UNC paths and Windows alternate paths, closing a local path-traversal vector (8.0.16); relevant if you expose the dev server beyond localhost.
• 8.0.15 fixes: /@fs/ HTML-proxy cache-key mismatch, relative-glob-in-virtual-module errors when no files match, closing the Rolldown bundle when write() rejects, and onWarn for viteResolvePlugin in JS plugin containers.
• transformIndexHtml handles trailing-slash paths more reliably, which matters for plugins and static deploy setups that rewrite or inject HTML on directory-style URLs.
• Dependency scanning now passes Oxc JSX options through the optimizer path, so JSX-heavy linked dependencies should behave closer to the main transform pipeline.

Prohibitions

• Do not copy large verbatim chunks from vendor docs.
• Do not assume framework-specific behavior without verifying.

Links

• Documentation
• Releases
• GitHub
• npm

Environment API for Frameworks

Actionable notes from the frameworks guide.

Dev environment communication levels

• RunnableDevEnvironment: runs modules via runner.import() in same runtime.
• FetchableDevEnvironment: runtime communicates via Fetch API; preferred for portability.
• Raw DevEnvironment: requires custom communication (virtual modules or hot messages).

SSR middleware pattern

• Use middleware mode + transformIndexHtml.
• Use runner.import('/src/entry-server.js') for SSR rendering in dev.
• Add import.meta.hot.accept() in server entry to avoid full invalidation.

Build across environments

• vite build still builds client-only by default for compatibility.
• Use builder / vite build --app to build all environments.
• Frameworks can override builder.buildApp for parallel builds.

Environment-agnostic code

• Prefer this.environment in plugin hooks over server.environments.

Environment Instances

Actionable notes from the environment instances guide.

Accessing environments

• Use server.environments.client / server.environments.ssr in dev.
• Plugins can access the current environment in hooks.

DevEnvironment capabilities

• Each environment has its own moduleGraph, pluginContainer, and hot channel.
• transformRequest(url) resolves, loads, transforms, and updates the module graph.
• warmupRequest(url) queues low-priority processing to prevent waterfalls.

Separate module graphs

• Each environment has an isolated graph with EnvironmentModuleNode entries.
• HMR runs independently per environment using its graph.
• Backward compatibility layer exists for the old mixed graph.

Migration considerations

• Use environment-specific APIs instead of server.moduleGraph when possible.

Environment API for Plugins

Actionable notes from the environment plugins guide.

Current environment access

• Use this.environment in hooks instead of ssr boolean.
• Use environment.config and environment.moduleGraph for scoped behavior.

Configuring environments

• Add environments in config hook via environments.
• Use configEnvironment(name, options) to customize each environment.

HMR per environment

• Use hotUpdate hook; it runs per environment.
• Use this.environment.hot.send for custom events.

Per-environment state

• Use Map<Environment, State> keyed by this.environment.
• Enable perEnvironmentStartEndDuringDev / perEnvironmentWatchChangeDuringDev when needed.

Per-environment plugins

• applyToEnvironment(environment) filters or replaces plugin per env.
• Use perEnvironmentPlugin() helper to generate per-env plugin instances.

App-plugin communication

• environment.hot supports server↔client messages for that environment.
• vite:client:connect / vite:client:disconnect signal app instances.

Shared plugins during build

• builder.sharedConfigBuild: true enables shared config/pipeline.
• Plugins can opt-in with sharedDuringBuild: true.

Environment API for Runtimes

Actionable notes from the runtimes guide.

Environment factories

• Runtime providers create factory functions returning EnvironmentOptions.
• Factories define dev.createEnvironment and build.createEnvironment defaults.
• Users plug factories into environments config.

Creating a dev environment

• Use DevEnvironment plus a HotChannel transport.
• Choose a communication level compatible with framework needs.

Module Runner

• ModuleRunner executes transformed modules via vite/module-runner.
• Supports custom evaluators when runtime disallows new AsyncFunction.
• import() is the main API; clearCache() and close() manage lifecycle.

Transport

• Implement ModuleRunnerTransport with connect/send (or invoke).
• Emit vite:client:connect / vite:client:disconnect with stable client references.
• For HMR support, transport must provide send + connect.

Practical guidance

• Prefer the most flexible communication level for framework compatibility.
• Use createServerHotChannel for SSR HMR support.

Environment API (Introduction)

Actionable notes from the Environment API intro.

What it is

• Vite 6 formalizes environments beyond client and ssr.
• Supports multiple runtimes (browser, node, edge) in dev and build.

Config model

• Default SPA config still maps to client environment.
• Use environments to define extra environments (e.g., server, edge).
• Top-level options are defaults for client and other envs (unless marked non-inherit).

Environment options

• EnvironmentOptions includes define, resolve, optimizeDeps, dev, build.
• client env is always present; ssr env is present in dev and optionally in build.

Backward compatibility

• Existing Vite 5 APIs still work; module graph is mixed in dev.
• Environment API is RC; avoid full adoption for user apps unless needed.

Who should use it

• End users: basic awareness.
• Plugin authors: see environment plugins guide.
• Frameworks/runtimes: use framework/runtime guides for integration.

HMR API

Actionable notes from the HMR API guide.

Required guard

• Always wrap usage with if (import.meta.hot) { ... }.

Accept updates

• hot.accept(cb) to self-accept; callback receives updated module.
• hot.accept(deps, cb) to accept updates from specific dependencies.
• Keep exports mutable (let) if re-exporting from HMR boundaries.

Lifecycle helpers

• hot.dispose(cb) for cleanup before replacing module.
• hot.prune(cb) when module is removed entirely.
• hot.data persists between updates; mutate properties only.
• hot.invalidate() to force upstream reload; call accept first.

Events

• hot.on / hot.off for Vite events and custom plugin events.
• hot.send sends payloads to the dev server.

TypeScript

• Add vite/client types for IntelliSense.

JavaScript API

Actionable notes from the JS API guide.

Core entry points

• createServer() for dev server usage (supports middleware mode).
• build() for production builds.
• preview() for serving dist locally.

Server objects

• ViteDevServer exposes middlewares, ws, moduleGraph, transformRequest, and SSR helpers.
• PreviewServer exposes middlewares, httpServer, printUrls, and bindCLIShortcuts.

Config helpers

• resolveConfig(inlineConfig, command, ...) to resolve config programmatically.
• mergeConfig(defaults, overrides) for deep merges (objects only).
• loadConfigFromFile() to load config with esbuild.

Env helpers

• loadEnv(mode, envDir, prefixes) loads .env files.
• normalizePath() for plugin path comparisons.

Transform helpers

• transformWithEsbuild() for plugin transforms.
• preprocessCSS() (experimental) to pre-process CSS.

Important caveats

• When using createServer and build in one process, align mode/NODE_ENV.
• Middleware mode with WS proxy requires passing the parent server to middlewareMode.

Plugin API

Actionable notes from the plugin API guide.

Authoring basics

• Prefer existing features or plugins before writing a new plugin.
• Plugin names: vite-plugin-* for Vite-only, rollup-plugin-* for compatible.
• Use factory functions for configuration.

Key Vite hooks

• config and configResolved for config adjustments.
• configureServer / configurePreviewServer for middleware.
• transformIndexHtml for HTML transforms (use order: 'pre' | 'post').

8.0.14 note:

• If your plugin rewrites assets or injects tags in transformIndexHtml, re-test directory-style routes with trailing slashes. The patch line fixes path handling there, so old plugin workarounds may now be unnecessary or wrong.

HMR hooks

• handleHotUpdate — legacy hook, deprecated in favor of hotUpdate.
• hotUpdate — new environment-aware hook:
• Called per environment.
• Receives type: 'create' | 'update' | 'delete'.
• Access current environment via this.environment.
• Use this.environment.hot.send() instead of server.ws.send().
• Set future.removePluginHookHandleHotUpdate: 'warn' for warnings.

this.environment in hooks

• Available in resolveId, load, transform, options, onLog.
• Access: this.environment.config, this.environment.moduleGraph.
• Replaces options.ssr boolean; use this.environment.config.consumer === 'server'.
• Set future.removePluginHookSsrArgument: 'warn' for warnings.

Ordering and conditions

• Use enforce: 'pre' | 'post' for ordering.
• Use apply: 'serve' | 'build' to scope a plugin to dev/build.

Virtual modules

• Use virtual:* ids and resolve to \0virtual:*.
• Avoid \0 for modules derived from real files (SFC submodules).

Rollup compatibility

• Rollup plugins that don’t rely on moduleParsed or output hooks usually work.
• Build-only plugins can go in build.rollupOptions.plugins.

Filtering and normalization

• Use createFilter from @rollup/pluginutils (re-exported by Vite).
• Normalize paths with normalizePath before matching.
• Hook filters (Rollup 4.38+ / Vite 6.3+) can reduce overhead.

Client/server events

• Use server.ws.send to broadcast, and import.meta.hot.on to receive.
• Use import.meta.hot.send for client-to-server events.
• Extend vite/types/customEvent.d.ts for typed payloads.

Static Asset Handling

Actionable notes from the static assets guide.

Importing assets

• Importing an asset returns its resolved public URL.
• Assets are hashed and included in the build graph.
• assetsInlineLimit controls base64 inlining.

Explicit queries

• ?url forces URL import.
• ?inline or ?no-inline controls inlining.
• ?raw loads the asset as a string.
• ?worker / ?sharedworker for worker imports.

public directory

• Use public/ for assets that must keep filenames or aren’t imported.
• Reference public assets with absolute paths (e.g. /icon.png).
• publicDir config changes the folder name.

new URL(..., import.meta.url)

• Works in browser with static URL strings; Vite rewrites during build.
• Dynamic or non-static URLs are not transformed.
• Not suitable for SSR because import.meta.url semantics differ in Node.

Gotchas

• For CSS url() with SVGs in JS strings, wrap in double quotes.
• Add vite/client types when TypeScript complains about asset imports.

Backend Integration

Actionable notes from the backend integration guide.

Dev setup

• Enable CORS or proxy asset requests to the Vite dev server.
• Inject Vite client and entry script from http://localhost:5173.
• For React, add the refresh preamble script before Vite client scripts.

Build setup

• Enable build.manifest: true and set build.rollupOptions.input to your entry.
• Import vite/modulepreload-polyfill if the polyfill is enabled.

Using the manifest

• Manifest maps entry points to hashed files, CSS, and imports.
• Render tags in this order for best performance:

1. Entry CSS files 2. CSS for imported chunks 3. Entry JS file 4. Optional modulepreload links for imported JS chunks

Key options

• server.origin can point generated asset URLs at the backend domain.
• Use manifest data to generate HTML tags in your server templates.

Breaking Changes

Actionable notes from the breaking changes index.

Planned (next major)

• options.ssr in hooks → this.environment
• handleHotUpdate hook → hotUpdate hook
• server.ssrLoadModule → ModuleRunner API
• server.warmupRequest → environment.warmupRequest
• server.pluginContainer → environment.pluginContainer
• server.moduleGraph → environment.moduleGraph
• server.hot → environment.hot
• server.reloadModule → environment.reloadModule

Deprecation warnings via future

Enable warnings in vite.config.js to prepare for migration:

export default defineConfig({
  future: {
    removePluginHookSsrArgument: "warn",
    removePluginHookHandleHotUpdate: "warn",
    removeSsrLoadModule: "warn",
    removeServerPluginContainer: "warn",
    removeServerReloadModule: "warn",
    removeServerHot: "warn",
    removeServerWarmupRequest: "warn",
    removeServerModuleGraph: "warn",
  },
});

Considering (experimental)

• Per-environment APIs
• Shared plugins during build

Practical guidance

• Treat items here as forward-looking; prefer stable APIs.
• Use future config option for opt-in warnings.
• Monitor linked discussions when you rely on these APIs.

Already effective in Vite 8

• CJS default-import interop is stricter and more consistent.
• Format sniffing for browser vs module resolution is gone.
• Passing a URL to import.meta.hot.accept is no longer supported; pass an id instead.

Building for Production

Actionable notes from the build guide.

Browser compatibility

• Default targets: modern Baseline widely available browsers.
• Customize via build.target (lowest is es2015).
• Vite does syntax transforms only; add polyfills separately or use @vitejs/plugin-legacy.

Public base path

• Set base to deploy under a subpath; works for JS, CSS, and HTML assets.
• Use import.meta.env.BASE_URL for dynamic base URL in code (must be exact).
• Relative base ("./" or "") requires import.meta support.

Build customization

• Use build.rollupOptions for custom outputs and build-only plugins.
• Use build.rollupOptions.output.manualChunks for chunk splitting.
• build.emitLicense (default: true) — emit LICENSE file with bundled deps.

Operational hooks

• Listen for vite:preloadError to handle stale chunk errors after deploys.
• Use vite build --watch or build.watch for rebuild-on-change.

Multi-page apps

• Provide multiple HTML entries via build.rollupOptions.input.
• The resolved HTML file path determines output structure.

Library mode

• Use build.lib to produce library bundles (ES + UMD/CJS).
• Externalize dependencies in rollupOptions.external.
• CSS for libraries is extracted to a single file; export it in package.json.

Advanced base options (experimental)

• Use experimental.renderBuiltUrl for custom CDN or split public paths.

Command Line Interface

Actionable notes from the Vite CLI page.

Dev server

• vite starts the dev server; vite dev and vite serve are aliases.
• Common options: --host, --port, --open, --cors, --strictPort.
• --force forces dependency re-bundling.
• -m, --mode selects the env mode.

Build

• vite build produces production output.
• Common options: --target, --outDir, --assetsDir, --assetsInlineLimit.
• --ssr builds an SSR entry; --ssrManifest emits SSR manifest.
• --sourcemap supports inline and hidden.
• --minify accepts esbuild, terser, or false.

Preview

• vite preview serves the built output from dist by default.
• Useful for local verification; not meant as a production server.

Optimize (deprecated)

• vite optimize triggers dependency pre-bundling but is deprecated.

Shared CLI behavior

• -c, --config <file> sets a config file.
• --base <path> sets the public base.
• --configLoader controls how config is loaded (experimental variants).
• -d, --debug and -f, --filter for debugging.

Config Reference

Actionable notes from the Vite config index.

Config file basics

• Vite auto-resolves vite.config.* from project root.
• Config can be ESM even without type: module.
• Use defineConfig() for IntelliSense.
• import.meta.resolve supported in ESM config (bundle loader).

Conditional/async config

• Export a function to branch on command, mode, isSsrBuild, isPreview.
• Export async config if you need async values.

Environment variables in config

• .env* files are loaded after config is resolved.
• Use loadEnv(mode, envDir, prefix) if config needs .env values.

Config loader

• Default loader bundles config with esbuild.
• --configLoader runner uses module runner (no temp file, no CJS config).
• --configLoader native uses native runtime; no auto-restart for imports.

Debugging config

• Use VS Code resolveSourceMapLocations to debug config when using bundled loader.

Future deprecations (future)

• future: Record<string, 'warn' | undefined> — opt-in warnings for next major.
• Enable warnings for deprecations you use:

export default defineConfig({
  future: {
    removePluginHookSsrArgument: "warn", // options.ssr → this.environment
    removePluginHookHandleHotUpdate: "warn", // handleHotUpdate → hotUpdate
    removeSsrLoadModule: "warn", // ssrLoadModule → ModuleRunner
    removeServerPluginContainer: "warn",
    removeServerReloadModule: "warn",
    removeServerHot: "warn",
  },
});

Vite 8 migration notes

• build.rollupOptions and worker.rollupOptions are deprecated in favor of build.rolldownOptions / worker.rolldownOptions.
• build.commonjsOptions is now effectively a no-op in the Rolldown path.
• If CommonJS default-import behavior regresses for a dependency, use legacy.inconsistentCjsInterop: true only as a temporary migration shim.

Dependency Pre-Bundling

Actionable notes from the dependency pre-bundling guide.

Why it exists

• Converts CJS/UMD deps to ESM for dev server compatibility.
• Collapses large ESM dep graphs into single modules to reduce browser requests.
• Uses esbuild for speed; production uses Rollup + commonjs plugin instead.

Automatic discovery

• Vite scans source for bare imports and pre-bundles them on first run.
• Newly discovered deps trigger a re-bundle + page reload.

Monorepos and linked deps

• Linked packages are treated as source, not deps.
• If linked deps are CJS, add to optimizeDeps.include and build.commonjsOptions.include.
• Restart dev server with --force after linked dep changes.

Tuning behavior

• Use optimizeDeps.include / exclude for imports not visible in source.
• Use optimizeDeps.esbuildOptions for special handling.
• In 8.0.14, dependency scanning passes Oxc JSX options through its transform path. If a linked dependency relies on non-default JSX parsing/runtime settings, keep optimizer and app-level JSX expectations aligned before debugging scan-only failures.

Caching

• Cache in node_modules/.vite is invalidated by lockfile, patches, config, or NODE_ENV.
• Browser cache is aggressive; disable cache + restart with --force when debugging deps.

Env Variables and Modes

Actionable notes from the env and modes guide.

Built-in constants

• import.meta.env.MODE, BASE_URL, PROD, DEV, SSR are always available.

.env files and loading order

• Loads .env, .env.local, .env.[mode], .env.[mode].local.
• Mode-specific files override generic ones.
• Existing process env values override file values.
• Restart dev server after editing .env files.

Exposure rules

• Only VITE_* variables are exposed to client code.
• Values are strings; parse booleans/numbers yourself.
• Use envPrefix to change the prefix.
• Do not store secrets in client-exposed vars.

TypeScript IntelliSense

• Augment ImportMetaEnv in vite-env.d.ts.
• Do not add import statements in the d.ts file, or augmentation breaks.

HTML replacements

• Use %CONST_NAME% in HTML to replace with import.meta.env values.
• Missing constants are ignored in HTML (not replaced).

Modes vs NODE_ENV

• Modes (--mode) are distinct from NODE_ENV.
• vite build defaults to mode production.
• You can set NODE_ENV via command or .env.[mode] to influence behavior.

Getting Started (Guide)

Actionable notes from the Vite guide start page.

What Vite is

• Vite provides a fast dev server with enhanced native ES module support and a production build that uses Rollup.
• The dev server focuses on fast iteration (HMR and native ESM). The build targets optimized static assets.

First run / scaffolding

• Recommended scaffolding command: npm create vite@latest.
• Online playground: https://vite.new/ supports framework templates (vanilla, vue, react, preact, lit, svelte, solid, qwik and TS variants).

Project structure basics

• index.html is the application entry and is treated as source.
• Absolute URLs resolve from the project root (<root>).
• You can set a different root with vite serve <path>; config is resolved inside the root.
• Multi-page apps are supported with multiple HTML entry points.

CLI basics

• Common scripts: vite (dev), vite build, vite preview.
• Extra flags like --port and --open are available; npx vite --help lists all options.

Browser targets

• Dev uses modern browser assumptions and esnext transform target.
• Production targets a baseline of widely-available browsers; can be lowered in config.

Using unreleased Vite

• You can install a specific commit via https://pkg.pr.new/vite@<SHA>.
• To use a local checkout, link packages/vite after building.

Cross-links (next steps)

• Features, Plugins, Config, Build, and HMR are covered in their dedicated pages.

Migration to v8

Actionable notes for upgrading to Vite 8.

Node support

• Node.js 18 is dropped; require Node 20.19+ or 22.12+.

Browser target defaults

• Default build.target now aligns with Baseline widely available browsers.
• Old modules target removed; new default is baseline-widely-available.

Removed or changed features

• Sass legacy API removed; drop css.preprocessorOptions.*.api legacy settings.
• splitVendorChunkPlugin removed; use build.rollupOptions.output.manualChunks.
• transformIndexHtml hook now uses { order, handler } instead of enforce/transform.

Vite 8-specific migration items

• build.target: 'baseline-widely-available' now maps to newer browser baselines (Chrome/Edge 111, Firefox 114, Safari 16.4).
• Default import interop for CommonJS is more consistent; if a dependency breaks, use the temporary legacy.inconsistentCjsInterop: true escape hatch while you fix or patch the package.
• Module resolution no longer sniffs file contents to choose between browser and module; it follows resolve.mainFields ordering more strictly.
• build() in the JS API throws BundleError; inspect .errors if you need per-error details.
• build.rollupOptions and worker.rollupOptions are deprecated in favor of build.rolldownOptions and worker.rolldownOptions.

Advanced removals

• Deprecated SSR/resolve properties removed; review custom tooling.
• optimizeDeps.entries treats values as globs.
• Some middlewares are applied before configureServer/configurePreviewServer.

Upgrade path

• Follow older migration guides in sequence if you are skipping majors.
• For Vite 8 upgrades, validate plugin behavior, CJS imports, and custom config/build scripts before rolling out broadly.

Performance

Actionable notes from the performance guide.

Browser and cache

• Disable extensions for dev profile; use incognito for faster reloads.
• Ensure “Disable Cache” is off in DevTools for Vite dev server.

Plugin audit

• Avoid heavy work in buildStart, config, configResolved.
• Gate expensive transforms by extension/keyword checks.
• Use vite --debug plugin-transform or vite-plugin-inspect to spot slow hooks.

Resolve costs

• Prefer explicit import extensions to reduce filesystem checks.
• Consider narrowing resolve.extensions if safe.
• In TS: moduleResolution: "bundler" and allowImportingTsExtensions: true.

Avoid barrels

• Import specific files instead of index re-exports to reduce waterfall.

Warmup

• Use server.warmup.clientFiles for frequently hit heavy files.
• --open or server.open will warm the entry automatically.

Tooling tradeoffs

• Prefer native CSS and avoid unnecessary transforms.
• Use @vitejs/plugin-react-swc for faster React builds.
• Consider Rolldown/LightningCSS if aligned with your stack.

Project Philosophy

Actionable notes from the Vite philosophy page.

Design goals

• Keep core lean and extensible; push features into plugins whenever possible.
• Maintain a small API surface to improve long-term maintainability.
• Align plugin behavior with Rollup to share ecosystem value.

Modern web stance

• Source is ESM-first; non-ESM deps must be pre-bundled.
• Encourage modern patterns (e.g., new Worker syntax).
• Node.js built-ins are not assumed to be available in the browser.

Performance approach

• Dev server architecture prioritizes fast HMR at scale.
• Use native tools (esbuild, SWC) for heavy transforms; keep core in JS for flexibility.
• Builds rely on Rollup for bundle size and plugin ecosystem.

Frameworks and integrations

• Vite is framework-agnostic but designed to enable framework tooling.
• JS API and SSR primitives support framework authors.
• Backend integrations exist (e.g., Ruby, Laravel) via dedicated plugins.

Ecosystem health

• Releases are coordinated with framework/plugin maintainers.
• Ecosystem CI is used to spot regressions early.

Practical takeaways

• Prefer a plugin when extending behavior instead of forking core.
• Plan for ESM-only source and pre-bundling constraints.
• For framework tooling, lean on JS API + plugin hooks rather than re-implementing pipeline pieces.

Rolldown Integration

Actionable notes from the Rolldown integration guide.

What Rolldown is

• Rust bundler designed as a Rollup drop-in replacement.
• Goals: speed, plugin compatibility, and advanced optimizations.

Why Vite is migrating

• Unify dependency optimization and build under one bundler.
• Improve performance and capabilities (chunking, HMR, module federation).

Trying rolldown-vite

• Alias vite to rolldown-vite in package.json.
• Pin versions; it’s experimental.
• Use package manager overrides when Vite is a peer dep.

Known limitations

• Some Rollup options are unsupported; expect validation warnings.
• manualChunks is deprecated in favor of advancedChunks.
• build.rollupOptions / worker.rollupOptions are deprecated in favor of build.rolldownOptions / worker.rolldownOptions during the transition.

Performance knobs

• Native plugins enabled by default (experimental.enableNativePlugin).
• @vitejs/plugin-react uses Oxc refresh transform for speed.
• Use withFilter wrapper to reduce hook overhead.

Plugin author notes

• Detect rolldown-vite via this.meta.rolldownVersion or vite.rolldownVersion.
• Vite 8.0.15 bumps Rolldown to 1.0.3 (8.0.14 shipped 1.0.2); re-check any workaround that targeted pre-1.0.3 Rolldown quirks before keeping it in build guidance.
• If you use transformWithEsbuild, add esbuild as a dependency or switch to transformWithOxc.
• Set moduleType: 'js' when transforming non-JS content.
• If you catch build errors programmatically, expect BundleError with a nested .errors array instead of assuming a single raw plugin exception.

Server-Side Rendering (SSR)

Actionable notes from the SSR guide.

Project structure

• entry-client mounts the app; entry-server renders to HTML.
• index.html includes an SSR outlet placeholder and entry-client module.

Dev server integration

• Use Vite in middleware mode (server.middlewareMode: true, appType: 'custom').
• Use vite.transformIndexHtml() for HTML transforms.

Legacy: ssrLoadModule

• vite.ssrLoadModule() — deprecated, use ModuleRunner instead.
• vite.ssrFixStacktrace() — not needed with ModuleRunner.
• Set future.removeSsrLoadModule: 'warn' to see warnings.

ModuleRunner API (recommended)

• Each environment has a ModuleRunner for importing modules.
• Use moduleRunner.import(url) instead of ssrLoadModule.
• Stack traces automatically fixed (unless sourcemapInterceptor: false).
• Works with custom environments running in separate threads/processes.

// Example with RunnableDevEnvironment
const environment = server.environments.ssr;
if (environment instanceof RunnableDevEnvironment) {
  const runner = environment.runner;
  const mod = await runner.import("/src/entry-server.js");
}

Production build

• Build client and server separately (vite build --ssr).
• Use dist/client/index.html as the template.
• Import the SSR bundle directly (no ssrLoadModule).

SSR manifest

• Use --ssrManifest on the client build to map module IDs to assets.
• Pass manifest to entry-server to generate preload directives.

Externals

• SSR externalizes deps by default.
• Use ssr.noExternal for deps that need Vite transforms.
• Use ssr.external to force externalization for linked deps.
• ssr.resolve.mainFields — customize main fields resolution for SSR.
• ssr.resolve.conditions — customize export conditions for SSR.

Plugin hooks

• options.ssr in hooks — deprecated.
• Use this.environment.config.consumer === 'server' instead.
• Set future.removePluginHookSsrArgument: 'warn' for warnings.

Targets and bundling

• Default SSR target is Node; ssr.target: 'webworker' for worker runtimes.
• ssr.noExternal: true bundles all deps and forbids Node built-ins.

Deploying a Static Site

Actionable notes from the static deploy guide.

General flow

• Build with npm run build → deploy dist.
• Test locally with npm run preview (not a production server).
• Set base for subpath deployments (GitHub Pages/GitLab Pages).

Platform highlights

• GitHub Pages: set base to / for user site, or /<repo>/ for project site; deploy via Actions.
• GitLab Pages: similar base rules; use .gitlab-ci.yml to build and publish.
• Netlify/Vercel: import repository; Vite preset auto-detected.
• Cloudflare Pages: deploy via Wrangler (wrangler pages deploy dist) or Git integration.
• Firebase/Surge/Azure/Render: configure dist as output directory.

Key cautions

• vite preview is for local verification only.
• Ensure base matches the deployment URL to avoid broken assets.

Troubleshooting

Actionable notes from the troubleshooting guide.

CLI / config

• Windows paths containing & break npm shims; remove & or switch package manager.
• ESM-only deps in config: use ESM config (type: module or .mjs/.mts).

Dev server issues

• Stalled requests on Linux: raise file descriptor and inotify limits.
• Self-signed certs in Chrome break caching; use trusted cert.
• 431 errors: reduce header size or increase --max-http-header-size.
• Dev containers: set server.host: '0.0.0.0' so forwarded ports are reachable (using 127.0.0.1 limits access to the container's localhost only).

HMR issues

• Case mismatch in imports prevents HMR; fix file casing.
• Circular deps can trigger full reload; use vite --debug hmr.

Build issues

• Opening dist via file:// causes CORS errors; use vite preview.
• Case-sensitive FS errors: fix import casing.
• Dynamic import fetch errors: handle version skew or missing chunks.

Optimized deps

• Linked deps may need vite --force to re-optimize.

Other notes

• Vite does not polyfill Node built-ins in browser code.
• Strict-mode only; patch dependencies if they rely on sloppy mode.

Using Plugins

Actionable notes from the plugins usage guide.

Add plugins

• Install plugin in devDependencies and add it to plugins in vite.config.*.
• plugins can include presets (arrays) that are flattened.
• Falsy entries are ignored (useful for conditional toggles).

Find plugins

• Check the Vite Features guide first; Vite may already cover your need.
• Official plugins: https://vite.dev/plugins/
• Community plugins: https://github.com/vitejs/awesome-vite#plugins
• Recommended conventions: vite-plugin-* or rollup-plugin-*.

Order and conditions

• Use enforce: 'pre' | 'post' to set order relative to Vite core plugins.
• Use apply: 'serve' | 'build' to run only in dev or build.

Practical takeaways

• Prefer Vite-native plugins for dev server integration.
• Only force ordering when a plugin requires it; avoid overusing enforce.
• Keep plugin logic environment-specific with apply.

Why Vite

Actionable notes from the "Why Vite" page.

Core problems Vite solves

• Bundler-based dev servers cold-start by eagerly building all modules.
• Large apps slow down incremental rebuilds; HMR can degrade with size.

Vite dev server approach

• Split code into dependencies and source.
• Pre-bundle dependencies with esbuild for fast startup.
• Serve source over native ESM; transform on-demand as the browser requests modules.
• HMR invalidates only the minimal boundary chain, keeping updates fast.
• Uses caching headers to avoid unnecessary reloads.

Why still bundle for production

• Unbundled ESM causes extra network round-trips in production.
• Bundling enables tree-shaking, code splitting, and better caching.
• Vite provides a pre-configured production build for parity and performance.

Why not bundle with esbuild

• Vite relies on Rollup’s flexible plugin API for ecosystem compatibility.
• esbuild is faster but less flexible for Vite’s plugin model.
• Future direction: Rolldown aims to improve build performance while keeping flexibility.

Practical takeaways

• Expect different goals in dev (speed) vs build (optimized output).
• Use dependency pre-bundling when you see slow cold starts or CJS interop issues.
• Plugin compatibility is a key reason Vite uses Rollup for builds.