0
# Vite
1

2
Vite is a next-generation frontend build tool that significantly improves the frontend development experience. It consists of two major parts: a dev server that serves source files over native ES modules with rich built-in features and lightning-fast Hot Module Replacement (HMR), and a build command that bundles code with Rollup, pre-configured to output highly optimized static assets for production.
3

4
## Package Information
5

6
- **Package Name**: vite
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vite`
10

11
## Core Imports
12

13
```typescript
14
import { defineConfig, createServer, build } from "vite";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { defineConfig, createServer, build } = require("vite");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { defineConfig, createServer } from "vite";
27

28
// Define configuration
29
const config = defineConfig({
30
  root: "./src",
31
  server: {
32
    port: 3000,
33
    host: true
34
  },
35
  build: {
36
    outDir: "../dist"
37
  }
38
});
39

40
// Create development server
41
const server = await createServer(config);
42
await server.listen();
43
console.log(`Dev server running at ${server.resolvedUrls?.local[0]}`);
44
```
45

46
## Architecture
47

48
Vite is built around several key components:
49

50
- **Configuration System**: Flexible configuration with `defineConfig()` supporting multiple environments and modes
51
- **Development Server**: Fast dev server with native ES modules and instant HMR 
52
- **Build System**: Production builds powered by Rollup with optimizations
53
- **Plugin System**: Extensible architecture compatible with Rollup plugins
54
- **Environment Management**: Support for different environments (client, server, etc.)
55
- **Module Processing**: Advanced module resolution, CSS processing, and asset handling
56

57
## Capabilities
58

59
### Configuration
60

61
Core configuration system for defining build options, server settings, and plugin configurations. Supports environment-specific settings and TypeScript integration.
62

63
```typescript { .api }
64
function defineConfig(config: UserConfig): UserConfig;
65
function defineConfig(configFn: UserConfigFn): UserConfigFn;
66
function defineConfig(configObj: UserConfigFnObject): UserConfigFnObject;
67

68
interface UserConfig {
69
  root?: string;
70
  base?: string;
71
  mode?: string;
72
  define?: Record<string, any>;
73
  plugins?: PluginOption[];
74
  server?: ServerOptions;
75
  build?: BuildOptions;
76
  preview?: PreviewOptions;
77
  ssr?: SSROptions;
78
  optimizeDeps?: DepOptimizationOptions;
79
  environments?: Record<string, EnvironmentOptions>;
80
}
81
```
82

83
[Configuration](./configuration.md)
84

85
### Development Server
86

87
Development server with native ES modules, instant server start, and lightning-fast HMR. Supports middleware, proxy configuration, and file serving options.
88

89
```typescript { .api }
90
function createServer(config?: InlineConfig): Promise<ViteDevServer>;
91

92
interface ViteDevServer {
93
  listen(port?: number, isRestart?: boolean): Promise<ViteDevServer>;
94
  close(): Promise<void>;
95
  restart(forceOptimize?: boolean): Promise<void>;
96
  ws: WebSocketServer;
97
  middlewares: Connect.Server;
98
  httpServer: HttpServer | null;
99
  resolvedUrls: ResolvedServerUrls | null;
100
}
101
```
102

103
[Development Server](./dev-server.md)
104

105
### Build System
106

107
Production build system powered by Rollup with advanced optimizations, code splitting, and asset processing. Supports library builds and custom output formats.
108

109
```typescript { .api }
110
function build(config?: InlineConfig): Promise<RollupOutput | RollupOutput[] | RollupWatcher>;
111
function createBuilder(config?: InlineConfig): Promise<ViteBuilder>;
112

113
interface ViteBuilder {
114
  build(config?: BuilderOptions): Promise<RollupOutput | RollupOutput[]>;
115
  close(): Promise<void>;
116
}
117
```
118

119
[Build System](./build-system.md)
120

121
### Preview Server
122

123
Preview server for testing production builds locally with the same behavior as the production environment.
124

125
```typescript { .api }
126
function preview(config?: InlineConfig): Promise<PreviewServer>;
127

128
interface PreviewServer {
129
  listen(port?: number): Promise<PreviewServer>;
130
  close(): Promise<void>;
131
  printUrls(): void;
132
  resolvedUrls: ResolvedServerUrls | null;
133
}
134
```
135

136
### Plugin System
137

138
Extensible plugin architecture compatible with Rollup plugins. Supports hooks for all phases of development and build processes.
139

140
```typescript { .api }
141
interface Plugin extends RollupPlugin {
142
  name: string;
143
  enforce?: 'pre' | 'post';
144
  apply?: 'build' | 'serve' | ((config: UserConfig, env: ConfigEnv) => boolean);
145
  config?: (config: UserConfig, env: ConfigEnv) => void | UserConfig | Promise<void | UserConfig>;
146
  configResolved?: (config: ResolvedConfig) => void | Promise<void>;
147
  configureServer?: (server: ViteDevServer) => void | Promise<void>;
148
  buildStart?: (opts: InputOptions) => void | Promise<void>;
149
  buildEnd?: (err?: Error) => void | Promise<void>;
150
}
151

152
type PluginOption = Plugin | false | null | undefined | PluginOption[];
153
```
154

155
[Plugin System](./plugin-system.md)
156

157
### Module Resolution
158

159
Advanced module resolution with support for aliases, conditions, and custom resolvers. Handles ES modules, CommonJS, and various asset types.
160

161
```typescript { .api }
162
function createIdResolver(config: ResolvedConfig): Promise<IdResolver>;
163

