Cloudflare Web App — House Stack
The reference for what to pick when starting a new web project. Every choice
here is already running in production across the other repos, so matching it
means CI, hooks, deploy, and agent workflows all behave the way they do
elsewhere.
Cloudflare is the infra and the backend. Workers, D1, KV, R2, Durable
Objects, Workers AI, Queues. Not AWS, not Vercel, not Netlify, not Supabase.
Reach outside Cloudflare only for something Cloudflare genuinely lacks (Stripe,
Resend, npm registry) and say so explicitly.
Two modes
Reference mode (default) — the user described a project and wants the stack.
Read the tables below, pick the project shape, read the reference files that
matter for that shape, and report the recommended stack with concrete versions
and file names. Do not write files.
Scaffold mode — the user passed --scaffold or asked to actually create the
project. Do reference mode first, confirm the shape, then copy from
assets/templates/ and adapt. See "Scaffolding" below.
Step 1 — Pick the project shape
| Shape |
When |
Frontend |
Deploy target |
| Content site |
Marketing, blog, portfolio, landing |
zfb + Preact + Tailwind v4 |
Workers Static Assets |
| Docs site |
Reference docs, manuals, changelog |
zudo-doc (a zfb preset) |
Workers Static Assets |
| SSR app |
Auth, forms, DB-backed pages |
zfb SSR routes (prerender = false) + CF adapter |
Workers Static Assets + bindings |
| API / worker |
JSON API, webhook, proxy, cron, agent |
Hono on Workers, no frontend |
Workers |
| Interactive app |
Editor, dashboard, canvas, heavy client state |
Vite + React + Tailwind v4 |
Workers Static Assets (+ separate API worker) |
| Library / CLI |
Publishable npm package |
none |
npm — use /dev-npm-package instead |
Mixed projects are normal: a pnpm workspace with a zfb site at the root and
worker packages under workers/*. Split when the deploy units differ.
Step 2 — The non-negotiable base
Every repo gets these regardless of shape. Details and rationale in
references/tooling.md.
| Concern |
Choice |
| Package manager |
pnpm, packageManager pinned in package.json, engines.node >= 22 |
| Language |
TypeScript, strict: true |
| Unit tests |
vitest |
| Worker tests |
@cloudflare/vitest-pool-workers |
| E2E |
Playwright |
| Format |
Prettier for code, @takazudo/mdx-formatter for .md/.mdx |
| Lint |
ESLint flat config (eslint.config.js) |
| Git hooks |
lefthook (lefthook.yml) + prepare script |
| Pre-push gate |
pnpm b4push — mirrors CI locally |
| CI |
GitHub Actions, SHA-pinned actions |
| Deploy |
wrangler deploy from GitHub Actions |
| Dep updates |
Renovate (preferred) or Dependabot |
Step 3 — Read the reference for what you're deciding
Load only what the current decision needs.
references/stack.md — every library choice with its
rationale, plus the explicit do-not-use list (Pages, Next.js, AWS SDK,
Prisma, Jest, styled-components, …). Read this for any "what should we use
for X" question.
references/cloudflare.md — wrangler.toml
anatomy, Workers Static Assets, bindings (D1/KV/R2/DO/AI/Queues/services),
named environments, preview aliases, secrets vs vars, and the TOML/config
gotchas that cost real debugging time.
references/ci.md — the standard workflow set, SHA pinning,
concurrency, self-skipping deploy jobs, PR preview comments, actionlint,
security audit.
references/tooling.md — pnpm settings, workspace
layout, lefthook, prettier, eslint, mdx-formatter, design-token-lint,
tsconfig, the b4push script.
references/testing.md — test levels and tiers, what
runs in b4push vs CI vs nightly, Playwright conventions.
references/conventions.md — directory layout,
CLAUDE.md, docs site, README, worktrees, .gitignore, scratch dirs.
For Cloudflare platform API detail (exact binding APIs, runtime limits,
current wrangler flags), defer to the Cloudflare plugin skills — /cloudflare:cloudflare,
/cloudflare:wrangler, /cloudflare:workers-best-practices,
/cloudflare:durable-objects, and /cloudflare:agents-sdk — they
retrieve live docs. This skill owns the opinion; those own the facts.
Step 4 — Report
Report as a short stack table (shape, framework, styling, data, tests, CI,
deploy target) plus the list of files the project needs. Name the Cloudflare
resources that must be provisioned (D1 database, KV namespace, R2 bucket,
custom domain) and the secrets that must be set — these are manual, one-time,
and easy to forget.
Scaffolding
Only in scaffold mode. Copy from assets/templates/ and adapt — every file
carries comments explaining the traps, so keep them.
| Template |
Copy to |
Notes |
package.json |
package.json |
Replace latest with resolved versions after the first install |
pnpm-workspace.yaml |
same |
Delete if single-package |
npmrc |
.npmrc |
|
gitignore |
.gitignore |
|
prettierignore |
.prettierignore |
|
.prettierrc.json |
same |
|
tsconfig.json |
same |
|
lefthook.yml |
same |
|
wrangler.toml |
same |
Strip unused binding blocks |
.github/workflows/*.yml |
same |
ci.yml, deploy.yml, actionlint.yml |
scripts/run-b4push.sh |
same |
chmod +x; keep steps identical to ci.yml |
scripts/smoke.mjs |
same |
Fill in EXPECTED with real page markers |
scripts/install-git-hooks.sh, scripts/hooks/pre-push |
same |
chmod +x both |
cloudflare-setup.md |
docs/cloudflare-setup.md |
|
Three templates ship without their leading dot (npmrc, gitignore,
prettierignore) so they stay inert inside this skill's own repo — rename on
copy.
Then:
Replace every __PROJECT_NAME__ and __DOMAIN__ placeholder
Write README.md and CLAUDE.md (outline in
references/conventions.md)
pnpm install, then confirm pnpm b4push passes before the first push
Do not invent Cloudflare resource ids. Leave REPLACE_ME plus the
wrangler ... create command that produces it — the deploy job self-skips until
the real id is committed.
1---2name: dev-basic-cloudflare-webapp3description: "The house tech stack for a new web project on Cloudflare — framework, lint, test, CI, docs, and repo conventions, with copy-ready config templates. Cloudflare is the default infra and backend (Workers, D1, KV, R2, Durable Objects); AWS is not. Use this whenever a new web app, site, API, or worker is being started or scaffolded, whenever someone asks 'what stack should we use', 'what should I pick for X', 'set up CI/lint/test for this project', or 'scaffold a new project' — even if Cloudflare is never named, because Cloudflare is the assumed target. Also use when adding CI, lint, formatting, git hooks, deploy workflows, or a docs site to an existing project so it matches the other repos. Keywords: new project, scaffold, boilerplate, starter, tech stack, tech choice, Cloudflare, Workers, wrangler, D1, KV, R2, Durable Objects, zfb, zudo-doc, pnpm, lefthook, vitest, playwright, GitHub Actions, b4push."4argument-hint: "[project description] [--scaffold]"5metadata:6 source: https://skillmd.com/skills/takazudo/dev-basic-cloudflare-webapp7---89# Cloudflare Web App — House Stack1011The reference for what to pick when starting a new web project. Every choice12here is already running in production across the other repos, so matching it13means CI, hooks, deploy, and agent workflows all behave the way they do14elsewhere.1516**Cloudflare is the infra and the backend.** Workers, D1, KV, R2, Durable17Objects, Workers AI, Queues. Not AWS, not Vercel, not Netlify, not Supabase.18Reach outside Cloudflare only for something Cloudflare genuinely lacks (Stripe,19Resend, npm registry) and say so explicitly.2021## Two modes2223**Reference mode (default)** — the user described a project and wants the stack.24Read the tables below, pick the project shape, read the reference files that25matter for that shape, and report the recommended stack with concrete versions26and file names. Do not write files.2728**Scaffold mode** — the user passed `--scaffold` or asked to actually create the29project. Do reference mode first, confirm the shape, then copy from30`assets/templates/` and adapt. See "Scaffolding" below.3132## Step 1 — Pick the project shape3334| Shape | When | Frontend | Deploy target |35| --- | --- | --- | --- |36| **Content site** | Marketing, blog, portfolio, landing | zfb + Preact + Tailwind v4 | Workers Static Assets |37| **Docs site** | Reference docs, manuals, changelog | zudo-doc (a zfb preset) | Workers Static Assets |38| **SSR app** | Auth, forms, DB-backed pages | zfb SSR routes (`prerender = false`) + CF adapter | Workers Static Assets + bindings |39| **API / worker** | JSON API, webhook, proxy, cron, agent | Hono on Workers, no frontend | Workers |40| **Interactive app** | Editor, dashboard, canvas, heavy client state | Vite + React + Tailwind v4 | Workers Static Assets (+ separate API worker) |41| **Library / CLI** | Publishable npm package | none | npm — use `/dev-npm-package` instead |4243Mixed projects are normal: a pnpm workspace with a zfb site at the root and44worker packages under `workers/*`. Split when the deploy units differ.4546## Step 2 — The non-negotiable base4748Every repo gets these regardless of shape. Details and rationale in49[references/tooling.md](references/tooling.md).5051| Concern | Choice |52| --- | --- |53| Package manager | pnpm, `packageManager` pinned in package.json, `engines.node >= 22` |54| Language | TypeScript, `strict: true` |55| Unit tests | vitest |56| Worker tests | `@cloudflare/vitest-pool-workers` |57| E2E | Playwright |58| Format | Prettier for code, `@takazudo/mdx-formatter` for `.md`/`.mdx` |59| Lint | ESLint flat config (`eslint.config.js`) |60| Git hooks | lefthook (`lefthook.yml`) + `prepare` script |61| Pre-push gate | `pnpm b4push` — mirrors CI locally |62| CI | GitHub Actions, SHA-pinned actions |63| Deploy | `wrangler deploy` from GitHub Actions |64| Dep updates | Renovate (preferred) or Dependabot |6566## Step 3 — Read the reference for what you're deciding6768Load only what the current decision needs.6970- [references/stack.md](references/stack.md) — every library choice with its7172 rationale, plus the explicit **do-not-use** list (Pages, Next.js, AWS SDK,73 Prisma, Jest, styled-components, …). Read this for any "what should we use74 for X" question.7576- [references/cloudflare.md](references/cloudflare.md) — `wrangler.toml`7778 anatomy, Workers Static Assets, bindings (D1/KV/R2/DO/AI/Queues/services),79 named environments, preview aliases, secrets vs vars, and the TOML/config80 gotchas that cost real debugging time.8182- [references/ci.md](references/ci.md) — the standard workflow set, SHA pinning,8384 concurrency, self-skipping deploy jobs, PR preview comments, actionlint,85 security audit.8687- [references/tooling.md](references/tooling.md) — pnpm settings, workspace8889 layout, lefthook, prettier, eslint, mdx-formatter, design-token-lint,90 tsconfig, the b4push script.9192- [references/testing.md](references/testing.md) — test levels and tiers, what9394 runs in b4push vs CI vs nightly, Playwright conventions.9596- [references/conventions.md](references/conventions.md) — directory layout,9798 `CLAUDE.md`, docs site, README, worktrees, `.gitignore`, scratch dirs.99100For Cloudflare **platform** API detail (exact binding APIs, runtime limits,101current wrangler flags), defer to the Cloudflare plugin skills — `/cloudflare:cloudflare`,102`/cloudflare:wrangler`, `/cloudflare:workers-best-practices`,103`/cloudflare:durable-objects`, and `/cloudflare:agents-sdk` — they104retrieve live docs. This skill owns the *opinion*; those own the *facts*.105106## Step 4 — Report107108Report as a short stack table (shape, framework, styling, data, tests, CI,109deploy target) plus the list of files the project needs. Name the Cloudflare110resources that must be provisioned (D1 database, KV namespace, R2 bucket,111custom domain) and the secrets that must be set — these are manual, one-time,112and easy to forget.113114## Scaffolding115116Only in scaffold mode. Copy from `assets/templates/` and adapt — every file117carries comments explaining the traps, so keep them.118119| Template | Copy to | Notes |120| --- | --- | --- |121| `package.json` | `package.json` | Replace `latest` with resolved versions after the first install |122| `pnpm-workspace.yaml` | same | Delete if single-package |123| `npmrc` | `.npmrc` | |124| `gitignore` | `.gitignore` | |125| `prettierignore` | `.prettierignore` | |126| `.prettierrc.json` | same | |127| `tsconfig.json` | same | |128| `lefthook.yml` | same | |129| `wrangler.toml` | same | Strip unused binding blocks |130| `.github/workflows/*.yml` | same | `ci.yml`, `deploy.yml`, `actionlint.yml` |131| `scripts/run-b4push.sh` | same | `chmod +x`; keep steps identical to `ci.yml` |132| `scripts/smoke.mjs` | same | Fill in `EXPECTED` with real page markers |133| `scripts/install-git-hooks.sh`, `scripts/hooks/pre-push` | same | `chmod +x` both |134| `cloudflare-setup.md` | `docs/cloudflare-setup.md` | |135136Three templates ship without their leading dot (`npmrc`, `gitignore`,137`prettierignore`) so they stay inert inside this skill's own repo — rename on138copy.139140Then:1411421. Replace every `__PROJECT_NAME__` and `__DOMAIN__` placeholder1432. Write `README.md` and `CLAUDE.md` (outline in144145 [references/conventions.md](references/conventions.md))1461473. `pnpm install`, then confirm `pnpm b4push` passes before the first push148149Do not invent Cloudflare resource ids. Leave `REPLACE_ME` plus the150`wrangler ... create` command that produces it — the deploy job self-skips until151the real id is committed.