Help us improve
Share bugs, ideas, or general feedback.
From cloudflare-r2
Manages Cloudflare R2 S3-compatible object storage in Workers: bucket creation, bindings, uploads/downloads, CORS, presigned URLs, multipart uploads. Fixes R2_ERROR and CORS issues.
npx claudepluginhub secondsky/claude-skills --plugin cloudflare-r2How this skill is triggered — by the user, by Claude, or both
Slash command
/cloudflare-r2:cloudflare-r2The summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Status**: Production Ready ✅ | **Last Verified**: 2025-12-27 | **v3.0.0**
references/advanced-features.mdreferences/cloudflare-access-integration.mdreferences/common-patterns.mdreferences/cors-configuration.mdreferences/data-catalog-iceberg.mdreferences/event-notifications.mdreferences/performance-optimization.mdreferences/r2-sql-integration.mdreferences/s3-compatibility.mdreferences/setup-guide.mdreferences/workers-api.mdtemplates/r2-cors-config.jsontemplates/r2-multipart-upload.tstemplates/r2-presigned-urls.tstemplates/r2-simple-upload.tstemplates/wrangler-r2-config.jsoncCloudflare Workers + Wrangler operations: bindings, local dev, secrets, deploy/CI, Workers-vs-Pages decisions, and observability. Covers KV, D1, R2, Durable Objects, Queues, Hyperdrive, Workers AI, Vectorize, and wrangler.jsonc/toml config.
Deploys and manages Cloudflare Workers, KV Storage, R2 buckets, Pages projects, DNS records, and routes via API. Validates credentials and extracts deployment URLs for service setup.
Manages Cloudflare Workers and related resources via the Wrangler CLI. Use for deploying, developing KV, R2, D1, Vectorize, Queues, and more.
Share bugs, ideas, or general feedback.
Status: Production Ready ✅ | Last Verified: 2025-12-27 | v3.0.0
Contents: Quick Start • New Features • Core R2 API • Critical Rules • Agents & Commands • References
bunx wrangler r2 bucket create my-bucket
Bucket naming: 3-63 chars, lowercase, numbers, hyphens only
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
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.
🆕 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
await env.MY_BUCKET.put(key, data, options?)
Upload with metadata, prevent overwrites with onlyIf. Load references/workers-api.md for complete R2PutOptions.
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()).
const object = await env.MY_BUCKET.head(key)
Check existence, get size, etag, metadata without downloading body. Useful for validation and caching.
await env.MY_BUCKET.delete(key | keys[]) // Single or bulk (max 1000)
Bulk delete up to 1000 keys in single call. Always succeeds (idempotent).
const listed = await env.MY_BUCKET.list(options?)
Pagination with cursor, prefix filtering, delimiter for folders. Load references/workers-api.md for R2ListOptions.
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.
cacheControl)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 });
});
Generate secure upload URLs for client-side uploads. See templates/r2-presigned-urls.ts for complete implementation using aws4fetch.
Load references/common-patterns.md for:
Load templates/r2-multipart-upload.ts for complete multipart example.
Agents handle complex multi-step workflows automatically:
Fast access to common R2 operations:
references/setup-guide.md - First-time setup, binding configuration, TypeScript types, deployment walkthrough
references/workers-api.md - Complete API reference (all methods + options), conditional operations, checksums
references/common-patterns.md - Multipart uploads, retry logic with backoff, batch operations, cache strategies
references/s3-compatibility.md - S3 migration guide, S3 client library usage, aws4fetch presigned URL signing
references/cors-configuration.md - Browser access setup, CORS debugging, security policies, Dashboard configuration
references/event-notifications.md - Event-driven automation, Queue integration, image processing, webhook triggers
references/advanced-features.md - Storage classes (cost optimization), bucket locks (compliance), tus resumable uploads, SSE-C encryption
references/r2-sql-integration.md - SQL queries on R2 data (CSV/Parquet/JSON), analytics patterns, performance tuning
references/data-catalog-iceberg.md - Apache Iceberg tables, time-travel queries, schema evolution, Spark/Snowflake integration
references/cloudflare-access-integration.md - Zero Trust security, SSO (Google/Okta/Azure AD), identity policies, MFA, audit logging
references/performance-optimization.md - Caching (browser/CDN/Workers), compression (gzip/Brotli), range requests, ETags, monitoring
Configure CORS for browser uploads/downloads. Load references/cors-configuration.md for complete guide including Dashboard setup, common scenarios, troubleshooting, and security best practices.
try {
await env.MY_BUCKET.put(key, data);
} catch (error: any) {
const message = error.message;
if (message.includes('R2_ERROR')) {
// Generic R2 error
} else if (message.includes('exceeded')) {
// Quota exceeded
} else if (message.includes('precondition')) {
// Conditional operation failed (onlyIf)
}
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.
| 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 |
# Bucket management
wrangler r2 bucket create <BUCKET_NAME>
wrangler r2 bucket list
wrangler r2 bucket delete <BUCKET_NAME>
# Object management
wrangler r2 object put <BUCKET>/<KEY> --file=<PATH>
wrangler r2 object get <BUCKET>/<KEY> --file=<OUTPUT>
wrangler r2 object delete <BUCKET>/<KEY>
# List objects
wrangler r2 object list <BUCKET>
wrangler r2 object list <BUCKET> --prefix="folder/"
Questions? Issues?
references/setup-guide.md for setup walkthroughreferences/workers-api.md for API referencereferences/common-patterns.md for advanced patternstemplates/ for working code examples