0
# Build and Development API
1

2
VitePress provides APIs for building static sites for production, running development servers with hot reloading, and serving built sites for preview. All build and development functions support extensive customization options.
3

4
## Capabilities
5

6
### Build Functions
7

8
Production build functionality for generating optimized static sites.
9

10
#### build
11

12
Builds VitePress site for production with static site generation and optimization.
13

14
```typescript { .api }
15
/**
16
 * Builds VitePress site for production
17
 * @param root - Project root directory (defaults to current directory)
18
 * @param buildOptions - Build configuration options
19
 * @returns Promise that resolves when build is complete
20
 */
21
function build(
22
  root?: string,
23
  buildOptions?: BuildOptions & VitePressSpecificBuildOptions
24
): Promise<void>;
25

26
interface VitePressSpecificBuildOptions {
27
  /**
28
   * Override base URL for build
29
   */
30
  base?: string;
31
  
32
  /**
33
   * Enable Multi-Page Application mode (requires string value for internal routing)
34
   */
35
  mpa?: string;
36
  
37
  /**
38
   * Hook called after config resolution
39
   */
40
  onAfterConfigResolve?: (config: SiteConfig) => Awaitable<void>;
41
}
42

43
// Note: build() function accepts Vite's BuildOptions extended with VitePress-specific options above
44
```
45

46
**Usage Examples:**
47

48
```typescript
49
import { build } from "vitepress";
50

51
// Basic build
52
await build();
53

54
// Build with VitePress-specific options  
55
await build("./docs", {
56
  base: "/my-site/",
57
  onAfterConfigResolve: async (config) => {
58
    console.log("Config resolved for:", config.site.title);
59
  }
60
});
61

62
// Build with Vite options (passed through)
63
await build("./docs", {
64
  outDir: "./dist",
65
  minify: true,
66
  sourcemap: true
67
});
68

69
// MPA mode build
70
await build("./docs", {
71
  mpa: "spa-fallback"  // mpa requires string value
72
});
73
```
74

75
### Development Server Functions
76

77
Development server with hot module replacement and fast rebuilds.
78

79
#### createServer
80

81
Creates and configures a Vite development server for VitePress with HMR support.
82

83
```typescript { .api }
84
/**
85
 * Creates Vite development server for VitePress
86
 * @param root - Project root directory (defaults to current directory)
87
 * @param serverOptions - Vite server options with VitePress extensions
88
 * @param recreateServer - Function to recreate server on config changes
89
 * @returns Promise resolving to Vite dev server instance
90
 */
91
function createServer(
92
  root?: string,
93
  serverOptions?: ServerOptions,
94
  recreateServer?: () => Promise<ViteDevServer>
95
): Promise<ViteDevServer>;
96

97
interface ServerOptions extends ViteServerOptions {
98
  /**
99
   * Override base URL for development
100
   */
101
  base?: string;
102
  
103
  /**
104
   * Enable/disable HMR
105
   * @default true
106
   */
107
  hmr?: boolean | HMROptions;
108
  
109
  /**
110
   * Server host
111
   * @default 'localhost'
112
   */
113
  host?: string | boolean;
114
  
115
  /**
116
   * Server port
117
   * @default 5173
118
   */
119
  port?: number;
120
  
121
  /**
122
   * Enable HTTPS
123
   * @default false
124
   */
125
  https?: boolean | ServerHttpsOptions;
126
  
127
  /**
128
   * Open browser on server start
129
   * @default false
130
   */
131
  open?: boolean | string;
132
  
133
  /**
134
   * CORS configuration
135
   */
136
  cors?: boolean | CorsOptions;
137
  
138
  /**
139
   * Proxy configuration
140
   */
141
  proxy?: Record<string, string | ProxyOptions>;
142
  
143
  /**
144
   * Custom middleware
145
   */
146
  middlewares?: Connect.Server;
147
  
148
  /**
149
   * Force dependency optimization
150
   * @default false
151
   */
152
  force?: boolean;
153
  
154
  /**
155
   * Clear screen on restart
156
   * @default true
157
   */
158
  clearScreen?: boolean;
159
}
160

161
interface HMROptions {
162
  /**
163
   * HMR server port
164
   */
165
  port?: number;
166
  
167
  /**
168
   * HMR server host
169
   */
170
  host?: string;
171
  
172
  /**
173
   * HMR connection options
174
   */
175
  clientPort?: number;
176
  server?: Server;
177
}
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
import { createServer } from "vitepress";
184

185
// Basic development server
186
const server = await createServer();
187
await server.listen();
188
console.log("VitePress dev server running at http://localhost:5173");
189

190
// Custom server configuration
191
const server = await createServer("./docs", {
192
  port: 3000,
193
  host: "0.0.0.0",
194
  open: true,
195
  cors: true,
196
  proxy: {
197
    "/api": "http://localhost:8080"
198
  }
199
});
200

201
await server.listen(3000);
202

203
// HTTPS development server
204
const server = await createServer("./docs", {
205
  https: {
206
    key: readFileSync("path/to/server.key"),
207
    cert: readFileSync("path/to/server.crt")
208
  },
209
  port: 443
210
});
211

212
// Server with custom middleware
213
const server = await createServer("./docs", {
214
  middlewares: (app) => {
215
    app.use("/custom", (req, res, next) => {
216
      // Custom middleware logic
217
      next();
218
    });
219
  }
220
});
221
```
222

