Understanding vite

A from-the-source book on Vite internals

A self-paced, hands-on study guide that turns the vitejs/vite repository into something you genuinely understand — not just npm create vite and vite dev.

---

Who this book is for (you)

You've shipped frontends for years. You wired up temlet as a Next.js app and you're carrying it across the web→native seam into Tauri, where the frontend is bundled by Vite and served behind a native shell instead of a Node server. You're building mang — a micro-app web shell with a command-K launcher, where dozens of small apps need to load fast, hot-reload in isolation, and ship as lean bundles. In both, Vite is the thing actually turning your .ts and .tsx into something a browser runs — and most of the time it is invisible. You run vite, the page just appears, you save a file, it just updates.

That invisibility is not magic. It falls out of one disciplined bet: in development, the browser's own native ESM loader is the module system — Vite never bundles your app to start the dev server; it just transforms one module at a time, on demand, as the browser asks for it. Everything else — the module graph, HMR, dependency pre-bundling, even the production build — is built around that one decision (and the fact that for production you do want a bundle, which is where Rolldown comes in).

This book opens the box. By the end you'll be able to take a single browser request for /src/main.ts, predict the exact path it takes from the dev server's middleware through transformRequest and the plugin container to the rewritten JavaScript that comes back, point to the precise .ts file and line where each layer does its work, and explain why the dev server feels instant while the production build is a wholly different machine.

---

What you'll be able to do

• Trace a request end-to-end — from a browser GET /src/main.ts through transformMiddleware, transformRequest, the plugin container's resolveId → load → transform, and back out as rewritten ESM, naming every hop by file:line.
• Explain the dev server — why Vite serves unbundled native ESM, how the EnvironmentModuleGraph caches every module's transform result, and how the import-analysis plugin rewrites import 'vue' into a URL the browser can actually fetch.
• Reason about HMR — read hmr.ts and predict how a saved file walks its importer chain to find an accepting boundary, and what gets sent over the WebSocket when it does (or doesn't).
• Understand pre-bundling — why Vite runs esbuild over your node_modules before the first request, how it hashes the result to cache it, and how it discovers new deps mid-session.
• Cross the dev/build seam — how the same plugins drive Rolldown for the production bundle, and how the Environment API generalizes "client vs SSR" into first-class, per-environment pipelines.

---

How this book is built (the grounding contract)

Every claim is grounded in source you can open:

• 📌 Pinned ref. This book is written against Vite v8.0.16 (commit f94df87). A read-only clone lives beside the book at ../vite; the code we cite is under packages/vite/src/node/.
• 🔎 file:line citations. Every walkthrough cites exact locations like packages/vite/src/node/server/transformRequest.ts:78. Open the clone and read along — the line numbers resolve to the symbol described.
• 🧪 Labs you run. Each chapter ends with a small lab you run yourself with pnpm and a real Vite project, with a stated expected result you record in labs/.

⚠️ Vite v8 is a fast-moving line. When you re-pin to a newer tag, line numbers will drift and Rolldown's surface may shift. Chapter 8 shows you how to re-sync.

🧠 Mental model: this is not "the Vite docs, longer." The docs teach you to use Vite. This book teaches you to read Vite — so that when the dev server does something surprising, you know which file to open.

---

The curriculum

Nine chapters, 00–08, with Chapter 03 (the dev server) as the flagship — the deepest chapter, where the "how does this actually work" core lives.

#	Chapter	Weight
00	Environment & TS / ESM / native-module refresher	Foundation
01	Mental model & repo map	Foundation
02	Config resolution & the plugin container	Core
03	★ The dev server, module graph & transform pipeline	Flagship
04	HMR: boundary propagation & import.meta.hot	Core
05	Dependency pre-bundling (the optimizer)	Core
06	The production build (Rolldown)	Application
07	SSR, the module runner & the Environment API	Application
08	Capstone: write a plugin & stay current	Mastery

Depth is intentionally weighted toward 03. The on-demand transform pipeline is where Vite earns its "instant" reputation, and it rewards the deepest read.

---

Per-chapter shape

Every chapter follows the same rhythm:

1. Goal — one paragraph, with the pinned ref.
2. Why it matters — the problem this layer solves.
3. Mental model + ASCII diagram — a picture to hold in your head.
4. Guided source read — exact file:line citations into ../vite.
5. Lab — commands you run, with an expected observation, recorded in labs/.
6. Checkpoint — 4–6 questions; if one is shaky, it points you back to the section to re-read.
7. 🔌 Connect to your past — a bridge from the concept to your mang micro-app shell and your temlet Next.js→Tauri / web→native work.

---

Pace

This is a two-to-three week book if you do the labs. A reasonable cadence:

• Days 1–2: Chapters 00–01 (setup + mental model).
• Days 3–4: Chapter 02 (config + the plugin container).
• Days 5–8: Chapter 03 — the flagship. Don't rush it.
• Days 9–11: Chapter 04 (HMR).
• Days 12–14: Chapter 05 (pre-bundling).
• Days 15–18: Chapters 06–07 (build + environments).
• Days 19+: Chapter 08 (capstone) and a re-read of anything shaky.

---

Progress checklist

• 00 — green build of Vite from source, ESM + bare-import problem understood
• 01 — traced one browser request end-to-end
• 02 — explained plugin ordering and what resolveConfig produces
• 03 — explained transformRequest, the module graph, and the import rewrite ★
• 04 — predicted how a saved file finds (or fails to find) an HMR boundary
• 05 — explained why and how deps are pre-bundled, and what invalidates the cache
• 06 — explained how plugins drive Rolldown for the production build
• 07 — explained ssrTransform, the module runner, and the Environment API
• 08 — read a real Vite PR unaided

---

Layout

vite-book/
├── README.md                 ← you are here
├── 00..08-*.md               ← the nine chapters (03 is the flagship)
├── labs/                     ← lab notes + a runnable vite-hello artifact
│   ├── README.md
│   ├── dev-baseline.md
│   └── vite-hello/
├── reference/glossary.md     ← terms by category + a Key-files source index
├── diagrams/                 ← (placeholder)
└── site_src/build_site.py    ← the static-site generator (RumitX kit)

The companion clone is at ../vite, pinned to v8.0.16. Keep it open.

Start: Chapter 0 — Environment & TS / ESM / Native-Module Refresher →

---

A RumitX publication · rumitx.com