Skip to main content Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/secondsky/claude-skills --skill cloudflare-r2The command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository
Related occupations SOC
Based on SOC occupation classification
name cloudflare-r2 description Cloudflare R2 S3-compatible object storage. Use for buckets, uploads, CORS, presigned URLs, or encountering R2_ERROR, CORS failures, multipart issues. license MIT metadata {"version":"3.0.0","last_verified":"2025-12-27","production_tested":true,"token_savings":"~65%","errors_prevented":12,"templates_included":5,"references_included":11,"agents_included":5,"commands_included":4,"scripts_included":3,"wrangler_version":"4.81.0","workers_types_version":"4.20260408.0","aws4fetch_version":"1.0.20","keywords":["r2","r2 storage","cloudflare r2","r2 bucket","r2 upload","r2 download","r2 binding","object storage","s3 compatible","r2 cors","presigned urls","multipart upload","r2 api","r2 workers","file upload","asset storage","R2_ERROR","R2Bucket","r2 metadata","custom metadata","http metadata","content-type","cache-control","aws4fetch","s3 client","bulk delete","r2 list","storage class"]}
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 {
"name" : "my-worker" ,
"main" : "src/index.ts" ,
"compatibility_date" : "2025-10-11" ,
"r2_buckets" : [
{
"binding" : "MY_BUCKET" ,
"bucket_name" : "my-bucket" ,
"preview_bucket_name" : "my-bucket-preview"
}
]
}
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 }>();
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 ,
});
});
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[])
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 ✅
Set contentType on uploads - Files will download as binary otherwiseUse batch delete for multiple objects (up to 1000 keys)Set cache headers for static assets (cacheControl)Use presigned URLs for large client uploadsUse multipart upload for files >100MBSet CORS policy before browser uploadsSet expiry times on presigned URLs (1-24 hours)Handle errors with try/catchUse head() when you only need metadata (not get())Use conditional operations to prevent overwrites
Never Do ❌
Never expose R2 access keys in client-side codeNever skip contentType (files will download as binary)Never delete in loops (use batch delete)Never upload without error handling Never skip CORS for browser uploadsNever use multipart for small files (<5MB overhead)Never delete >1000 keys in single call (will fail)Never assume uploads succeed (always check response)Never skip presigned URL expiry (security risk)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 trackingcors-debugger - Systematic CORS troubleshooting with configuration generation and testings3-migration-planner - AWS S3 to R2 migration planning, data transfer, and cost analysisevent-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 and fix CORS configuration issues/r2-multipart-init - Initialize multipart upload workflow for large files
When to Load References
Core References (Existing Features) references/setup-guide.md
references/workers-api.md
references/common-patterns.md
references/s3-compatibility.md
references/cors-configuration.md
New Features References (2025) references/event-notifications.md
references/advanced-features.md
references/r2-sql-integration.md
references/data-catalog-iceberg.md
references/cloudflare-access-integration.md
references/performance-optimization.md
Using Bundled Resources
References (references/)
setup-guide.md - Complete setup walkthrough (bucket creation → deployment)workers-api.md - Complete Workers API reference (all methods + options)common-patterns.md - Advanced patterns (multipart, retry, batch, performance)s3-compatibility.md - S3 compatibility guide (migration, aws4fetch, S3 clients)cors-configuration.md - CORS setup guide (Dashboard, scenarios, troubleshooting, security)
Templates (templates/)
r2-simple-upload.ts - Basic upload/download Workerr2-multipart-upload.ts - Complete multipart upload implementationr2-presigned-urls.ts - Presigned URL generation (upload + download)r2-cors-config.json - CORS configuration exampleswrangler-r2-config.jsonc - Complete wrangler.jsonc with R2 binding
CORS Configuration Configure CORS for browser uploads/downloads. Load references/cors-configuration.md for complete guide including Dashboard setup, common scenarios, troubleshooting, and security best practices.
Error Handling try {
await env.MY_BUCKET .put (key, data);
} catch (error : any ) {
const message = error.message ;
if (message.includes ('R2_ERROR' )) {
} else if (message.includes ('exceeded' )) {
} else if (message.includes ('precondition' )) {
}
console .error ('R2 Error:' , message);
return c.json ({ error : 'Storage operation failed' }, 500 );
}
Load references/common-patterns.md for retry logic with exponential backoff, circuit breaker patterns, and advanced error recovery.
Known Issues Prevented Issue Description Solution CORS errors Browser can't upload/download Configure CORS in bucket settings Files download as binary Missing content-type Always set httpMetadata.contentType Presigned URL security URLs never expire Always set X-Amz-Expires (1-24 hours) Multipart limits Parts >100MB or >10,000 parts Keep parts 5MB-100MB, max 10,000 Bulk delete limits >1000 keys fails Chunk deletes into batches of 1000 Metadata overflow >2KB custom metadata Keep total under 2KB
Wrangler Commands
wrangler r2 bucket create <BUCKET_NAME>
wrangler r2 bucket list
wrangler r2 bucket delete <BUCKET_NAME>
wrangler r2 object put <BUCKET>/<KEY> --file=<PATH>
wrangler r2 object get <BUCKET>/<KEY> --file=<OUTPUT>
wrangler r2 object delete <BUCKET>/<KEY>
wrangler r2 object list <BUCKET>
wrangler r2 object list <BUCKET> --prefix="folder/"
Official Documentation
Check references/setup-guide.md for setup walkthrough
Review references/workers-api.md for API reference
See references/common-patterns.md for advanced patterns
Load templates/ for working code examples
