Brain

Appearance

Deployment to Cloudflare Pages ​

This guide explains how to deploy your VitePress site to Cloudflare Pages.

Prerequisites ​

Before deploying to Cloudflare Pages, ensure you have:

  1. A wrangler.jsonc file in your project root
  2. A Cloudflare account
  3. Your project connected to a Git repository (GitHub or GitLab)

Wrangler Configuration ​

Cloudflare Pages uses Wrangler for deployment, so you need a wrangler.jsonc file in your project root. This file tells Wrangler where to find your built assets.

Here's an example configuration:

jsonc
{
    "name": "your-project-name",
    "compatibility_date": "2025-12-06",
    "assets": {
        "directory": "./.vitepress/dist"
    }
}

Important points:

  • The name field should match your project name
  • The assets.directory must point to .vitepress/dist, which is where VitePress outputs the built site
  • The compatibility_date specifies the Workers runtime version

Build Settings on Cloudflare Dashboard ​

After connecting your Git repository to Cloudflare Pages, you need to configure the build settings in the Cloudflare Dashboard under Workers & Pages.

Required Build Settings ​

  1. Build command: bun run docs:build

    • This runs the VitePress build process using Bun

  2. Build output directory: .vitepress/dist

    • This is where VitePress outputs the static files

  3. Root directory (if needed): Leave blank if your project is at the repository root, or specify the path if it's in a subdirectory

Environment Variables ​

You typically don't need environment variables for a basic VitePress deployment, but you can add them if your build process requires them.

CI/CD Build Checks ​

A GitHub Actions workflow is configured to automatically check that the build passes on every pull request. This ensures that:

  • Build errors are caught before merging
  • The documentation site can be built successfully
  • Contributors can see build status directly on their PRs

The workflow (.github/workflows/build-check.yml) runs:

  • On all pull requests
  • On pushes to main or master branches
  • Uses Bun to install dependencies and build the site

You'll see the build check status directly on your pull requests, and the PR cannot be merged if the build fails (if branch protection rules are configured).

Deployment Process ​

  1. Connect your Git repository: Follow the Cloudflare Pages Git integration guide to connect your GitHub or GitLab repository

  2. Configure build settings: Set the build command and output directory as described above

  3. Deploy: Click "Save and Deploy" - Cloudflare will automatically build and deploy your site

  4. Automatic deployments: Every push to your production branch (typically main or master) will trigger a new deployment. Other branches will create preview deployments.

VitePress-Specific Considerations ​

  • Static site generation: VitePress generates a static site, which is perfect for Cloudflare Pages
  • Build output: Always ensure your wrangler.jsonc points to .vitepress/dist
  • Base path: If you're deploying to a subdirectory, configure the base option in your VitePress config
  • Node.js version: Cloudflare Pages uses Node.js by default, but since you're using Bun, make sure your build command uses bun explicitly

Troubleshooting ​

  • Build fails: Check that your build command uses bun instead of npm or node
  • 404 errors: Verify that wrangler.jsonc points to the correct output directory (.vitepress/dist)
  • Assets not loading: Ensure the build output directory matches what's specified in wrangler.jsonc

Additional Resources ​