vite-impl-javascript-api
Quick Reference
Core API Functions
| Function |
Return Type |
Purpose |
createServer(inlineConfig?) |
Promise<ViteDevServer> |
Start a programmatic dev server |
build(inlineConfig?) |
Promise<RollupOutput | RollupOutput[]> |
Run a production build |
preview(inlineConfig?) |
Promise<PreviewServer> |
Start a preview server for built output |
resolveConfig(inlineConfig, command, ...) |
Promise<ResolvedConfig> |
Resolve and merge all config sources |
mergeConfig(defaults, overrides, isRoot?) |
Record<string, any> |
Deep-merge two Vite configs |
loadConfigFromFile(configEnv, ...) |
Promise<{path, config, dependencies} | null> |
Load config from a file path |
loadEnv(mode, envDir, prefixes?) |
Record<string, string> |
Load .env files for a given mode |
Utility Functions
| Function |
Purpose |
searchForWorkspaceRoot(current, root?) |
Find monorepo workspace root directory |
normalizePath(id) |
Convert Windows backslashes to forward slashes |
createFilter(include, exclude) |
Create a picomatch-based file filter |
transformWithOxc(code, filename, options?, inMap?) |
Transform code with OXC (Vite 8+) |
transformWithEsbuild(code, filename, options?, inMap?) |
Transform code with esbuild (DEPRECATED) |
preprocessCSS(code, filename, config) |
Preprocess CSS (experimental) |
Version Constants
| Constant |
Description |
version |
Current Vite version string |
rolldownVersion |
Rolldown version used (Vite 8+) |
esbuildVersion |
Backward compatibility only |
rollupVersion |
Backward compatibility only |
Critical Warnings
NEVER use createServer() and build() in the same Node.js process without setting process.env.NODE_ENV or the mode config option consistently. Inconsistent modes cause unpredictable behavior.
NEVER call mergeConfig() with isRoot=true (the default) when merging nested config subsections like build or server. ALWAYS pass isRoot=false for nested option merging.
NEVER use transformWithEsbuild() in new projects targeting Vite 8+. ALWAYS use transformWithOxc() instead -- transformWithEsbuild is deprecated.
ALWAYS call server.close() in cleanup/shutdown handlers when using createServer() programmatically. Failing to close leaks file watchers, HTTP connections, and WebSocket handles.
ALWAYS call server.listen() after createServer() -- the server is NOT listening by default. createServer() only creates the server instance.
Decision Tree: Which API Function?
Need to run Vite programmatically?
├── Development server → createServer()
│ ├── Custom middleware → server.middlewares.use()
│ ├── SSR rendering → server.ssrLoadModule()
│ ├── Transform a file → server.transformRequest()
│ └── Transform HTML → server.transformIndexHtml()
├── Production build → build()
├── Preview built output → preview()
├── Read resolved config → resolveConfig()
├── Combine configs → mergeConfig()
├── Load config file → loadConfigFromFile()
├── Load env variables → loadEnv()
├── Transform code standalone → transformWithOxc() (v8+) / transformWithEsbuild() (v5-v7)
└── Find workspace root → searchForWorkspaceRoot()
ViteDevServer Interface
The ViteDevServer object returned by createServer() provides full programmatic control:
Properties
| Property |
Type |
Purpose |
config |
ResolvedConfig |
Fully resolved Vite configuration |
middlewares |
Connect.Server |
Connect-compatible middleware stack |
httpServer |
http.Server | null |
Underlying Node HTTP server (null in middleware mode) |
watcher |
FSWatcher |
Chokidar file system watcher |
ws |
WebSocketServer |
WebSocket server for HMR communication |
pluginContainer |
PluginContainer |
Runs plugin hooks programmatically |
moduleGraph |
ModuleGraph |
Tracks import relationships and HMR state |
resolvedUrls |
ResolvedServerUrls | null |
Resolved local and network URLs (available after listen()) |
Methods
| Method |
Signature |
Purpose |
transformRequest |
(url, options?) → Promise<TransformResult | null> |
Transform a module by URL |
transformIndexHtml |
(url, html, originalUrl?) → Promise<string> |
Apply HTML transforms |
ssrLoadModule |
(url, options?) → Promise<Record<string, any>> |
Load a module for SSR |
ssrFixStacktrace |
(e: Error) → void |
Fix SSR error stack traces |
reloadModule |
(module: ModuleNode) → Promise<void> |
Trigger HMR reload for a module |
listen |
(port?, isRestart?) → Promise<ViteDevServer> |
Start listening on a port |
restart |
(forceOptimize?) → Promise<void> |
Restart the dev server |
close |
() → Promise<void> |
Shut down the server and clean up |
bindCLIShortcuts |
(options?) → void |
Enable keyboard shortcuts (r, u, c, q) |
waitForRequestsIdle |
(ignoredId?) → Promise<void> |
Wait until all pending requests complete |
PreviewServer Interface
The PreviewServer object returned by preview():
| Member |
Type |
Purpose |
config |
ResolvedConfig |
Resolved configuration |
middlewares |
Connect.Server |
Connect middleware stack |
httpServer |
http.Server |
HTTP server (ALWAYS present, unlike dev server) |
resolvedUrls |
ResolvedServerUrls | null |
Resolved URLs |
printUrls() |
method |
Print server URLs to console |
bindCLIShortcuts(options?) |
method |
Enable keyboard shortcuts |
Key Types
InlineConfig
Extends UserConfig with:
configFile: Set to a path to specify config file, or false to disable auto-resolving. ALWAYS set configFile: false when you want zero config file influence.
ResolvedConfig
All UserConfig properties resolved (no undefined values), plus:
config.assetsInclude(id): Function to check if an ID is an assetconfig.logger: Internal logger object
resolveConfig Signature
async function resolveConfig(
inlineConfig: InlineConfig,
command: 'build' | 'serve', // 'serve' for dev AND preview
defaultMode?: string, // default: 'development'
defaultNodeEnv?: string, // default: 'development'
isPreview?: boolean, // default: false
): Promise<ResolvedConfig>
ALWAYS pass command: 'serve' for both dev and preview scenarios. The command parameter is 'build' ONLY for production builds.
Version Differences
| Feature |
Vite 5.x / 6.x |
Vite 8.x+ |
| Transform API |
transformWithEsbuild() |
transformWithOxc() |
| Bundler engine |
Rollup-based |
Rolldown-based |
| Version constants |
version only |
version, rolldownVersion, esbuildVersion (compat), rollupVersion (compat) |
| Filter utility |
@rollup/pluginutils |
createFilter() re-exported from Vite directly |
Reference Links
- references/api-reference.md -- Complete API signatures for all programmatic functions
- references/examples.md -- Working code examples for dev server, build, preview, and utilities
- references/anti-patterns.md -- Common programmatic API mistakes and how to avoid them
Official Sources
1---2name: vite-impl-javascript-api3description: Use when using Vite programmatically, building custom dev servers, running builds from scripts, or accessing Vite utilities. Prevents misuse of createServer(), build(), preview() signatures and incorrect ViteDevServer interface usage. Covers createServer(), build(), preview(), resolveConfig(), mergeConfig(), loadConfigFromFile(), loadEnv(), searchForWorkspaceRoot(), transformWithOxc(), normalizePath(), createFilter(), and version constants. Keywords: JavaScript API, createServer, build, preview, InlineConfig, ViteDevServer, moduleGraph, resolveConfig, mergeConfig, loadEnv, programmatic Vite, custom dev server, run Vite from script.4license: MIT5---67# vite-impl-javascript-api89## Quick Reference1011### Core API Functions1213| Function | Return Type | Purpose |14|----------|------------|---------|15| `createServer(inlineConfig?)` | `Promise<ViteDevServer>` | Start a programmatic dev server |16| `build(inlineConfig?)` | `Promise<RollupOutput \| RollupOutput[]>` | Run a production build |17| `preview(inlineConfig?)` | `Promise<PreviewServer>` | Start a preview server for built output |18| `resolveConfig(inlineConfig, command, ...)` | `Promise<ResolvedConfig>` | Resolve and merge all config sources |19| `mergeConfig(defaults, overrides, isRoot?)` | `Record<string, any>` | Deep-merge two Vite configs |20| `loadConfigFromFile(configEnv, ...)` | `Promise<{path, config, dependencies} \| null>` | Load config from a file path |21| `loadEnv(mode, envDir, prefixes?)` | `Record<string, string>` | Load `.env` files for a given mode |2223### Utility Functions2425| Function | Purpose |26|----------|---------|27| `searchForWorkspaceRoot(current, root?)` | Find monorepo workspace root directory |28| `normalizePath(id)` | Convert Windows backslashes to forward slashes |29| `createFilter(include, exclude)` | Create a picomatch-based file filter |30| `transformWithOxc(code, filename, options?, inMap?)` | Transform code with OXC (Vite 8+) |31| `transformWithEsbuild(code, filename, options?, inMap?)` | Transform code with esbuild (DEPRECATED) |32| `preprocessCSS(code, filename, config)` | Preprocess CSS (experimental) |3334### Version Constants3536| Constant | Description |37|----------|-------------|38| `version` | Current Vite version string |39| `rolldownVersion` | Rolldown version used (Vite 8+) |40| `esbuildVersion` | Backward compatibility only |41| `rollupVersion` | Backward compatibility only |4243### Critical Warnings4445**NEVER** use `createServer()` and `build()` in the same Node.js process without setting `process.env.NODE_ENV` or the `mode` config option consistently. Inconsistent modes cause unpredictable behavior.4647**NEVER** call `mergeConfig()` with `isRoot=true` (the default) when merging nested config subsections like `build` or `server`. ALWAYS pass `isRoot=false` for nested option merging.4849**NEVER** use `transformWithEsbuild()` in new projects targeting Vite 8+. ALWAYS use `transformWithOxc()` instead -- `transformWithEsbuild` is deprecated.5051**ALWAYS** call `server.close()` in cleanup/shutdown handlers when using `createServer()` programmatically. Failing to close leaks file watchers, HTTP connections, and WebSocket handles.5253**ALWAYS** call `server.listen()` after `createServer()` -- the server is NOT listening by default. `createServer()` only creates the server instance.5455---5657## Decision Tree: Which API Function?5859```60Need to run Vite programmatically?61├── Development server → createServer()62│ ├── Custom middleware → server.middlewares.use()63│ ├── SSR rendering → server.ssrLoadModule()64│ ├── Transform a file → server.transformRequest()65│ └── Transform HTML → server.transformIndexHtml()66├── Production build → build()67├── Preview built output → preview()68├── Read resolved config → resolveConfig()69├── Combine configs → mergeConfig()70├── Load config file → loadConfigFromFile()71├── Load env variables → loadEnv()72├── Transform code standalone → transformWithOxc() (v8+) / transformWithEsbuild() (v5-v7)73└── Find workspace root → searchForWorkspaceRoot()74```7576---7778## ViteDevServer Interface7980The `ViteDevServer` object returned by `createServer()` provides full programmatic control:8182### Properties8384| Property | Type | Purpose |85|----------|------|---------|86| `config` | `ResolvedConfig` | Fully resolved Vite configuration |87| `middlewares` | `Connect.Server` | Connect-compatible middleware stack |88| `httpServer` | `http.Server \| null` | Underlying Node HTTP server (null in middleware mode) |89| `watcher` | `FSWatcher` | Chokidar file system watcher |90| `ws` | `WebSocketServer` | WebSocket server for HMR communication |91| `pluginContainer` | `PluginContainer` | Runs plugin hooks programmatically |92| `moduleGraph` | `ModuleGraph` | Tracks import relationships and HMR state |93| `resolvedUrls` | `ResolvedServerUrls \| null` | Resolved local and network URLs (available after `listen()`) |9495### Methods9697| Method | Signature | Purpose |98|--------|-----------|---------|99| `transformRequest` | `(url, options?) → Promise<TransformResult \| null>` | Transform a module by URL |100| `transformIndexHtml` | `(url, html, originalUrl?) → Promise<string>` | Apply HTML transforms |101| `ssrLoadModule` | `(url, options?) → Promise<Record<string, any>>` | Load a module for SSR |102| `ssrFixStacktrace` | `(e: Error) → void` | Fix SSR error stack traces |103| `reloadModule` | `(module: ModuleNode) → Promise<void>` | Trigger HMR reload for a module |104| `listen` | `(port?, isRestart?) → Promise<ViteDevServer>` | Start listening on a port |105| `restart` | `(forceOptimize?) → Promise<void>` | Restart the dev server |106| `close` | `() → Promise<void>` | Shut down the server and clean up |107| `bindCLIShortcuts` | `(options?) → void` | Enable keyboard shortcuts (r, u, c, q) |108| `waitForRequestsIdle` | `(ignoredId?) → Promise<void>` | Wait until all pending requests complete |109110---111112## PreviewServer Interface113114The `PreviewServer` object returned by `preview()`:115116| Member | Type | Purpose |117|--------|------|---------|118| `config` | `ResolvedConfig` | Resolved configuration |119| `middlewares` | `Connect.Server` | Connect middleware stack |120| `httpServer` | `http.Server` | HTTP server (ALWAYS present, unlike dev server) |121| `resolvedUrls` | `ResolvedServerUrls \| null` | Resolved URLs |122| `printUrls()` | method | Print server URLs to console |123| `bindCLIShortcuts(options?)` | method | Enable keyboard shortcuts |124125---126127## Key Types128129### InlineConfig130131Extends `UserConfig` with:132- `configFile`: Set to a path to specify config file, or `false` to disable auto-resolving. ALWAYS set `configFile: false` when you want zero config file influence.133134### ResolvedConfig135136All `UserConfig` properties resolved (no undefined values), plus:137- `config.assetsInclude(id)`: Function to check if an ID is an asset138- `config.logger`: Internal logger object139140### resolveConfig Signature141142```typescript143async function resolveConfig(144 inlineConfig: InlineConfig,145 command: 'build' | 'serve', // 'serve' for dev AND preview146 defaultMode?: string, // default: 'development'147 defaultNodeEnv?: string, // default: 'development'148 isPreview?: boolean, // default: false149): Promise<ResolvedConfig>150```151152**ALWAYS** pass `command: 'serve'` for both dev and preview scenarios. The `command` parameter is `'build'` ONLY for production builds.153154---155156## Version Differences157158| Feature | Vite 5.x / 6.x | Vite 8.x+ |159|---------|----------------|-----------|160| Transform API | `transformWithEsbuild()` | `transformWithOxc()` |161| Bundler engine | Rollup-based | Rolldown-based |162| Version constants | `version` only | `version`, `rolldownVersion`, `esbuildVersion` (compat), `rollupVersion` (compat) |163| Filter utility | `@rollup/pluginutils` | `createFilter()` re-exported from Vite directly |164165---166167## Reference Links168169- [references/api-reference.md](references/api-reference.md) -- Complete API signatures for all programmatic functions170- [references/examples.md](references/examples.md) -- Working code examples for dev server, build, preview, and utilities171- [references/anti-patterns.md](references/anti-patterns.md) -- Common programmatic API mistakes and how to avoid them172173### Official Sources174175- https://vite.dev/guide/api-javascript176- https://vite.dev/guide/api-environment177- https://vite.dev/guide/ssr
Impertio-Studio