164
interface ResolveOptions {
165
  alias?: AliasOptions;
166
  conditions?: string[];
167
  mainFields?: string[];
168
  extensions?: string[];
169
  preserveSymlinks?: boolean;
170
}
171
```
172

173
[Module Resolution](./module-resolution.md)
174

175
### CSS Processing
176

177
Comprehensive CSS processing with support for preprocessors, CSS modules, PostCSS, and advanced optimizations.
178

179
```typescript { .api }
180
function preprocessCSS(
181
  code: string,
182
  filename: string,
183
  config: ResolvedConfig
184
): Promise<PreprocessCSSResult>;
185

186
interface CSSOptions {
187
  modules?: CSSModulesOptions;
188
  preprocessorOptions?: {
189
    sass?: SassPreprocessorOptions;
190
    scss?: SassPreprocessorOptions;
191
    less?: LessPreprocessorOptions;
192
    stylus?: StylusPreprocessorOptions;
193
  };
194
  postcss?: PostCSSOptions;
195
  devSourcemap?: boolean;
196
}
197
```
198

199
[CSS Processing](./css-processing.md)
200

201
### Server-Side Rendering
202

203
Server-side rendering capabilities with module runner, environment management, and SSR-specific optimizations.
204

205
```typescript { .api }
206
function createServerModuleRunner(
207
  server: ViteDevServer,
208
  options?: ServerModuleRunnerOptions
209
): Promise<ModuleRunner>;
210

211
interface SSROptions {
212
  external?: string[];
213
  noExternal?: string[] | true;
214
  target?: SSRTarget;
215
  resolve?: {
216
    conditions?: string[];
217
    externalConditions?: string[];
218
  };
219
  optimizeDeps?: SsrDepOptimizationConfig;
220
}
221
```
222

223
[Server-Side Rendering](./ssr.md)
224

225
### Hot Module Replacement
226

227
Hot Module Replacement system with WebSocket communication, client-server coordination, and plugin integration.
228

229
```typescript { .api }
230
function createServerHotChannel(): ServerHotChannel;
231

232
interface HmrOptions {
233
  port?: number;
234
  host?: string;
235
  clientPort?: number;
236
  overlay?: boolean;
237
}
238

239
interface HotPayload {
240
  type: 'connected' | 'update' | 'full-reload' | 'prune' | 'error' | 'custom';
241
}
242
```
243

244
[Hot Module Replacement](./hmr.md)
245

246
### Utility Functions
247

248
Essential utility functions for configuration, logging, and development workflows.
249

250
```typescript { .api }
251
function mergeConfig<T extends Record<string, any>>(
252
  defaults: T,
253
  overrides: T,
254
  isRoot?: boolean
255
): T;
256

257
function createLogger(level?: LogLevel, options?: LoggerOptions): Logger;
258

259
function loadEnv(
260
  mode: string,
261
  envDir: string,
262
  prefixes?: string | string[]
263
): Record<string, string>;
264

265
function normalizePath(id: string): string;
266

267
function optimizeDeps(
268
  config: ResolvedConfig,
269
  force?: boolean,
270
  asCommand?: boolean
271
): Promise<DepOptimizationMetadata>;
272

273
function transformWithEsbuild(
274
  code: string,
275
  filename: string,
276
  options?: TransformOptions,
277
  inMap?: object
278
): Promise<ESBuildTransformResult>;
279
```
280

281
[Utilities](./utilities.md)
282

283
## Core Types
284

285
```typescript { .api }
286
interface ConfigEnv {
287
  command: 'build' | 'serve';
288
  mode: string;
289
  isSsrBuild?: boolean;
290
  isPreview?: boolean;
291
}
292

293
interface ResolvedConfig {
294
  root: string;
295
  base: string;
296
  mode: string;
297
  command: 'build' | 'serve';
298
  isProduction: boolean;
299
  plugins: readonly Plugin[];
300
  server: ResolvedServerOptions;
301
  build: ResolvedBuildOptions;
302
  env: Record<string, any>;
303
  logger: Logger;
304
}
305

306
type UserConfigFn = (env: ConfigEnv) => UserConfig | Promise<UserConfig>;
307
type UserConfigExport = UserConfig | Promise<UserConfig> | UserConfigFn;
308

309
interface Logger {
310
  info(msg: string, options?: LogOptions): void;
311
  warn(msg: string, options?: LogOptions): void;
312
  error(msg: string, options?: LogOptions): void;
313
  clearScreen(type: LogType): void;
314
  hasErrorLogged(error: Error): boolean;
315
  hasWarned: boolean;
316
}
317

318
interface LoggerOptions {
319
  prefix?: string;
320
  allowClearScreen?: boolean;
321
  customLogger?: Logger;
322
}
323

324
interface DepOptimizationMetadata {
325
  hash: string;
326
  processing: boolean;
327
  discovered: Record<string, string>;
328
  chunks: Record<string, string>;
329
}
330

331
interface ESBuildTransformResult {
332
  code: string;
333
  map: any;
334
  warnings: any[];
335
}
336

337
type LogLevel = 'error' | 'warn' | 'info' | 'silent';
338
type LogType = 'error' | 'warn';
339
interface LogOptions {
340
  clear?: boolean;
341
  timestamp?: boolean;
342
}
343

344
interface TransformOptions {
345
  loader?: 'js' | 'jsx' | 'ts' | 'tsx';
346
  target?: string;
347
  format?: 'esm' | 'cjs' | 'iife';
348
  platform?: 'browser' | 'node' | 'neutral';
349
  define?: Record<string, string>;
350
  jsx?: 'transform' | 'preserve';
351
  jsxFactory?: string;
352
  jsxFragment?: string;
353
}
354
```