Skip to main content

build()

Build your VitePress site programmatically. The build() function creates a production-ready static site.

Usage

import { build } from 'vitepress'

await build()

Function Signature

export async function build(
  root?: string,
  buildOptions?: BuildOptions & {
    base?: string
    mpa?: string
    onAfterConfigResolve?: (siteConfig: SiteConfig) => Awaitable<void>
  }
): Promise<void>

Parameters

root
string
The root directory of your VitePress project. Defaults to process.cwd().This should be the directory containing the .vitepress folder.
buildOptions
BuildOptions
Configuration options for the build process.
buildOptions.base
string
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/).
buildOptions.mpa
string
Enable MPA (Multi-Page Application) mode. When enabled, VitePress will generate a zero-JS static site.This is experimental and disables client-side routing.
buildOptions.outDir
string
Output directory for build files. Overrides the outDir specified in config.Defaults to .vitepress/dist.
buildOptions.onAfterConfigResolve
(siteConfig: SiteConfig) => Awaitable<void>
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

import { build } from 'vitepress'

await build()

Build with Custom Root

import { build } from 'vitepress'
import path from 'path'

const root = path.resolve(__dirname, '../docs')
await build(root)

Build with Custom Options

import { build } from 'vitepress'

await build(process.cwd(), {
  base: '/my-docs/',
  outDir: './dist/site'
})

Build with Config Hook

import { build } from 'vitepress'

await build(process.cwd(), {
  async onAfterConfigResolve(config) {
    console.log('Building', config.site.title)
    console.log('Pages:', config.pages.length)
    
    // Modify config if needed
    config.site.description = 'Custom description'
  }
})

Build MPA Site

import { build } from 'vitepress'

// Build a zero-JS static site
await build(process.cwd(), {
  mpa: true
})

Build Process

The build function performs the following steps:
  1. Config Resolution: Resolves the site configuration from .vitepress/config.js
  2. Bundling: Creates optimized client and server bundles using Vite
  3. Rendering: Pre-renders all pages to static HTML
  4. Asset Generation: Generates CSS, fonts, and other static assets
  5. Sitemap: Generates sitemap.xml if configured
  6. 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 files
  • assets/ - JavaScript, CSS, fonts, and images
  • hashmap.json - Page hash map for cache invalidation
  • vp-icons.css - Social media icons
  • sitemap.xml - Sitemap (if configured)

Environment Variables

NODE_ENV
string
Automatically set to 'production' during build.
BUNDLE_ONLY
string
When set, only bundles the app without rendering pages. Useful for debugging build issues.
DEBUG
string
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:
// .vitepress/config.js
export default {
  async buildEnd(siteConfig) {
    // Generate additional files
    // Upload to CDN
    // etc.
  }
}

postRender

Called after SSR rendering:
// .vitepress/config.js
export default {
  async postRender(context) {
    // Process rendered content
    console.log('Rendered pages:', context.renderedPages)
  }
}

transformHead

Transform the <head> before writing HTML:
// .vitepress/config.js
export default {
  async transformHead(context) {
    return [
      ['meta', { name: 'keywords', content: context.pageData.frontmatter.keywords }]
    ]
  }
}

Error Handling

import { build } from 'vitepress'

try {
  await build()
  console.log('Build completed successfully')
} catch (error) {
  console.error('Build failed:', error)
  process.exit(1)
}

Build docs developers (and LLMs) love