1# R2 Patterns & Best Practices
2 
3## Streaming Large Files
4 
5```typescript
6const object = await env.MY_BUCKET.get(key);
7if (!object) return new Response('Not found', { status: 404 });
8 
9const headers = new Headers();
10object.writeHttpMetadata(headers);
11headers.set('etag', object.httpEtag);
12 
13return new Response(object.body, { headers });
14```
15 
16## Conditional GET (304 Not Modified)
17 
18```typescript
19const ifNoneMatch = request.headers.get('if-none-match');
20const object = await env.MY_BUCKET.get(key, {
21  onlyIf: { etagDoesNotMatch: ifNoneMatch?.replace(/"/g, '') || '' }
22});
23 
24if (!object) return new Response('Not found', { status: 404 });
25if (!object.body) return new Response(null, { status: 304, headers: { 'etag': object.httpEtag } });
26 
27return new Response(object.body, { headers: { 'etag': object.httpEtag } });
28```
29 
30## Upload with Validation
31 
32```typescript
33const key = url.pathname.slice(1);
34if (!key || key.includes('..')) return new Response('Invalid key', { status: 400 });
35 
36const object = await env.MY_BUCKET.put(key, request.body, {
37  httpMetadata: { contentType: request.headers.get('content-type') || 'application/octet-stream' },
38  customMetadata: { uploadedAt: new Date().toISOString(), ip: request.headers.get('cf-connecting-ip') || 'unknown' }
39});
40 
41return Response.json({ key: object.key, size: object.size, etag: object.httpEtag });
42```
43 
44## Multipart with Progress
45 
46```typescript
47const PART_SIZE = 5 * 1024 * 1024; // 5MB
48const partCount = Math.ceil(file.size / PART_SIZE);
49const multipart = await env.MY_BUCKET.createMultipartUpload(key, { httpMetadata: { contentType: file.type } });
50 
51const uploadedParts: R2UploadedPart[] = [];
52try {
53  for (let i = 0; i < partCount; i++) {
54    const start = i * PART_SIZE;
55    const part = await multipart.uploadPart(i + 1, file.slice(start, start + PART_SIZE));
56    uploadedParts.push(part);
57    onProgress?.(Math.round(((i + 1) / partCount) * 100));
58  }
59  return await multipart.complete(uploadedParts);
60} catch (error) {
61  await multipart.abort();
62  throw error;
63}
64```
65 
66## Batch Delete
67 
68```typescript
69async function deletePrefix(prefix: string, env: Env) {
70  let cursor: string | undefined;
71  let truncated = true;
72 
73  while (truncated) {
74    const listed = await env.MY_BUCKET.list({ prefix, limit: 1000, cursor });
75    if (listed.objects.length > 0) {
76      await env.MY_BUCKET.delete(listed.objects.map(o => o.key));
77    }
78    truncated = listed.truncated;
79    cursor = listed.cursor;
80  }
81}
82```
83 
84## Checksum Validation & Storage Transitions
85 
86```typescript
87// Upload with checksum
88const hash = await crypto.subtle.digest('SHA-256', data);
89await env.MY_BUCKET.put(key, data, { sha256: hash });
90 
91// Transition storage class (requires S3 SDK)
92import { S3Client, CopyObjectCommand } from '@aws-sdk/client-s3';
93await s3.send(new CopyObjectCommand({
94  Bucket: 'my-bucket', Key: key,
95  CopySource: `/my-bucket/${key}`,
96  StorageClass: 'STANDARD_IA'
97}));
98```
99 
100## Client-Side Uploads (Presigned URLs)
101 
102```typescript
103import { S3Client } from '@aws-sdk/client-s3';
104import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
105import { PutObjectCommand } from '@aws-sdk/client-s3';
106 
107// Worker: Generate presigned upload URL
108const s3 = new S3Client({
109  region: 'auto',
110  endpoint: `https://${env.ACCOUNT_ID}.r2.cloudflarestorage.com`,
111  credentials: { accessKeyId: env.R2_ACCESS_KEY_ID, secretAccessKey: env.R2_SECRET_ACCESS_KEY }
112});
113 
114const url = await getSignedUrl(s3, new PutObjectCommand({ Bucket: 'my-bucket', Key: key }), { expiresIn: 3600 });
115return Response.json({ uploadUrl: url });
116 
117// Client: Upload directly
118const { uploadUrl } = await fetch('/api/upload-url').then(r => r.json());
119await fetch(uploadUrl, { method: 'PUT', body: file });
120```
121 
122## Caching with Cache API
123 
124```typescript
125export default {
126  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
127    const cache = caches.default;
128    const url = new URL(request.url);
129    const cacheKey = new Request(url.toString(), request);
130 
131    // Check cache first
132    let response = await cache.match(cacheKey);
133    if (response) return response;
134 
135    // Fetch from R2
136    const key = url.pathname.slice(1);
137    const object = await env.MY_BUCKET.get(key);
138    if (!object) return new Response('Not found', { status: 404 });
139 
140    const headers = new Headers();
141    object.writeHttpMetadata(headers);
142    headers.set('etag', object.httpEtag);
143    headers.set('cache-control', 'public, max-age=31536000, immutable');
144 
145    response = new Response(object.body, { headers });
146 
147    // Cache for subsequent requests
148    ctx.waitUntil(cache.put(cacheKey, response.clone()));
149 
150    return response;
151  }
152};
153```
154 
155## Public Bucket with Custom Domain
156 
157```typescript
158export default {
159  async fetch(request: Request, env: Env): Promise<Response> {
160    // CORS preflight
161    if (request.method === 'OPTIONS') {
162      return new Response(null, {
163        headers: {
164          'access-control-allow-origin': '*',
165          'access-control-allow-methods': 'GET, HEAD',
166          'access-control-max-age': '86400'
167        }
168      });
169    }
170 
171    const key = new URL(request.url).pathname.slice(1);
172    if (!key) return Response.redirect('/index.html', 302);
173 
174    const object = await env.MY_BUCKET.get(key);
175    if (!object) return new Response('Not found', { status: 404 });
176 
177    const headers = new Headers();
178    object.writeHttpMetadata(headers);
179    headers.set('etag', object.httpEtag);
180    headers.set('access-control-allow-origin', '*');
181    headers.set('cache-control', 'public, max-age=31536000, immutable');
182 
183    return new Response(object.body, { headers });
184  }
185};
186```
187 
188## r2.dev Public URLs
189 
190Enable r2.dev in dashboard for simple public access: `https://pub-${hashId}.r2.dev/${key}`  
191Or add custom domain via dashboard: `https://files.example.com/${key}`
192 
193**Limitations:** No auth, bucket-level CORS, no cache override.
194