Skip to main content

serve()

Serve a built VitePress site locally for preview. This is useful for testing the production build before deployment.

Usage

import { serve } from 'vitepress'

const server = await serve()

Function Signature

export async function serve(
  options?: ServeOptions
): Promise<Polka>

interface ServeOptions {
  base?: string
  root?: string
  port?: number
}

Parameters

options
ServeOptions
Configuration options for the preview server.
options.root
string
The root directory of your VitePress project. Defaults to process.cwd().This should be the directory containing the .vitepress folder.
options.base
string
Base public path to serve the site at. Overrides the base path from config.Example: /my-docs/
options.port
number
default:"4173"
Port number for the preview server.

Return Value

server
Polka
Returns a Polka server instance that can be used to stop the server or access server details.

Examples

Basic Preview Server

import { serve } from 'vitepress'

const server = await serve()
// Server is now running at http://localhost:4173/

Custom Port

import { serve } from 'vitepress'

const server = await serve({
  port: 8080
})
// Server is now running at http://localhost:8080/

Custom Base Path

import { serve } from 'vitepress'

const server = await serve({
  base: '/docs/',
  port: 4173
})
// Server is now running at http://localhost:4173/docs/

Custom Root Directory

import { serve } from 'vitepress'
import path from 'path'

const server = await serve({
  root: path.resolve(__dirname, '../my-docs'),
  port: 3000
})

Build and Serve

import { build, serve } from 'vitepress'

// Build the site first
await build()

// Then serve it
const server = await serve({
  port: 4173
})

console.log('Preview server running')

Programmatic Server Control

import { serve } from 'vitepress'

const server = await serve({ port: 4173 })

// Do something...

// Stop the server when done
server.server.close()

Server Features

The preview server includes:

Compression

Automatic Brotli and gzip compression for all responses.

Caching

Smart caching strategy:
  • Asset files (/assets/): Cached for 1 year with immutable flag
  • HTML files: No cache, always revalidated

SPA Fallback

Serves 404.html for non-asset routes that don’t match files, supporting client-side routing.

Static File Serving

Serves all static files from the build output directory (.vitepress/dist by default).

CLI Alternative

You can also use the VitePress CLI to preview your site:
vitepress preview
With options:
vitepress preview --port 8080
vitepress preview --base /docs/

Prerequisites

Before running the preview server, you must build your site:
vitepress build
Or programmatically:
import { build } from 'vitepress'

await build()

Server Configuration

The preview server uses:

Error Handling

import { serve } from 'vitepress'

try {
  const server = await serve({ port: 4173 })
  console.log('Server started successfully')
} catch (error) {
  if (error.code === 'EADDRINUSE') {
    console.error('Port 4173 is already in use')
  } else {
    console.error('Failed to start server:', error)
  }
  process.exit(1)
}

Production Deployment

While serve() is useful for local preview, for production deployment you should:
  1. Build your site with build()
  2. Deploy the .vitepress/dist folder to a static hosting service
Popular options:
  • Vercel
  • Netlify
  • GitHub Pages
  • CloudFlare Pages
  • AWS S3 + CloudFront

Build docs developers (and LLMs) love