serve()
Serve a built VitePress site locally for preview. This is useful for testing the production build before deployment.Usage
Function Signature
Parameters
Configuration options for the preview server.
The root directory of your VitePress project. Defaults to
process.cwd().This should be the directory containing the .vitepress folder.Base public path to serve the site at. Overrides the base path from config.Example:
/my-docs/Port number for the preview server.
Return Value
Returns a Polka server instance that can be used to stop the server or access server details.
Examples
Basic Preview Server
Custom Port
Custom Base Path
Custom Root Directory
Build and Serve
Programmatic Server Control
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 withimmutableflag - HTML files: No cache, always revalidated
SPA Fallback
Serves404.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:Prerequisites
Before running the preview server, you must build your site:Server Configuration
The preview server uses:- Polka - Fast micro-framework
- sirv - Static file serving
- @polka/compression - Response compression
Error Handling
Production Deployment
Whileserve() is useful for local preview, for production deployment you should:
- Build your site with
build() - Deploy the
.vitepress/distfolder to a static hosting service
- 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