1# Common Patterns
2 
3## Background Tasks (waitUntil)
4 
5Non-blocking tasks after response sent (analytics, cleanup, webhooks):
6 
7```typescript
8export async function onRequest(ctx: EventContext<Env>) {
9  const res = Response.json({ success: true });
10  
11  ctx.waitUntil(ctx.env.KV.put('last-visit', new Date().toISOString()));
12  ctx.waitUntil(Promise.all([
13    ctx.env.ANALYTICS.writeDataPoint({ event: 'view' }),
14    fetch('https://webhook.site/...', { method: 'POST' })
15  ]));
16  
17  return res; // Returned immediately
18}
19```
20 
21## Middleware & Auth
22 
23```typescript
24// functions/_middleware.js (global) or functions/users/_middleware.js (scoped)
25export async function onRequest(ctx) {
26  try { return await ctx.next(); } 
27  catch (err) { return new Response(err.message, { status: 500 }); }
28}
29 
30// Chained: export const onRequest = [errorHandler, auth, logger];
31 
32// Auth
33async function auth(ctx: EventContext<Env>) {
34  const token = ctx.request.headers.get('authorization')?.replace('Bearer ', '');
35  if (!token) return new Response('Unauthorized', { status: 401 });
36  const session = await ctx.env.KV.get(`session:${token}`);
37  if (!session) return new Response('Invalid', { status: 401 });
38  ctx.data.user = JSON.parse(session);
39  return ctx.next();
40}
41```
42 
43## CORS & Rate Limiting
44 
45```typescript
46// CORS middleware
47const cors = { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST' };
48export async function onRequestOptions() { return new Response(null, { headers: cors }); }
49export async function onRequest(ctx) {
50  const res = await ctx.next();
51  Object.entries(cors).forEach(([k, v]) => res.headers.set(k, v));
52  return res;
53}
54 
55// Rate limiting (KV-based)
56async function rateLimit(ctx: EventContext<Env>) {
57  const ip = ctx.request.headers.get('CF-Connecting-IP') || 'unknown';
58  const count = parseInt(await ctx.env.KV.get(`rate:${ip}`) || '0');
59  if (count >= 100) return new Response('Rate limited', { status: 429 });
60  await ctx.env.KV.put(`rate:${ip}`, (count + 1).toString(), { expirationTtl: 3600 });
61  return ctx.next();
62}
63```
64 
65## Forms, Caching, Redirects
66 
67```typescript
68// JSON & file upload
69export async function onRequestPost(ctx) {
70  const ct = ctx.request.headers.get('content-type') || '';
71  if (ct.includes('application/json')) return Response.json(await ctx.request.json());
72  if (ct.includes('multipart/form-data')) {
73    const file = (await ctx.request.formData()).get('file') as File;
74    await ctx.env.BUCKET.put(file.name, file.stream());
75    return Response.json({ uploaded: file.name });
76  }
77}
78 
79// Cache API
80export async function onRequest(ctx) {
81  let res = await caches.default.match(ctx.request);
82  if (!res) {
83    res = new Response('Data');
84    res.headers.set('Cache-Control', 'public, max-age=3600');
85    ctx.waitUntil(caches.default.put(ctx.request, res.clone()));
86  }
87  return res;
88}
89 
90// Redirects
91export async function onRequest(ctx) {
92  if (new URL(ctx.request.url).pathname === '/old') {
93    return Response.redirect(new URL('/new', ctx.request.url), 301);
94  }
95  return ctx.next();
96}
97```
98 
99## Testing
100 
101**Unit tests** (Vitest + cloudflare:test):
102```typescript
103import { env } from 'cloudflare:test';
104import { it, expect } from 'vitest';
105import { onRequest } from '../functions/api';
106 
107it('returns JSON', async () => {
108  const req = new Request('http://localhost/api');
109  const ctx = { request: req, env, params: {}, data: {} } as EventContext;
110  const res = await onRequest(ctx);
111  expect(res.status).toBe(200);
112});
113```
114 
115**Integration:** `wrangler pages dev` + Playwright/Cypress
116 
117## Advanced Mode (_worker.js)
118 
119Use `_worker.js` for complex routing (replaces `/functions`):
120 
121```typescript
122interface Env { ASSETS: Fetcher; KV: KVNamespace; }
123 
124export default {
125  async fetch(request: Request, env: Env): Promise<Response> {
126    const url = new URL(request.url);
127    if (url.pathname.startsWith('/api/')) {
128      return Response.json({ data: await env.KV.get('key') });
129    }
130    return env.ASSETS.fetch(request); // Static files
131  }
132} satisfies ExportedHandler<Env>;
133```
134 
135**When:** Existing Worker, framework-generated (Next.js/SvelteKit), custom routing logic
136 
137**See also:** [api.md](./api.md) for `env.ASSETS.fetch()` | [gotchas.md](./gotchas.md) for debugging
138