Get started →

    Deploy to Vercel

    Deploy your ciderpress documentation site to Vercel as a static site.

    Prerequisites

    • A Vercel account
    • Your ciderpress project pushed to a Git repository (GitHub, GitLab, or Bitbucket)
    • ciderpress building locally (npx ciderpress build succeeds)
    • A committed lockfile (pnpm-lock.yaml or package-lock.json) — --frozen-lockfile / npm ci fail without one

    Steps

    1. Add output directories to gitignore

    Add the ciderpress output root to .gitignore — its contents are regenerated by sync and build:

    .ciderpress/

    2. Add a vercel.json

    Create a vercel.json in your project root to configure the build. Commit and push this file before importing your project in Vercel.

    If your project has a pnpm-lock.yaml, skip to the pnpm snippet below.

    {
  "buildCommand": "npx ciderpress build",
  "outputDirectory": ".ciderpress/dist",
  "framework": null,
  "installCommand": "npm install"
}

    framework: null opts out of Vercel's auto-detection so your buildCommand is used as-is.

    If your project uses pnpm, enable corepack in your Vercel project settings or add a packageManager field to your package.json:

    {
  "packageManager": "pnpm@10.32.0"
}

    Then update vercel.json accordingly:

    {
  "buildCommand": "pnpm exec ciderpress build",
  "outputDirectory": ".ciderpress/dist",
  "framework": null,
  "installCommand": "pnpm install --frozen-lockfile"
}

    Again, framework: null keeps Vercel from overriding buildCommand with its own detected default.

    3. Import your project in Vercel

    Go to the Vercel dashboard and import your Git repository.

    4. Configure environment variables

    No environment variables are required for a standard ciderpress build. If your configuration fetches content from external APIs (e.g., remote OpenAPI specs), add the necessary API keys in the Vercel dashboard under Settings > Environment Variables.

    5. Deploy

    Push to your main branch. Vercel automatically builds and deploys on every push.

    Verification

    After deployment completes, open the Vercel-provided URL. You should see your documentation site with all pages, navigation, and search working. If something looks wrong, check the build logs in the Vercel dashboard under Deployments > (latest) > Build Logs.

    Troubleshooting

    Build fails with missing dependencies

    Symptom: Module not found errors during build.

    Fix: Ensure your install command matches your package manager. If using pnpm, set the install command to pnpm install --frozen-lockfile.

    Empty site after deploy

    Symptom: The deployed site shows a blank page or 404.

    Cause: The output directory is misconfigured.

    Fix: Verify the output directory is set to .ciderpress/dist (not dist or .ciderpress).

    Custom domain

    Add a custom domain from the Vercel dashboard under Settings > Domains. Vercel automatically provisions SSL certificates. For DNS records (CNAME for subdomains, A for apex), see Vercel's DNS docs.

    References