Cloudflare Pages — handover docs site

Purpose

Deploy the developer handover documentation (docs/) separately from the Frappe app. This page does not describe hosting ERPNext.

Production URL: https://leekimdocs.pages.dev · Cloudflare Pages project leekimdocs.

Prerequisites

• Node.js 22.12+ (Astro 6 requires >=22.12.0; see docs/package.json engines and docs/.nvmrc).
• Cloudflare account; optional Wrangler CLI (npm install already includes wrangler under docs/ devDependencies).

PUBLIC_SITE_URL (what to set)

This environment variable feeds Astro’s site option at build time. It is used for sitemaps, canonical URLs, and any metadata that needs an absolute public URL for this handover site.

Question	Answer
What value?	The URL users type to open this docs site: production is https://leekimdocs.pages.dev. If you attach a custom domain, use that instead (e.g. https://docs.example.com).
Format	Include https://. Do not add a trailing /.
Local dev	Optional; defaults in astro.config.mjs apply if unset. For a local-only build test you can use http://localhost:4321, but CI and Cloudflare builds should use the real production URL.
Where to set	Root or docs/ .env (see .env.example), GitHub Actions repository Variable PUBLIC_SITE_URL, and/or Cloudflare Pages → project → Environment variables for dashboard builds.

If PUBLIC_SITE_URL is missing in CI, the build still uses the default in docs/astro.config.mjs (https://leekimdocs.pages.dev unless you change it).

One-time setup (Cloudflare dashboard)

1. Workers & Pages → Create → Pages → Connect to Git.

2. Select this repository.

3. Configure builds:

   Field	Value
   Root directory	docs
   Build command	npm run build
   Build output directory	dist/client (not dist — static files live here with @astrojs/cloudflare)

4. Environment variables (production / preview): set PUBLIC_SITE_URL to https://leekimdocs.pages.dev (or your custom domain; no trailing slash). Used by Astro for sitemaps and canonical URLs.

5. Production branch: In the dashboard this lives under Settings → General (not always under a separate “Builds & deployments” heading — Cloudflare’s UI changes). Set Production branch to the branch that should power https://leekimdocs.pages.dev. If docs only build from staging but production is main, Git builds show as Preview only and the project URL stays empty until a Production deployment exists. Either set production branch to staging, or merge docs to main so that branch gets a production build.

6. Build command / output / root directory: If you use Connect to Git, these are part of the linked repository’s Pages build configuration — in some accounts they appear under Settings → Pages configuration (or the Deployments tab → manage build settings). Use root docs, command npm run build, output dist/client.

7. Save and deploy.

Root URL empty while Preview works

https://<project>.pages.dev serves the latest Production deployment. Preview URLs look like https://<hash>.<project>.pages.dev (per deployment). If the Deployments list shows only Preview / staging, fix the Production branch (step 5) or open the preview URL from the dashboard until production is configured.

404 at the site root

If the dashboard Build output directory is set to dist instead of dist/client, Pages serves an empty root (files appear under /client/...) and you get 404 on *.pages.dev. Use dist/client so index.html is at the deployment root.

What you should see after a correct upload: at the root of the deployment file list, index.html, 404.html, _astro/, section folders like api/, architecture/ — not a single top-level folder named client that contains those files. If server/ (with entry.mjs, wrangler.json) appears alongside client/, you are still publishing dist/; switch the output to dist/client only.

GitHub Actions

Workflow: .github/workflows/deploy-docs.yml

• Runs on changes under docs/** or when the workflow file changes; workflow_dispatch allows manual runs.
• Sets PUBLIC_SITE_URL from repository Variables (vars.PUBLIC_SITE_URL); default in astro.config.mjs is https://leekimdocs.pages.dev. Match Cloudflare Pages env if you use dashboard builds.
• Uploads docs/dist/client as a workflow artifact for inspection.
• Publish: cloudflare/pages-action@v1 uploads docs/dist/client (static site root) to the leekimdocs Pages project. Required repository Secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID (see Cloudflare direct upload). The job uses permissions: deployments: write and gitHubToken: ${{ github.token }} for GitHub deployment status.

Local commands

From repository root:

npm run docs:install   # once
npm run docs:build     # produces docs/dist
npm run docs:preview   # Astro preview
npm run docs:preview:cf  # after build: Wrangler Pages dev (static under dist/client)

From docs/: see docs/README.md for wrangler.toml and adapter notes.

Adapter output

@astrojs/cloudflare emits dist/client (static HTML, index.html, assets) and dist/server (Worker). Pages direct upload and the dashboard “output directory” must point at dist/client, not dist, so the site root serves index.html.

Related

• Deployment & operations — Frappe / Bench app hosting
• Repository docs/README.md — developer-focused build reference