serve()

Preview server API for built VitePress sites

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:

• Polka - Fast micro-framework
• sirv - Static file serving
• @polka/compression - Response compression

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

Related

• build() - Build the site for production
• createServer() - Create a development server
• Deployment Guide - Deploy your VitePress site