Vite Core Architecture

vite-core-architecture

Quick Reference

Two-Mode Architecture

Vite operates as two completely different systems depending on context:

Internal Tools Evolution

Node.js Requirements

Browser Support Targets

Critical Warnings

NEVER set envPrefix to '' -- this exposes ALL environment variables (including secrets like DB_PASSWORD) to client-side code.

NEVER exclude CommonJS dependencies from pre-bundling via optimizeDeps.exclude -- they MUST be pre-bundled to be converted to ESM for the dev server.

NEVER edit files in node_modules/.vite/ -- this is the pre-bundling cache directory. Use optimizeDeps.force: true or --force CLI flag to rebuild it.

NEVER use a JavaScript file as the application entry point -- Vite uses index.html as the entry point. The HTML file references your scripts via <script type="module" src="...">.

ALWAYS use defineConfig() wrapper for vite.config.ts -- this provides TypeScript IntelliSense and type checking for all configuration options.

ALWAYS run tsc --noEmit separately for type checking -- Vite performs transpile-only (no type checking) for speed. NEVER rely on Vite for TypeScript type safety.

How Vite Works

Dev Server: Native ESM Serving

The dev server serves source files as native ES modules over HTTP:

1. Browser requests index.html from http://localhost:5173/
2. HTML contains <script type="module" src="/src/main.ts">
3. Browser requests /src/main.ts, Vite transforms it on-the-fly (TypeScript, JSX, etc.)
4. Browser parses import statements and requests each dependency
5. Vite intercepts node_modules imports and serves pre-bundled versions

No bundling step occurs. Each source file is an individual HTTP request. HMR updates propagate through the module graph -- only changed modules are replaced.

Dependency Pre-Bundling

Pre-bundling runs automatically on first vite startup for two reasons:

1. CommonJS/UMD to ESM conversion -- the dev server serves ONLY native ESM
2. Performance -- packages like lodash-es (600+ modules) are consolidated into a single request

Pre-bundling results are cached in node_modules/.vite. Cache invalidates when: lockfile changes, vite.config changes, NODE_ENV changes, or patches folder changes.

Production Build Pipeline

vite build bundles the entire application:

1. Resolves the module graph starting from index.html entry points
2. Applies all plugin transforms (JSX, TypeScript, CSS modules, etc.)
3. Bundles via Rolldown (v8) or Rollup (v5-7) with code splitting
4. Minifies JS via Oxc (v8) or esbuild (v5-7)
5. Minifies CSS via Lightning CSS (v8) or esbuild/lightningcss (v5-7)
6. Outputs optimized static assets to dist/

index.html as Entry Point

Unlike Webpack or other bundlers, Vite treats index.html as the entry point:

<root>/index.html       → http://localhost:5173/
<root>/about.html       → http://localhost:5173/about.html
<root>/nested/page.html → http://localhost:5173/nested/page.html

Vite resolves <script type="module" src="..."> tags and inline <script type="module"> blocks, processing all referenced modules and CSS.

Decision Trees

Choosing a Framework Template

Creating new project with create-vite?
├── React app?
│   ├── Want Babel plugins?     → react-ts (uses @vitejs/plugin-react with Babel)
│   └── Want fastest transforms? → react-swc-ts (uses @vitejs/plugin-react-swc)
├── Vue app?                    → vue-ts (uses @vitejs/plugin-vue)
├── Svelte app?                 → svelte-ts
├── Solid app?                  → solid-ts
├── Preact app?                 → preact-ts
├── Lit web components?         → lit-ts
├── Qwik app?                   → qwik-ts
└── No framework?               → vanilla-ts

ALWAYS use the -ts variant -- TypeScript variants include proper type definitions and vite-env.d.ts.

Choosing Build Target

What browsers must you support?
├── Modern only (Chrome 111+, Safari 16.4+) → Default (baseline-widely-available)
├── Slightly older (ES2020, etc.)           → Set build.target: 'es2020'
├── IE11 / very old browsers                → Add @vitejs/plugin-legacy
└── Server-side / Node.js                   → Set build.target: 'node20'

Official Plugins

CLI Commands

Key flags: --port <number>, --open, --mode <mode>, --force (re-bundle deps), --host (expose to LAN).

Standard package.json Scripts

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Project Structure

my-vite-app/
├── index.html              # Application entry point (NOT in src/)
├── public/                 # Static assets (copied as-is, no processing)
│   └── favicon.ico
├── src/
│   ├── main.ts             # Module entry (referenced from index.html)
│   ├── App.tsx              # Root component (framework-dependent)
│   ├── vite-env.d.ts        # Vite client type declarations
│   └── assets/              # Processed assets (images, fonts, etc.)
├── vite.config.ts           # Vite configuration
├── tsconfig.json            # TypeScript configuration
├── package.json             # Dependencies and scripts
└── node_modules/
    └── .vite/               # Pre-bundling cache (auto-generated)

ALWAYS place index.html at the project root (not inside src/) -- Vite expects it at the root directory.

Reference Links

• references/internals.md -- Version evolution details, module graph internals, build pipeline specifics
• references/examples.md -- Minimal project setup, CLI commands, package.json scripts
• references/anti-patterns.md -- Common architecture mistakes with explanations

Official Sources

• https://vite.dev/guide/
• https://vite.dev/config/
• https://vite.dev/guide/dep-pre-bundling
• https://vite.dev/guide/cli
• https://vite.dev/plugins/