r2-storage

R2 Object Storage

Store and retrieve objects at scale using Cloudflare's S3-compatible object storage.

When to Use

• File uploads (images, videos, documents)
• AI assets and model artifacts
• Image and media asset storage
• Structured data (JSON, CSV, logs)
• User-facing uploads and downloads
• Static asset hosting
• Backup and archival storage
• S3-compatible workflows with existing tools

FIRST: Create R2 Bucket

# Create bucket
wrangler r2 bucket create my-bucket

# Create with location hint
wrangler r2 bucket create my-bucket --location wnam

# List buckets
wrangler r2 bucket list

Quick Reference

Operation	API
Upload object	await bucket.put(key, data, { httpMetadata })
Download object	const obj = await bucket.get(key); const data = await obj.text()
Delete object	await bucket.delete(key)
List objects	const list = await bucket.list({ prefix, limit })
Get metadata	const obj = await bucket.head(key)
Multipart upload	const upload = await bucket.createMultipartUpload(key)
Generate signed URL	Use presigned URL patterns with R2's S3 compatibility

Wrangler Configuration

// wrangler.jsonc
{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "r2_buckets": [
    {
      "binding": "BUCKET",
      "bucket_name": "my-bucket"
    }
  ]
}

TypeScript Types (run wrangler types to generate):

export interface Env {
  BUCKET: R2Bucket;
}

Basic Upload and Download

import { R2Bucket } from "@cloudflare/workers-types";

export interface Env {
  BUCKET: R2Bucket;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const key = url.pathname.slice(1); // Remove leading /

    // Upload
    if (request.method === "PUT") {
      await env.BUCKET.put(key, request.body, {
        httpMetadata: {
          contentType: request.headers.get("content-type") || "application/octet-stream",
        },
      });
      return new Response("Uploaded", { status: 201 });
    }

    // Download
    if (request.method === "GET") {
      const object = await env.BUCKET.get(key);
      
      if (!object) {
        return new Response("Not found", { status: 404 });
      }

      return new Response(object.body, {
        headers: {
          "Content-Type": object.httpMetadata?.contentType || "application/octet-stream",
          "ETag": object.httpEtag,
          "Cache-Control": object.httpMetadata?.cacheControl || "public, max-age=3600",
        },
      });
    }

    // Delete
    if (request.method === "DELETE") {
      await env.BUCKET.delete(key);
      return new Response("Deleted", { status: 204 });
    }

    return new Response("Method not allowed", { status: 405 });
  },
};