/scaffold

name: blueprint-cloudflare-scaffold
description: "Lay out a Worker with D1 and static Vue assets, with tests that run inside the Workers runtime."

App skeleton

One folder, one `package.json`, TypeScript throughout, `yarn`. The later checks rely on this layout exactly:

wrangler.jsonc          the Worker: main, compatibility_date, assets, the D1 binding "DB"
src/worker/index.ts     the Worker's fetch handler; /api/* is the API, everything else is the Vue app
migrations/             D1 migrations: numbered .sql files, applied by wrangler
index.html              the Vue entry (<div id="app">)
src/client/             Vue 3 + Vite
public/_headers         the security headers for the static files (they do not go through the Worker)
vitest.config.ts        @cloudflare/vitest-pool-workers: tests run in workerd with D1, migrations applied first
test/                   one file per area: data.test.ts, api.test.ts, ui.test.ts, auth.test.ts

• Dev dependencies: `wrangler`, `vite`, `@vitejs/plugin-vue`, `vue`, `typescript`, `@cloudflare/workers-types`,

`@cloudflare/vitest-pool-workers`, and the `vitest` major that it asks for as a peer (check `yarn why` and the install warnings: a newer vitest than it supports fails to start).

• `typescript@^6`, not 7: a later check reads the test files through TypeScript's compiler API, which TypeScript 7

does not ship.

• `wrangler.jsonc`:
• `assets`: `{ "directory": "./dist/client", "not_found_handling": "single-page-application", "run_worker_first": ["/api/*"] }`
• `d1_databases`: one entry with `"binding": "DB"`, `"migrations_dir": "migrations"`. The `database_id` is a

placeholder until the publish step creates the real database.

• `compatibility_date`: a date the installed wrangler's runtime supports — about a month before today. A date

newer than the runtime refuses to start ("requires compatibility date … newest supported is …").

• Scripts:
• `build`: `vite build` into `dist/client`
• `start`: `wrangler d1 migrations apply DB --local && wrangler dev --local --ip 127.0.0.1`. The checks run

`yarn start --port <n>`, so extra arguments must reach `wrangler dev`.

• `test`: `vitest run`
• `deploy`: `wrangler deploy`
• `GET /api/health` answers `{ "ok": true }`.
• The tests read the migrations with `readD1Migrations` and apply them in a setup file with `applyD1Migrations`, so

every test starts from the same schema. Call the Worker through `SELF.fetch` from `cloudflare:test`.

• Add one trivial passing test in `test/` so the harness is proven.

Done when the check passes: the layout exists, `yarn build` and `yarn test` succeed.

Always

• Read `.blueprint/spec.md` first. It is the agreed specification; do not widen it.
• When you need a decision, ask it through the blueprint question tool and stop. Do not guess.
• Do not run `git init`: a new repository loses the folder's trust and the next unattended step stops at Claude

Code's trust prompt. The user adds git themselves after the build if they want it.

• Say you are done by stopping; the executor runs the check. Do not claim success yourself.