cloudflare · zeke · Mar 17, 2026 · Mar 17, 2026 · Mar 17, 2026 · Mar 17, 2026
diff --git a/d1-template/AGENTS.md b/d1-template/AGENTS.md
@@ -0,0 +1,61 @@
+# D1 Template
+
+A minimal Cloudflare Worker that queries a D1 (serverless SQLite) database and renders the results as HTML. Runs `SELECT * FROM comments LIMIT 3` against a seeded table. Good starting point for any Worker + D1 project.
+
+## Setup
+
+```bash
+npm install
+npx wrangler d1 create d1-template-database
+# Update database_id in wrangler.json with the returned ID
+npm run dev
+```
+
+The `dev` script seeds the local D1 database via migrations before starting the dev server.
+
+## Configuration
+
+| Name | Type        | Required | Description                              |
+| ---- | ----------- | -------- | ---------------------------------------- |
+| `DB` | D1 Database | Yes      | Bound to database `d1-template-database` |
+
+No secrets or environment variables needed. After creating the database, update `database_id` in `wrangler.json`.
+
+## Development
+
+The Worker entry point (`src/index.ts`) runs a prepared statement against the `DB` binding and passes the results to a rendering function (`src/renderHtml.ts`). There's no router — every request returns the same page.
+
+Schema changes go in new migration files under `migrations/`. Apply locally with `npx wrangler d1 migrations apply DB --local`. Run `npm run cf-typegen` after changing bindings to regenerate types.
+
+## Deployment
+
+```bash
+npm run deploy
+```
+
+The `predeploy` script runs remote D1 migrations automatically.
+
+## Cloudflare Resources
+
+### Skills
+
+For deeper guidance on the products used in this template, load these [Cloudflare Skills](https://github.com/cloudflare/skills):
+
+- `cloudflare` — Workers, D1, and the broader developer platform
+- `wrangler` — CLI for deploying and managing Workers and D1
+
+### MCP Servers
+
+These [Cloudflare MCP servers](https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/) can help when working with this template:
+
+| Server           | URL                                            | Use for                                                          |
+| ---------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
+| Cloudflare API   | `https://mcp.cloudflare.com/mcp`               | Managing D1 databases, Workers, DNS, and the full Cloudflare API |
+| Documentation    | `https://docs.mcp.cloudflare.com/mcp`          | Looking up D1 and Workers docs                                   |
+| Workers Bindings | `https://bindings.mcp.cloudflare.com/mcp`      | Building with D1 bindings                                        |
+| Workers Builds   | `https://builds.mcp.cloudflare.com/mcp`        | Managing deployments                                             |
+| Observability    | `https://observability.mcp.cloudflare.com/mcp` | Debugging logs and analytics                                     |
+
+## Maintaining this file
+
+Keep this AGENTS.md up to date as the template evolves. If you add bindings, change the schema, or modify the architecture, update this file to reflect those changes.
diff --git a/durable-chat-template/AGENTS.md b/durable-chat-template/AGENTS.md
@@ -0,0 +1,63 @@
+# Durable Chat Template
+
+A real-time chat application using Cloudflare Durable Objects and PartyKit. Each chat room is a Durable Object instance with WebSocket connections and SQLite-backed message persistence. The frontend is a React SPA bundled with esbuild. Sharing a room URL lets multiple users chat in real time.
+
+## Setup
+
+```bash
+npm install
+npm run dev
+```
+
+No database setup or migrations needed — the Durable Object creates its SQLite table on first use.
+
+## Configuration
+
+| Name     | Type           | Required | Description                              |
+| -------- | -------------- | -------- | ---------------------------------------- |
+| `Chat`   | Durable Object | Yes      | DO namespace for the Chat class          |
+| `ASSETS` | Static Assets  | Yes      | Serves files from `./public` in SPA mode |
+
+No secrets or environment variables.
+
+## Development
+
+The server (`src/server/index.ts`) has a Worker fetch handler that routes PartyKit WebSocket upgrades to the `Chat` Durable Object, falling back to static asset serving via the `ASSETS` binding. The `Chat` class extends `partyserver.Server` with hibernation enabled — it persists messages to DO SQLite storage and broadcasts to all connected clients.
+
+The client (`src/client/index.tsx`) is a React SPA using `react-router` for room URLs and `partysocket/react` for WebSocket connectivity. It's bundled by esbuild via the `build.command` in `wrangler.json`, which runs automatically during dev and deploy.
+
+Shared types and constants live in `src/shared.ts` and are imported by both client and server.
+
+## Deployment
+
+```bash
+npm run deploy
+```
+
+The esbuild step and DO migration run automatically.
+
+## Cloudflare Resources
+
+### Skills
+
+For deeper guidance on the products used in this template, load these [Cloudflare Skills](https://github.com/cloudflare/skills):
+
+- `durable-objects` — Stateful coordination, SQLite storage, WebSockets, hibernation
+- `cloudflare` — Workers and the broader developer platform
+- `wrangler` — CLI for deploying and managing Workers and Durable Objects
+
+### MCP Servers
+
+These [Cloudflare MCP servers](https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/) can help when working with this template:
+
+| Server           | URL                                            | Use for                                                        |
+| ---------------- | ---------------------------------------------- | -------------------------------------------------------------- |
+| Cloudflare API   | `https://mcp.cloudflare.com/mcp`               | Managing Workers, Durable Objects, and the full Cloudflare API |
+| Documentation    | `https://docs.mcp.cloudflare.com/mcp`          | Looking up Durable Objects and Workers docs                    |
+| Workers Bindings | `https://bindings.mcp.cloudflare.com/mcp`      | Building with DO bindings                                      |
+| Workers Builds   | `https://builds.mcp.cloudflare.com/mcp`        | Managing deployments                                           |
+| Observability    | `https://observability.mcp.cloudflare.com/mcp` | Debugging logs and analytics                                   |
+
+## Maintaining this file
+
+Keep this AGENTS.md up to date as the template evolves. If you add bindings, change the message format, or modify the architecture, update this file to reflect those changes.
diff --git a/postgres-hyperdrive-template/AGENTS.md b/postgres-hyperdrive-template/AGENTS.md
@@ -0,0 +1,73 @@
+# Postgres Hyperdrive Template
+
+A Cloudflare Worker that connects to a PostgreSQL database via Hyperdrive and provides a CRUD admin dashboard for managing organizations and users. The frontend is a vanilla JS SPA (no build step) served as static assets. Hyperdrive handles connection pooling and acceleration.
+
+## Setup
+
+```bash
+npm install
+
+# Create a Hyperdrive configuration pointing to your Postgres database
+npx wrangler hyperdrive create hyperdrive-configuration \
+  --connection-string="postgres://user:password@host:5432/dbname"
+
+# Update the id in wrangler.jsonc with the returned Hyperdrive ID
+npm run dev
+```
+
+On first load, the dashboard prompts you to initialize the database tables via `POST /api/initialize`.
+
+For local dev, a `localConnectionString` in `wrangler.jsonc` defaults to `postgresql://postgres:postgres@localhost:5432/defaultdb`. You need a local Postgres instance (e.g., `docker run -d -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres`).
+
+## Configuration
+
+| Name         | Type          | Required | Description                                 |
+| ------------ | ------------- | -------- | ------------------------------------------- |
+| `HYPERDRIVE` | Hyperdrive    | Yes      | Connection pool to your PostgreSQL database |
+| `ASSETS`     | Static Assets | Yes      | Serves the frontend from `public/`          |
+
+No secrets or environment variables. The `nodejs_compat` compatibility flag is required for the `pg` library.
+
+## Development
+
+The Worker entry point (`src/index.ts`) routes `/api/*` requests to handler functions and lets the `ASSETS` binding serve everything else. Each API request creates a `pg.Client` using `env.HYPERDRIVE.connectionString`, runs parameterized SQL queries, and closes the connection in a `finally` block via `ctx.waitUntil(client.end())`.
+
+The frontend is vanilla JS under `public/js/` with no build step — edit and reload.
+
+Tables are created at runtime via the `/api/initialize` endpoint rather than a migration system.
+
+Note: `src/utils.ts` defines a Postgres identifier validator but it's not currently imported anywhere.
+
+## Deployment
+
+```bash
+npm run deploy
+```
+
+Make sure the Hyperdrive ID in `wrangler.jsonc` is correct. Tables are initialized from the UI on first use.
+
+## Cloudflare Resources
+
+### Skills
+
+For deeper guidance on the products used in this template, load these [Cloudflare Skills](https://github.com/cloudflare/skills):
+
+- `cloudflare` — Workers, Hyperdrive, and the broader developer platform
+- `wrangler` — CLI for deploying and managing Workers and Hyperdrive
+- `workers-best-practices` — Patterns for Workers development
+
+### MCP Servers
+
+These [Cloudflare MCP servers](https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/) can help when working with this template:
+
+| Server           | URL                                            | Use for                                                           |
+| ---------------- | ---------------------------------------------- | ----------------------------------------------------------------- |
+| Cloudflare API   | `https://mcp.cloudflare.com/mcp`               | Managing Hyperdrive configs, Workers, and the full Cloudflare API |
+| Documentation    | `https://docs.mcp.cloudflare.com/mcp`          | Looking up Hyperdrive and Workers docs                            |
+| Workers Bindings | `https://bindings.mcp.cloudflare.com/mcp`      | Building with Hyperdrive bindings                                 |
+| Workers Builds   | `https://builds.mcp.cloudflare.com/mcp`        | Managing deployments                                              |
+| Observability    | `https://observability.mcp.cloudflare.com/mcp` | Debugging logs and analytics                                      |
+
+## Maintaining this file
+
+Keep this AGENTS.md up to date as the template evolves. If you add bindings, API endpoints, or change the database setup approach, update this file to reflect those changes.
diff --git a/react-router-starter-template/AGENTS.md b/react-router-starter-template/AGENTS.md
@@ -0,0 +1,62 @@
+# React Router Starter Template
+
+A full-stack React application on Cloudflare Workers using React Router v7 with SSR, TailwindCSS v4, and the Cloudflare Vite plugin. Renders a welcome page that displays a message loaded from a Cloudflare environment variable, demonstrating the data-loading pipeline from Worker fetch handler through React Router loader to React component.
+
+## Setup
+
+```bash
+npm install
+npm run dev
+```
+
+No database, bindings, or secrets needed out of the box.
+
+## Configuration
+
+| Name                    | Type    | Required | Description                                                        |
+| ----------------------- | ------- | -------- | ------------------------------------------------------------------ |
+| `VALUE_FROM_CLOUDFLARE` | Env var | No       | Displayed on the welcome page. Defaults to "Hello from Cloudflare" |
+
+This is a minimal starter. Add bindings to `wrangler.json` and run `npm run cf-typegen` to regenerate types.
+
+## Development
+
+The Worker entry point (`workers/app.ts`) wraps React Router's `createRequestHandler`, passing `env` and `ctx` into the load context as `context.cloudflare.env` and `context.cloudflare.ctx`. Route files under `app/routes/` export loaders and components; register new routes in `app/routes.ts`.
+
+The SSR entry (`app/entry.server.tsx`) streams HTML with `renderToReadableStream` and uses `isbot` for bot-aware buffering.
+
+Vite is configured with the `cloudflare()`, `tailwindcss()`, `reactRouter()`, and `tsconfigPaths()` plugins. The `~/` path alias maps to `./app/`.
+
+Note: the `typecheck` script references a nonexistent `typegen` script. Use `npm run cf-typegen && tsc -b` instead.
+
+## Deployment
+
+```bash
+npm run deploy
+```
+
+## Cloudflare Resources
+
+### Skills
+
+For deeper guidance on the products used in this template, load these [Cloudflare Skills](https://github.com/cloudflare/skills):
+
+- `cloudflare` — Workers, environment variables, and the broader developer platform
+- `wrangler` — CLI for deploying and managing Workers
+- `workers-best-practices` — Patterns for Workers development
+
+### MCP Servers
+
+These [Cloudflare MCP servers](https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/) can help when working with this template:
+
+| Server           | URL                                            | Use for                                            |
+| ---------------- | ---------------------------------------------- | -------------------------------------------------- |
+| Cloudflare API   | `https://mcp.cloudflare.com/mcp`               | Managing Workers, DNS, and the full Cloudflare API |
+| Documentation    | `https://docs.mcp.cloudflare.com/mcp`          | Looking up Workers and Vite plugin docs            |
+| Workers Bindings | `https://bindings.mcp.cloudflare.com/mcp`      | Building with Workers bindings                     |
+| Workers Builds   | `https://builds.mcp.cloudflare.com/mcp`        | Managing deployments                               |
+| Observability    | `https://observability.mcp.cloudflare.com/mcp` | Debugging logs and analytics                       |
+
+## Maintaining this file
+
+Keep this AGENTS.md up to date as the template evolves. If you add bindings, routes, or change the build pipeline, update this file to reflect those changes.
diff --git a/saas-admin-template/AGENTS.md b/saas-admin-template/AGENTS.md
@@ -0,0 +1,72 @@
+# SaaS Admin Template
+
+A SaaS admin dashboard for managing customers and subscriptions, built with Astro, React, and Cloudflare Workers. Features a D1-backed REST API with Bearer token auth, interactive data tables (TanStack Table), CRUD forms (react-hook-form + Zod), a Cloudflare Workflow for background customer processing, and shadcn/ui components styled with Tailwind CSS.
+
+## Setup
+
+Prerequisites: Node.js >= 22.
+
+```bash
+npm install
+cp .dev.vars.example .dev.vars
+# Edit .dev.vars and set API_TOKEN=<your-token>
+npm run dev
+```
+
+The `dev` script runs D1 migrations, builds Astro, copies the workflow wrapper, and starts Wrangler.
+
+## Configuration
+
+| Name                | Type     | Required | Description                                                                    |
+| ------------------- | -------- | -------- | ------------------------------------------------------------------------------ |
+| `DB`                | D1       | Yes      | D1 database named `admin-db`                                                   |
+| `CUSTOMER_WORKFLOW` | Workflow | Yes      | Bound to `CustomerWorkflow` class                                              |
+| `API_TOKEN`         | Secret   | Yes      | Bearer token for API auth. `.dev.vars` locally, `wrangler secret put` for prod |
+
+To create the D1 database for your own account: `npx wrangler d1 create admin-db`, then update `database_id` in `wrangler.jsonc`.
+
+## Development
+
+Astro pages under `src/pages/` query D1 directly via service classes (`src/lib/services/`) during SSR. API routes under `src/pages/api/` require Bearer token auth validated with `crypto.subtle.timingSafeEqual` (three header formats accepted: `Authorization: Bearer`, `Authorization: Token`, `X-Api-Token`).
+
+Interactive React components use `client:only="react"` and call the API via client-side fetch helpers in `src/lib/api.ts`.
+
+The `CustomerWorkflow` class (`src/workflows/customer_workflow.ts`) extends `WorkflowEntrypoint` and is triggered via `POST /api/customers/:id/workflow`.
+
+Build quirk: Astro's build doesn't export non-Astro entry points. A `wrapper.js` re-exports both the Astro app and the `CustomerWorkflow` class — the `wrangler:wrapper` script copies it over Astro's output before deploy.
+
+Database schema is defined in three migration files under `migrations/` (customers, subscriptions/features, customer_subscriptions).
+
+## Deployment
+
+```bash
+npx wrangler secret put API_TOKEN  # first time only
+npm run deploy
+```
+
+The `predeploy` script runs remote D1 migrations automatically.
+
+## Cloudflare Resources
+
+### Skills
+
+For deeper guidance on the products used in this template, load these [Cloudflare Skills](https://github.com/cloudflare/skills):
+
+- `cloudflare` — Workers, D1, Workflows, and the broader developer platform
+- `wrangler` — CLI for deploying and managing Workers, D1, and secrets
+
+### MCP Servers
+
+These [Cloudflare MCP servers](https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/) can help when working with this template:
+
+| Server           | URL                                            | Use for                                                                |
+| ---------------- | ---------------------------------------------- | ---------------------------------------------------------------------- |
+| Cloudflare API   | `https://mcp.cloudflare.com/mcp`               | Managing D1 databases, Workers, Workflows, and the full Cloudflare API |
+| Documentation    | `https://docs.mcp.cloudflare.com/mcp`          | Looking up D1, Workflows, and Workers docs                             |
+| Workers Bindings | `https://bindings.mcp.cloudflare.com/mcp`      | Building with D1 and Workflow bindings                                 |
+| Workers Builds   | `https://builds.mcp.cloudflare.com/mcp`        | Managing deployments                                                   |
+| Observability    | `https://observability.mcp.cloudflare.com/mcp` | Debugging logs and analytics                                           |
+
+## Maintaining this file
+
+Keep this AGENTS.md up to date as the template evolves. If you add bindings, API endpoints, database tables, or change the build pipeline, update this file to reflect those changes.