1# Patterns
2 
3## API Routes
4 
5```typescript
6// functions/api/todos/[id].ts
7export const onRequestGet: PagesFunction<Env> = async ({ env, params }) => {
8  const todo = await env.DB.prepare('SELECT * FROM todos WHERE id = ?').bind(params.id).first();
9  if (!todo) return new Response('Not found', { status: 404 });
10  return Response.json(todo);
11};
12 
13export const onRequestPut: PagesFunction<Env> = async ({ env, params, request }) => {
14  const body = await request.json();
15  await env.DB.prepare('UPDATE todos SET title = ?, completed = ? WHERE id = ?')
16    .bind(body.title, body.completed, params.id).run();
17  return Response.json({ success: true });
18};
19// Also: onRequestDelete, onRequestPost
20```
21 
22## Auth Middleware
23 
24```typescript
25// functions/_middleware.ts
26const auth: PagesFunction<Env> = async (context) => {
27  if (context.request.url.includes('/public/')) return context.next();
28  const authHeader = context.request.headers.get('Authorization');
29  if (!authHeader?.startsWith('Bearer ')) {
30    return new Response('Unauthorized', { status: 401 });
31  }
32  
33  try {
34    const payload = await verifyJWT(authHeader.substring(7), context.env.JWT_SECRET);
35    context.data.user = payload;
36    return context.next();
37  } catch (err) {
38    return new Response('Invalid token', { status: 401 });
39  }
40};
41export const onRequest = [auth];
42```
43 
44## CORS
45 
46```typescript
47// functions/api/_middleware.ts
48const corsHeaders = {
49  'Access-Control-Allow-Origin': '*',
50  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
51  'Access-Control-Allow-Headers': 'Content-Type, Authorization'
52};
53 
54export const onRequest: PagesFunction = async (context) => {
55  if (context.request.method === 'OPTIONS') {
56    return new Response(null, {headers: corsHeaders});
57  }
58  const response = await context.next();
59  Object.entries(corsHeaders).forEach(([k, v]) => response.headers.set(k, v));
60  return response;
61};
62```
63 
64## Form Handling
65 
66```typescript
67// functions/api/contact.ts
68export const onRequestPost: PagesFunction<Env> = async ({ request, env }) => {
69  const formData = await request.formData();
70  await env.QUEUE.send({name: formData.get('name'), email: formData.get('email')});
71  return new Response('<h1>Thanks!</h1>', { headers: { 'Content-Type': 'text/html' } });
72};
73```
74 
75## Background Tasks
76 
77```typescript
78export const onRequestPost: PagesFunction = async ({ request, waitUntil }) => {
79  const data = await request.json();
80  waitUntil(fetch('https://api.example.com/webhook', {
81    method: 'POST', body: JSON.stringify(data)
82  }));
83  return Response.json({ queued: true });
84};
85```
86 
87## Error Handling
88 
89```typescript
90// functions/_middleware.ts
91const errorHandler: PagesFunction = async (context) => {
92  try {
93    return await context.next();
94  } catch (error) {
95    console.error('Error:', error);
96    if (context.request.url.includes('/api/')) {
97      return Response.json({ error: error.message }, { status: 500 });
98    }
99    return new Response(`<h1>Error</h1><p>${error.message}</p>`, { 
100      status: 500, headers: { 'Content-Type': 'text/html' } 
101    });
102  }
103};
104export const onRequest = [errorHandler];
105```
106 
107## Caching
108 
109```typescript
110// functions/api/data.ts
111export const onRequestGet: PagesFunction<Env> = async ({ env, request }) => {
112  const cacheKey = `data:${new URL(request.url).pathname}`;
113  const cached = await env.KV.get(cacheKey, 'json');
114  if (cached) return Response.json(cached, { headers: { 'X-Cache': 'HIT' } });
115  
116  const data = await env.DB.prepare('SELECT * FROM data').first();
117  await env.KV.put(cacheKey, JSON.stringify(data), {expirationTtl: 3600});
118  return Response.json(data, {headers: {'X-Cache': 'MISS'}});
119};
120```
121 
122## Smart Placement for Database Apps
123 
124Enable Smart Placement for apps with D1 or centralized data sources:
125 
126```jsonc
127// wrangler.jsonc
128{
129  "name": "global-app",
130  "placement": {
131    "mode": "smart"
132  },
133  "d1_databases": [{
134    "binding": "DB",
135    "database_id": "your-db-id"
136  }]
137}
138```
139 
140```typescript
141// functions/api/data.ts
142export const onRequestGet: PagesFunction<Env> = async ({ env }) => {
143  // Smart Placement optimizes execution location over time
144  // Balances user location vs database location
145  const data = await env.DB.prepare('SELECT * FROM products LIMIT 10').all();
146  return Response.json(data);
147};
148```
149 
150**Best for**: Read-heavy apps with D1/Durable Objects in specific regions.  
151**Not needed**: Apps without data locality constraints or with evenly distributed traffic.
152 
153## Framework Integration
154 
155**Supported** (2026): SvelteKit, Astro, Nuxt, Qwik, Solid Start
156 
157```bash
158npm create cloudflare@latest my-app -- --framework=svelte
159```
160 
161### SvelteKit
162```typescript
163// src/routes/+page.server.ts
164export const load = async ({ platform }) => {
165  const todos = await platform.env.DB.prepare('SELECT * FROM todos').all();
166  return { todos: todos.results };
167};
168```
169 
170### Astro
171```astro
172---
173const { DB } = Astro.locals.runtime.env;
174const todos = await DB.prepare('SELECT * FROM todos').all();
175---
176<ul>{todos.results.map(t => <li>{t.title}</li>)}</ul>
177```
178 
179### Nuxt
180```typescript
181// server/api/todos.get.ts
182export default defineEventHandler(async (event) => {
183  const { DB } = event.context.cloudflare.env;
184  return await DB.prepare('SELECT * FROM todos').all();
185});
186```
187 
188**⚠️ Framework Status** (2026):
189- ✅ **Supported**: SvelteKit, Astro, Nuxt, Qwik, Solid Start
190- ❌ **Deprecated**: Next.js (`@cloudflare/next-on-pages`), Remix (`@remix-run/cloudflare-pages`)
191 
192For deprecated frameworks, see [gotchas.md](./gotchas.md#framework-specific) for migration options.
193 
194[Framework Guides](https://developers.cloudflare.com/pages/framework-guides/)
195 
196## Monorepo
197 
198Dashboard → Settings → Build → Root directory. Set to subproject (e.g., `apps/web`).
199 
200## Best Practices
201 
202**Performance**: Exclude static via `_routes.json`; cache with KV; keep bundle < 1MB  
203**Security**: Use secrets (not vars); validate inputs; rate limit with KV/DO  
204**Workflow**: Preview per branch; local dev with `wrangler pages dev`; instant rollbacks in Dashboard
205