From c427fc8260c0feddb0cf61f1f692cc596ab9c4db Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Tue, 17 Mar 2026 14:42:44 -0700 Subject: [PATCH 1/5] feat: add AGENTS.md to d1-template --- d1-template/AGENTS.md | 61 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 d1-template/AGENTS.md diff --git a/d1-template/AGENTS.md b/d1-template/AGENTS.md new file mode 100644 index 000000000..667c4b670 --- /dev/null +++ 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. From 605761e8db1bc6ef13091ff7e8c4c2751f929a5f Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Tue, 17 Mar 2026 14:42:48 -0700 Subject: [PATCH 2/5] feat: add AGENTS.md to durable-chat-template --- durable-chat-template/AGENTS.md | 63 +++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 durable-chat-template/AGENTS.md diff --git a/durable-chat-template/AGENTS.md b/durable-chat-template/AGENTS.md new file mode 100644 index 000000000..718279486 --- /dev/null +++ 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. From 58e78307035abb701767f4a505d5ac0b4a3fbf38 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Tue, 17 Mar 2026 14:42:52 -0700 Subject: [PATCH 3/5] feat: add AGENTS.md to react-router-starter-template --- react-router-starter-template/AGENTS.md | 62 +++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 react-router-starter-template/AGENTS.md diff --git a/react-router-starter-template/AGENTS.md b/react-router-starter-template/AGENTS.md new file mode 100644 index 000000000..6a4387377 --- /dev/null +++ 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. From c11464d6af86c609048f06e12abe000de0aa2ac8 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Tue, 17 Mar 2026 14:42:57 -0700 Subject: [PATCH 4/5] feat: add AGENTS.md to saas-admin-template --- saas-admin-template/AGENTS.md | 72 +++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 saas-admin-template/AGENTS.md diff --git a/saas-admin-template/AGENTS.md b/saas-admin-template/AGENTS.md new file mode 100644 index 000000000..64208927d --- /dev/null +++ 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= +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. From ef71a67c11c7a4e11c14729fe5e60cdec4d79633 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Tue, 17 Mar 2026 14:43:01 -0700 Subject: [PATCH 5/5] feat: add AGENTS.md to postgres-hyperdrive-template --- postgres-hyperdrive-template/AGENTS.md | 73 ++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 postgres-hyperdrive-template/AGENTS.md diff --git a/postgres-hyperdrive-template/AGENTS.md b/postgres-hyperdrive-template/AGENTS.md new file mode 100644 index 000000000..68754c776 --- /dev/null +++ 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.