Entry Point and Boot Process

Vite's entry point is surprisingly clean. In a codebase of over 50,000 lines, the path from vite in your terminal to a running dev server crosses only a handful of files. That's intentional — Vite's architecture separates concerns sharply, so each layer does one thing well.

Let's trace the boot sequence from the CLI command to a running dev server, understanding each decision along the way.

The bin Entry

When you run vite or vite dev, your shell resolves the command through the bin field in packages/vite/package.json. This points to packages/vite/bin/vite.js, a deliberately minimal file.

The bin file does almost nothing itself. It records the startup time, parses debug and filter flags from process.argv, enables the Node.js compile cache, and then dynamically imports the CLI module. This pattern — thin bin entry, heavy module — is common across the Node.js ecosystem. It keeps startup fast and makes the real logic testable.

flowchart TD
    A["$ vite dev"] --> B["bin/vite.js"]
    B --> C["cli.ts — parse args with cac"]
    C --> D{Command?}
    D -->|dev| E["createServer()"]
    D -->|build| F["build()"]
    D -->|preview| G["preview()"]
    D -->|optimize| H["optimizeDeps()"]
    E --> I["resolveConfig()"]
    I --> J["Plugin container init"]
    J --> K["HTTP server + HMR"]

CLI Argument Parsing

The actual CLI logic lives in packages/vite/src/node/cli.ts. Vite uses cac as its argument parser — a lightweight alternative to libraries like commander or yargs. If you've never seen cac before, don't worry: its API is almost identical to commander. The key point is that each subcommand (dev, build, preview) maps to a separate handler function.

One detail worth noting: the dev command is also the default. If you run vite with no subcommand, it's equivalent to vite dev. This is handled by cac's default command feature.

Tip: Read cli.ts top to bottom. It's well-structured and every flag maps to a config option. When you're confused about what a CLI flag does, this file is the definitive reference.

Config Resolution

Before anything meaningful happens, Vite needs to resolve its configuration. The resolveConfig function in config.ts is one of the most important functions in the entire codebase.

Config resolution follows a layered approach:

1. Inline config — options passed directly via the API (e.g., createServer({ root: './app' }))
2. Config file — vite.config.ts, vite.config.js, or other supported formats
3. Defaults — sensible fallback values for everything

flowchart LR
    A["Inline config"] --> D["mergeConfig()"]
    B["vite.config.ts"] --> D
    C["Defaults"] --> D
    D --> E["ResolvedConfig"]
    E --> F["Plugins sorted & applied"]

The config file itself is loaded through a surprisingly sophisticated process. Vite needs to handle TypeScript config files, ESM vs CJS formats, and even config files that import from node_modules. By default, it does this by bundling the config file with Rolldown at startup — yes, Vite uses its own bundler to build its own configuration. This is one of those design decisions that's obvious in hindsight but took real insight to arrive at.

Server Creation: The Heart of Dev Mode

The createServer function orchestrates everything needed for the development server. It's worth reading carefully, because it reveals Vite's architectural philosophy: compose independent systems through a shared context object.

Here's what createServer sets up, in order:

1. Config resolution — merging user config with defaults, as described above
2. Plugin container — initializing the Rollup-compatible plugin pipeline
3. Module graph — the ModuleGraph instance that tracks every module and its dependencies
4. WebSocket server — for HMR communication with the browser
5. File watcher — chokidar watching the project for file changes
6. Connect middleware stack — the HTTP server that serves transformed modules

The server object itself acts as the shared context. Every subsystem receives a reference to it, and they communicate by calling methods on each other through this shared reference. This is a deliberate alternative to an event-driven architecture — it's more explicit and easier to debug.

Tip: The ViteDevServer interface in server/index.ts is the best documentation for what the server can do. Read the type definition before diving into implementation details.

The Module Graph

The EnvironmentModuleGraph class in packages/vite/src/node/server/moduleGraph.ts deserves special attention. It's the data structure that makes Vite's HMR fast — when a file changes, the module graph knows exactly which modules are affected and need to be re-fetched by the browser. (A backward-compatible ModuleGraph wrapper lives in mixedModuleGraph.ts, combining per-environment graphs.)

Each node in the graph (EnvironmentModuleNode) tracks:

• Its URL and file path
• Which modules it imports (importedModules)
• Which modules import it (importers)
• Whether it's been HMR-accepted
• Its last transform timestamp

graph TD
    A["main.ts"] --> B["App.vue"]
    A --> C["router.ts"]
    B --> D["Header.vue"]
    B --> E["Footer.vue"]
    C --> F["routes/Home.vue"]
    C --> G["routes/About.vue"]
    style A fill:#e8f4fd,stroke:#333
    style B fill:#fde8e8,stroke:#333

When Header.vue changes, the module graph walks up the importer chain to find the nearest HMR boundary. If App.vue accepts HMR updates for its children, only that subtree gets invalidated. This is how Vite achieves near-instant HMR — it never invalidates more than necessary.

What You Need to Know

To read Vite's source effectively, you should be familiar with these concepts:

• Rollup plugin API — Vite extends Rollup's plugin interface with additional hooks for development. If you understand Rollup plugins, you understand 80% of Vite's plugin system.
• ES module semantics — import.meta, dynamic import(), and how browsers handle native ESM. This is the foundation that makes Vite's architecture possible.
• Node.js HTTP servers — Vite uses connect as its middleware framework. It's much simpler than Express, and that simplicity is intentional.
• Rolldown and OXC — Rolldown is used for dependency pre-bundling and production builds, while OXC handles TypeScript/JSX transpilation. Understanding these tools helps explain Vite 8's performance characteristics.

Directory Map

Here's a quick reference for the key files discussed in this article:

Path	Purpose
packages/vite/bin/vite.js	Thin bin entry point
packages/vite/src/node/cli.ts	CLI argument parsing with cac
packages/vite/src/node/config.ts	Config resolution and merging
packages/vite/src/node/server/index.ts	Dev server creation and orchestration
packages/vite/src/node/server/moduleGraph.ts	Per-environment module dependency graph
packages/vite/src/node/plugins/	Built-in plugin implementations

Next Steps

In the next article, we'll dive deep into the plugin system — how Vite extends Rollup's plugin interface, the order plugins execute in, and how the plugin container transforms modules on the fly during development.