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

string

The root directory of your VitePress project. Defaults to process.cwd().This should be the directory containing the .vitepress folder.

BuildOptions

Configuration options for the build process.

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/).

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.

string

Output directory for build files. Overrides the outDir specified in config.Defaults to .vitepress/dist.

(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:

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 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

string

Automatically set to 'production' during build.

string

When set, only bundles the app without rendering pages. Useful for debugging build issues.

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)
}

serve() - Preview the built site
resolveConfig() - Resolve site configuration
Configuration Reference - Site configuration options

Configuration

Node API

Client API

build()

build()

Usage

Function Signature

Parameters

Examples

Basic Build

Build with Custom Root

Build with Custom Options

Build with Config Hook

Build MPA Site

Build Process

Build Output

Environment Variables

Build Hooks

buildEnd

postRender

transformHead

Error Handling

​build()

​Usage

​Function Signature

​Parameters

​Examples

​Basic Build

​Build with Custom Root

​Build with Custom Options

​Build with Config Hook

​Build MPA Site

​Build Process

​Build Output

​Environment Variables

​Build Hooks

​buildEnd

​postRender

​transformHead

​Error Handling

​Related

build()

Usage

Function Signature

Parameters

Examples

Basic Build

Build with Custom Root

Build with Custom Options

Build with Config Hook

Build MPA Site

Build Process

Build Output

Environment Variables

Build Hooks

buildEnd

postRender

transformHead

Error Handling

Related