223
### Preview Server Functions
224

225
Serve built VitePress sites for testing and preview.
226

227
#### serve
228

229
Serves a built VitePress site using a lightweight static file server.
230

231
```typescript { .api }
232
/**
233
 * Serves built VitePress site
234
 * @param options - Server configuration options
235
 * @returns Promise resolving to server instance
236
 */
237
function serve(options?: ServeOptions): Promise<Server>;
238

239
interface ServeOptions {
240
  /**
241
   * Project root directory
242
   * @default process.cwd()
243
   */
244
  root?: string;
245
  
246
  /**
247
   * Override base URL
248
   */
249
  base?: string;
250
  
251
  /**
252
   * Server port
253
   * @default 4173
254
   */
255
  port?: number;
256
  
257
  /**
258
   * Server host
259
   * @default 'localhost'
260
   */
261
  host?: string | boolean;
262
  
263
  /**
264
   * Open browser on start
265
   * @default false
266
   */
267
  open?: boolean | string;
268
  
269
  /**
270
   * CORS configuration
271
   * @default false
272
   */
273
  cors?: boolean;
274
  
275
  /**
276
   * Strict port (fail if port is in use)
277
   * @default false
278
   */
279
  strictPort?: boolean;
280
  
281
  /**
282
   * Custom headers for responses
283
   */
284
  headers?: Record<string, string>;
285
  
286
  /**
287
   * Compression options
288
   */
289
  compression?: {
290
    /**
291
     * Enable gzip compression
292
     * @default true
293
     */
294
    gzip?: boolean;
295
    
296
    /**
297
     * Enable brotli compression
298
     * @default true
299
     */
300
    brotli?: boolean;
301
    
302
    /**
303
     * Compression level (1-9)
304
     * @default 6
305
     */
306
    level?: number;
307
  };
308
  
309
  /**
310
   * Cache control headers
311
   */
312
  cache?: {
313
    /**
314
     * Cache control for HTML files
315
     * @default 'no-cache'
316
     */
317
    html?: string;
318
    
319
    /**
320
     * Cache control for assets
321
     * @default 'max-age=31536000,immutable'
322
     */
323
    assets?: string;
324
  };
325
}
326
```
327

328
**Usage Examples:**
329

330
```typescript
331
import { serve } from "vitepress";
332

333
// Basic preview server
334
const server = await serve();
335
console.log("Preview server running at http://localhost:4173");
336

337
// Custom preview server
338
const server = await serve({
339
  root: "./docs",
340
  port: 8080,
341
  host: "0.0.0.0",
342
  open: true,
343
  cors: true,
344
  headers: {
345
    "X-Custom-Header": "VitePress"
346
  }
347
});
348

349
// Preview with custom caching
350
const server = await serve({
351
  port: 3000,
352
  cache: {
353
    html: "no-cache, no-store, must-revalidate",
354
    assets: "max-age=86400"
355
  },
356
  compression: {
357
    gzip: true,
358
    brotli: true,
359
    level: 9
360
  }
361
});
362

363
// Preview with base path
364
const server = await serve({
365
  base: "/my-docs/",
366
  port: 4000
367
});
368
```
369

370
### Server Management
371

372
Utilities for managing server lifecycle and configuration.
373

374
#### Server Instance Methods
375

376
Methods available on the server instances returned by `createServer` and `serve`.
377

