Cloudflare Pages deployment

Production configuration

The site uses a static Astro build and needs no server adapter, database, runtime secret, or Cloudflare Function. The Pages project is mochi-sdk. Its production address is mochi-sdk.pages.dev.

Deploy from your computer

Install dependencies and authenticate with an account that can write Pages projects:

npm ci
npx wrangler login
npx wrangler whoami
npm run deploy

npm run deploy builds the workspace and uploads site/dist to the configured project. Wrangler stores authentication locally; never place tokens in source code. The site itself does not need authentication variables.

For a first setup in a different account, create the project first:

npx wrangler pages project create mochi-sdk --production-branch main

If you choose a different project name, update site/wrangler.jsonc, the workspace deploy command, and PUBLIC_SITE_URL. Project names and domain availability are account/platform dependent.

Git-connected builds

This repository includes CI build validation. Publishing uses the explicit deployment command above. To enable automatic publishing, connect the GitHub repository in the Cloudflare Pages dashboard and use the settings table. As described in Cloudflare’s Direct Upload guide, a direct-upload project cannot be converted to Git integration; create a separate Git-connected project if that is your preferred workflow. Alternatively, use a narrowly scoped Pages API token in your own CI secret store and call Wrangler from a deployment job.

Do not put account IDs, API tokens, or local auth files in the public repository. Preview deployments should use a separate branch or project when validating changes before production.

Add your custom subdomain

In the Pages project, add the desired hostname under Custom domains and follow Cloudflare’s DNS verification instructions. Domain/DNS configuration is managed by the domain owner. Set the canonical site URL to the final HTTPS address and rebuild:

PUBLIC_SITE_URL=https://docs.example.com npm run deploy

Use that same environment variable in a Git-connected build configuration. It controls canonical links, social image URLs, robots, and the sitemap. Do not put a trailing path into it; the site is designed for a domain root, not a subdirectory.

Verify a deployment

Check the landing page, a nested documentation URL, a missing URL, /search-index.json, /sitemap.xml, and /robots.txt. Verify both themes and reload after choosing another companion. Assets under /_astro/ use content hashes and long-lived caching. Documents and the search index are not given an immutable cache rule.

public/_headers applies MIME-sniffing, framing, referrer, and hardware-permission protections. There is no catch-all SPA rewrite, so unknown routes return the custom 404 page. Keep the build artifact free of local settings and device data.

Roll back

Use the Pages dashboard to roll production back to a previous successful production deployment, or check out a known-good revision and redeploy it. A domain change also needs a rebuild with the appropriate PUBLIC_SITE_URL. Test the restored landing page and documentation URLs after rollback.