build()
Build your VitePress site programmatically. Thebuild() function creates a production-ready static site.
Usage
Function Signature
Parameters
The root directory of your VitePress project. Defaults to
process.cwd().This should be the directory containing the .vitepress folder.Configuration options for the build process.
Base public path when served in production. Overrides the base path defined in config.Must start and end with a slash (e.g.,
/my-site/).Enable MPA (Multi-Page Application) mode. When enabled, VitePress will generate a zero-JS static site.This is experimental and disables client-side routing.
Output directory for build files. Overrides the
outDir specified in config.Defaults to .vitepress/dist.Hook called after the site config is resolved but before the build starts.Use this to inspect or modify the resolved configuration.
Examples
Basic Build
Build with Custom Root
Build with Custom Options
Build with Config Hook
Build MPA Site
Build Process
The build function performs the following steps:- Config Resolution: Resolves the site configuration from
.vitepress/config.js - Bundling: Creates optimized client and server bundles using Vite
- Rendering: Pre-renders all pages to static HTML
- Asset Generation: Generates CSS, fonts, and other static assets
- Sitemap: Generates sitemap.xml if configured
- Cleanup: Removes temporary files
Build Output
The build outputs the following files to.vitepress/dist (or your configured outDir):
index.html- Homepage*.html- Individual page filesassets/- JavaScript, CSS, fonts, and imageshashmap.json- Page hash map for cache invalidationvp-icons.css- Social media iconssitemap.xml- Sitemap (if configured)
Environment Variables
Automatically set to
'production' during build.When set, only bundles the app without rendering pages. Useful for debugging build issues.
When set, preserves the
.vitepress/.temp directory after build for inspection.Build Hooks
VitePress provides several hooks during the build process:buildEnd
Called after the build completes:postRender
Called after SSR rendering:transformHead
Transform the<head> before writing HTML:
Error Handling
Related
- serve() - Preview the built site
- resolveConfig() - Resolve site configuration
- Configuration Reference - Site configuration options