378
```typescript { .api }
379
interface ViteDevServer {
380
  /**
381
   * Start the server
382
   */
383
  listen(port?: number, isRestart?: boolean): Promise<ViteDevServer>;
384
  
385
  /**
386
   * Close the server
387
   */
388
  close(): Promise<void>;
389
  
390
  /**
391
   * Restart the server
392
   */
393
  restart(forceOptimize?: boolean): Promise<void>;
394
  
395
  /**
396
   * Server configuration
397
   */
398
  config: ResolvedConfig;
399
  
400
  /**
401
   * HTTP server instance
402
   */
403
  httpServer: Server;
404
  
405
  /**
406
   * WebSocket server for HMR
407
   */
408
  ws: WebSocketServer;
409
  
410
  /**
411
   * Module graph
412
   */
413
  moduleGraph: ModuleGraph;
414
  
415
  /**
416
   * Transform request
417
   */
418
  transformRequest(
419
    url: string,
420
    options?: TransformOptions
421
  ): Promise<TransformResult | null>;
422
  
423
  /**
424
   * Warm up files
425
   */
426
  warmupRequest(url: string): Promise<void>;
427
  
428
  /**
429
   * SSR transform
430
   */
431
  ssrTransform(
432
    code: string,
433
    inMap: SourceMap | null,
434
    url: string
435
  ): Promise<TransformResult | null>;
436
  
437
  /**
438
   * Load SSR module
439
   */
440
  ssrLoadModule(
441
    url: string,
442
    opts?: { fixStacktrace?: boolean }
443
  ): Promise<Record<string, any>>;
444
}
445

446
interface Server {
447
  /**
448
   * Server address info
449
   */
450
  address(): AddressInfo | string | null;
451
  
452
  /**
453
   * Close the server
454
   */
455
  close(callback?: (err?: Error) => void): Server;
456
  
457
  /**
458
   * Listen on port
459
   */
460
  listen(port?: number, hostname?: string, callback?: () => void): Server;
461
  listen(port?: number, callback?: () => void): Server;
462
  listen(callback?: () => void): Server;
463
}
464
```
465

466
### Build Optimization
467

468
Advanced build optimization features and configuration.
469

470
#### Bundle Analysis
471

472
```typescript { .api }
473
interface BuildResult {
474
  /**
475
   * Build output files
476
   */
477
  output: OutputBundle;
478
  
479
  /**
480
   * Build warnings
481
   */
482
  warnings: RollupWarning[];
483
  
484
  /**
485
   * Build statistics
486
   */
487
  stats?: {
488
    /**
489
     * Total build time in milliseconds
490
     */
491
    buildTime: number;
492
    
493
    /**
494
     * Number of files processed
495
     */
496
    fileCount: number;
497
    
498
    /**
499
     * Total output size in bytes
500
     */
501
    outputSize: number;
502
    
503
    /**
504
     * Chunk information
505
     */
506
    chunks: ChunkInfo[];
507
  };
508
}
509

510
interface ChunkInfo {
511
  /**
512
   * Chunk name
513
   */
514
  name: string;
515
  
516
  /**
517
   * Chunk size in bytes
518
   */
519
  size: number;
520
  
521
  /**
522
   * Chunk type
523
   */
524
  type: "entry" | "chunk" | "asset";
525
  
526
  /**
527
   * Modules in this chunk
528
   */
529
  modules: string[];
530
}
531
```
532

533
#### Performance Monitoring
534

535
```typescript { .api }
536
interface PerformanceMetrics {
537
  /**
538
   * Page load time metrics
539
   */
540
  loadTime: {
541
    /**
542
     * Time to first byte
543
     */
544
    ttfb: number;
545
    
546
    /**
547
     * First contentful paint
548
     */
549
    fcp: number;
550
    
551
    /**
552
     * Largest contentful paint
553
     */
554
    lcp: number;
555
  };
556
  
557
  /**
558
   * Bundle size metrics
559
   */
560
  bundleSize: {
561
    /**
562
     * JavaScript bundle size
563
     */
564
    js: number;
565
    
566
    /**
567
     * CSS bundle size
568
     */
569
    css: number;
570
    
571
    /**
572
     * Total asset size
573
     */
574
    assets: number;
575
  };
576
  
577
  /**
578
   * Build performance
579
   */
580
  buildPerformance: {
581
    /**
582
     * Build duration
583
     */
584
    duration: number;
585
    
586
    /**
587
     * Memory usage
588
     */
589
    memory: number;
590
    
591
    /**
592
     * CPU usage
593
     */
594
    cpu: number;
595
  };
596
}
597
```