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. 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. 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. 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. 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.