VitePress on Cloudflare Pages
This guide explains how to deploy a VitePress documentation site to Cloudflare Pages. It assumes you already have a working VitePress project pushed to a GitHub or GitLab repository. If you do not have one, follow this guide to set it up.
NOTE
Cloudflare Pages provides a generous free tier that includes unlimited bandwidth and automatic continuous deployments whenever you push changes to your repository. This means you can effectively host your documentation for free.
Connect Your Repository
First, log in to your Cloudflare dashboard and navigate to Workers & Pages in the left sidebar under the "Build -> Compute" section.
Click the Create application button. By default, you will be presented with the worker creation screen. Click Looking to deploy Pages? Get started at the bottom of the screen to switch to the Pages interface.
Click the Get started button next to the option to import an existing Git repository. Select your provider (GitHub or GitLab) and authorize Cloudflare to access your account and read your source code. Finally, choose the repository containing your VitePress project and click Begin setup to proceed.
Configure Build Settings
In the setup screen, provide a name for your project and select your production branch (usually main).
Configure the build settings as follows, adjusting the output directory if your project uses a different structure:
| Parameter | Value |
|---|---|
| Framework preset | None |
| Build command | npm run docs:build |
| Build output directory | docs/.vitepress/dist |
TIP
If you are using a different package manager, update the build command accordingly (for example, pnpm run docs:build or yarn docs:build).
(Optional) Set Environment Variables
Cloudflare Pages occasionally defaults to an older Node environment that cannot run modern Vite or VitePress applications. You must explicitly tell Cloudflare to use a newer version of Node.js.
Expand the Environment variables (advanced) section at the bottom of the setup page and add the following variable:
| Variable name | Value |
|---|---|
NODE_VERSION | 20 |
Deploy Your Site
Click Save and Deploy to trigger the initial build.
Cloudflare will clone your repository, install your dependencies, run the build command, and publish the compiled static files. Once finished, you will receive a unique pages.dev URL where you can view your live documentation.
(Optional) Add a Custom Domain
To use your own domain name instead of the default .pages.dev address, open your newly created Pages project and navigate to the Custom domains tab.
Click Set up a custom domain, enter your desired domain name, and follow the on-screen instructions to automatically configure the necessary DNS records.