Cloudflare Pages Storybook Runbook
This runbook configures the standalone Storybook site for storybook.mayadev.cloud.
Project
| Setting | Value |
|---|---|
| Cloudflare Pages project | maya-storybook |
| Production domain | storybook.mayadev.cloud |
| Repository root directory | / |
| Build command | pnpm verify:ui-storybook-build |
| Build output directory | .tmp/storybook/assistant-ui |
| Production branch | main |
| Framework preset | None |
| Build system version | v3 |
NODE_VERSION | 24.9.0 |
PNPM_VERSION | 10.18.3 |
Storybook is a separate artifact. It is linked from docs but is not copied into apps/docs/build.
Keep NODE_VERSION aligned with .node-version and PNPM_VERSION aligned with the root packageManager.
Local Preflight
Run from the workspace root:
pnpm verify:ui-storybook-build
The build output must contain:
.tmp/storybook/assistant-ui/index.html.tmp/storybook/assistant-ui/iframe.html.tmp/storybook/assistant-ui/index.json.tmp/storybook/assistant-ui/_headers
The _headers file is copied from projects/claude-ui/storybook-static-headers by the Storybook build script.
Domain
Attach storybook.mayadev.cloud to the maya-storybook Pages project in Cloudflare. Do not reuse the maya-docs Pages project or Docusaurus build artifact.
The DNS record must be:
storybook.mayadev.cloud CNAME maya-storybook.pages.dev
Do not use an A record for the Storybook host. Cloudflare Pages custom-domain verification reports CNAME record not set until the host points at the Pages project domain.
Preview Deployments
Preview deployments can be enabled for branches and pull requests. A Storybook preview failure should not block docs deploy unless a release owner explicitly chooses a combined release gate.
Rollback
Rollback through the maya-storybook Pages project:
- Select the last known good Storybook deployment.
- Promote or rollback through Cloudflare Pages.
- Run Storybook smoke checks from
.docs/ops/smoke-checks.md. - Record follow-up work in Linear if stories or assets caused the failure.
Forbidden Drift
- Do not iframe Storybook into Docusaurus.
- Do not copy generated Storybook docs into
.docs. - Do not make
apps/docsdepend on.tmp/storybook/assistant-ui. - Do not rewrite existing stories as a deployment side effect.
Direct Upload
Current direct-upload command:
wrangler pages deploy .tmp/storybook/assistant-ui --project-name=maya-storybook --branch=main
If direct upload remains a supported release path, add a pinned wrangler dependency or a pinned CI action in the same change as the release automation. Do not use unpinned pnpm dlx wrangler in release documentation.