Cloudflare R2 Object Storage

Status: Production Ready ✅ | Last Verified: 2025-12-27 | v3.0.0

Contents: Quick Start • New Features • Core R2 API • Critical Rules • Agents & Commands • References

Quick Start (5 Minutes)

1. Create R2 Bucket

bunx wrangler r2 bucket create my-bucket

Bucket naming: 3-63 chars, lowercase, numbers, hyphens only

2. Configure Binding

Add to wrangler.jsonc:

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "r2_buckets": [
    {
      "binding": "MY_BUCKET",          // env.MY_BUCKET
      "bucket_name": "my-bucket",      // Actual bucket
      "preview_bucket_name": "my-bucket-preview"  // Optional: dev bucket
    }
  ]
}

CRITICAL: binding = code access name, bucket_name = actual R2 bucket

3. Basic Upload/Download

import { Hono } from 'hono';

type Bindings = {
  MY_BUCKET: R2Bucket;
};

const app = new Hono<{ Bindings: Bindings }>();

// Upload
app.put('/upload/:filename', async (c) => {
  const filename = c.req.param('filename');
  const body = await c.req.arrayBuffer();

  const object = await c.env.MY_BUCKET.put(filename, body, {
    httpMetadata: {
      contentType: c.req.header('content-type') || 'application/octet-stream',
    },
  });

  return c.json({
    success: true,
    key: object.key,
    size: object.size,
  });
});

// Download
app.get('/download/:filename', async (c) => {
  const object = await c.env.MY_BUCKET.get(c.req.param('filename'));

  if (!object) {
    return c.json({ error: 'Not found' }, 404);
  }

  return new Response(object.body, {
    headers: {
      'Content-Type': object.httpMetadata?.contentType || 'application/octet-stream',
      'ETag': object.httpEtag,
    },
  });
});

export default app;

Load references/setup-guide.md for complete setup walkthrough.

New R2 Features (2025)

🆕 R2 SQL Integration - Query CSV/Parquet/JSON data with distributed SQL. Analytics without ETL. Load references/r2-sql-integration.md

🆕 Data Catalog (Apache Iceberg) - Table versioning, time-travel queries, schema evolution. Spark/Snowflake integration. Load references/data-catalog-iceberg.md

🆕 Event Notifications - Trigger Workers on object changes (upload/delete). Automate image processing, backups, webhooks. Load references/event-notifications.md

Advanced Features - Storage classes, bucket locks (compliance), tus resumable uploads, SSE-C encryption. Load references/advanced-features.md

Zero Trust Security - Cloudflare Access integration with SSO, MFA, identity policies, audit logging. Load references/cloudflare-access-integration.md

Performance Tuning - Caching strategies, compression, range requests, ETags, monitoring best practices. Load references/performance-optimization.md

Core R2 Workers API - Quick Reference

put() - Upload Objects

await env.MY_BUCKET.put(key, data, options?)

Upload with metadata, prevent overwrites with onlyIf. Load references/workers-api.md for complete R2PutOptions.

get() - Download Objects

const object = await env.MY_BUCKET.get(key, options?)

Returns R2ObjectBody | null. Supports range requests, conditional operations. Load references/workers-api.md for read methods (text(), json(), arrayBuffer(), blob()).

head() - Get Metadata Only

const object = await env.MY_BUCKET.head(key)

Check existence, get size, etag, metadata without downloading body. Useful for validation and caching.

delete() - Delete Objects

await env.MY_BUCKET.delete(key | keys[])  // Single or bulk (max 1000)

Bulk delete up to 1000 keys in single call. Always succeeds (idempotent).

list() - List Objects

const listed = await env.MY_BUCKET.list(options?)

Pagination with cursor, prefix filtering, delimiter for folders. Load references/workers-api.md for R2ListOptions.

createMultipartUpload() - Large Files (>100MB)

const multipart = await env.MY_BUCKET.createMultipartUpload(key, options?)

For files >100MB. Load references/common-patterns.md for complete multipart workflow with part upload and completion.

Load references/workers-api.md when: Need complete API reference, interface definitions (R2Object, R2ObjectBody, R2PutOptions, R2GetOptions), conditional operations, checksums, or advanced options.

Critical Rules

Always Do ✅

1. Set contentType on uploads - Files will download as binary otherwise
2. Use batch delete for multiple objects (up to 1000 keys)
3. Set cache headers for static assets (cacheControl)
4. Use presigned URLs for large client uploads
5. Use multipart upload for files >100MB
6. Set CORS policy before browser uploads
7. Set expiry times on presigned URLs (1-24 hours)
8. Handle errors with try/catch
9. Use head() when you only need metadata (not get())
10. Use conditional operations to prevent overwrites

Never Do ❌

1. Never expose R2 access keys in client-side code
2. Never skip contentType (files will download as binary)
3. Never delete in loops (use batch delete)
4. Never upload without error handling
5. Never skip CORS for browser uploads
6. Never use multipart for small files (<5MB overhead)
7. Never delete >1000 keys in single call (will fail)
8. Never assume uploads succeed (always check response)
9. Never skip presigned URL expiry (security risk)
10. Never hardcode bucket names (use bindings)

Top Use Cases

Use Case 1: Image/Asset Storage

app.put('/api/upload/image', async (c) => {
  const file = await c.req.parseBody();
  const image = file['image'] as File;

  await c.env.MY_BUCKET.put(`images/${image.name}`, image.stream(), {
    httpMetadata: {
      contentType: image.type,
      cacheControl: 'public, max-age=31536000, immutable',
    },
  });

  return c.json({ success: true });
});

Use Case 2: Direct Client Upload (Presigned URLs)

Generate secure upload URLs for client-side uploads. See templates/r2-presigned-urls.ts for complete implementation using aws4fetch.

Additional Patterns in References

Load references/common-patterns.md for:

• Multipart upload (files >100MB) - Complete workflow with part management
• Bulk operations - Batch delete, cleanup patterns with pagination
• Custom metadata tracking - User files, versions, approval workflows
• Versioned file storage - Version history with latest pointer pattern
• Backup & archive patterns - Automated backups with retention policies
• Thumbnail generation & caching - On-demand image processing
• Static site hosting - SPA fallback and cache strategies
• CDN with origin fallback - R2 as cache layer

Load templates/r2-multipart-upload.ts for complete multipart example.

Available Agents & Commands

Autonomous Agents

Agents handle complex multi-step workflows automatically:

• r2-setup-automator - Complete R2 setup (bucket creation → binding → TypeScript types → deployment)
• multipart-orchestrator - Large file uploads with chunking, error recovery, and progress tracking
• cors-debugger - Systematic CORS troubleshooting with configuration generation and testing
• s3-migration-planner - AWS S3 to R2 migration planning, data transfer, and cost analysis
• event-notification-setup - Event-driven workflows with Workers, Queues, and automation

Quick Commands

Fast access to common R2 operations:

• /r2-setup - Create bucket and configure binding in wrangler.jsonc
• /r2-presigned-url - Generate presigned URLs for secure client-side uploads/downloads
• /r2-cors-debug - Diagnose