Zero-egress object storage with R2

After this lesson you'll be able to create an R2 bucket, read and write objects from a Worker binding, connect to the same bucket with a stock S3 SDK, and reason about what R2 actually costs you.

R2 is Cloudflare's object storage product: buckets and keys, just like Amazon S3, for storing any blob — images, video, backups, JSON blobs, model weights, whatever doesn't fit neatly into a database row. The headline difference from S3 and every other major cloud object store is pricing structure, not features: R2 charges nothing for egress — the bandwidth cost of serving data back out to the internet or to another cloud. On S3, egress is often the line item that dwarfs storage cost once you're serving any real traffic; on R2 it's zero, by design, regardless of how much data you move out.

How it works

R2 is S3-compatible at the API level: it implements a large subset of the S3 REST API (PutObject, GetObject, HeadObject, ListObjectsV2, multipart upload operations, CopyObject, and bucket-level operations like CreateBucket/DeleteBucket). That means existing S3 SDKs — the AWS SDK for JS, boto3, etc. — work against R2 by pointing them at a different endpoint and different credentials, with no code rewrite for the common operations. Notable gaps: no ACLs, no object tagging, no versioning, and some S3 encryption modes aren't supported — check the S3 compatibility matrix before assuming a niche S3 feature works.

There are two ways to talk to a bucket:

• Workers binding — if your code runs in a Worker, bind the bucket directly in config and call methods on env.MY_BUCKET (get, put, delete, list). This path never leaves Cloudflare's network — no HTTP round trip, no S3 signing, and it's what you want for anything running inside a Worker.
• S3-compatible API — for code that runs outside Workers (a existing backend, a CI job, a desktop tool) or that already uses an S3 SDK. You authenticate with an R2-specific Access Key ID / Secret Access Key pair (not your global Cloudflare API token) against the endpoint https://<ACCOUNT_ID>.r2.cloudflarestorage.com, using region auto.

Buckets are private by default. Nothing is reachable over the public internet until you explicitly enable public access or front the bucket with a Worker or custom domain — covered in the next lesson.

Worked example

1. Create a bucket

npx wrangler r2 bucket create my-app-uploads

Bucket names: lowercase letters, numbers, and hyphens only, 3-63 characters, can't start or end with a hyphen.

2. Bind it to a Worker

// wrangler.jsonc
{
  "r2_buckets": [
    {
      "binding": "MY_BUCKET",
      "bucket_name": "my-app-uploads"
    }
  ]
}

export interface Env {
  MY_BUCKET: R2Bucket;
}

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const url = new URL(req.url);
    const key = url.pathname.slice(1); // "/avatar.png" -> "avatar.png"

    if (req.method === "PUT") {
      await env.MY_BUCKET.put(key, req.body, {
        httpMetadata: { contentType: req.headers.get("content-type") ?? undefined },
      });
      return new Response(`Stored ${key}`, { status: 201 });
    }

    if (req.method === "GET") {
      const object = await env.MY_BUCKET.get(key);
      if (object === null) return new Response("Not found", { status: 404 });

      const headers = new Headers();
      object.writeHttpMetadata(headers);
      headers.set("etag", object.httpEtag);
      return new Response(object.body, { headers });
    }

    if (req.method === "DELETE") {
      await env.MY_BUCKET.delete(key);
      return new Response(null, { status: 204 });
    }

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

3. Connect with an existing S3 SDK

First create an R2 API token (R2 dashboard → Manage API Tokens) scoped to Object Read & Write, optionally restricted to one bucket. This gives you an Access Key ID and a Secret Access Key — save the secret immediately, it isn't retrievable afterward. Then use it exactly like an S3 credential pair:

import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  region: "auto",
  endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: {
    accessKeyId: R2_ACCESS_KEY_ID,
    secretAccessKey: R2_SECRET_ACCESS_KEY,
  },
});

await s3.send(new PutObjectCommand({
  Bucket: "my-app-uploads",
  Key: "reports/2026-07.csv",
  Body: csvBuffer,
  ContentType: "text/csv",
}));

const { Body } = await s3.send(new GetObjectCommand({
  Bucket: "my-app-uploads",
  Key: "reports/2026-07.csv",
}));

This is the same @aws-sdk/client-s3 package you'd use against real S3 — only the endpoint, region, and credentials change. It's how you migrate an existing S3-backed service to R2 with minimal code churn, or run one codebase against either provider.

Pricing

Verified from the R2 pricing page at time of writing — check it directly before relying on exact figures, since pricing can change:

DeleteObject, DeleteBucket, and AbortMultipartUpload are free. Infrequent Access storage adds a per-GB retrieval fee and a 30-day minimum storage duration; Standard storage has no retrieval fee. The free tier (Standard storage only) includes 10 GB-month storage, 1 million Class A operations, 10 million Class B operations, and unlimited egress per month.

The point to internalize: egress is the one line that's always zero. Storage and operations are still metered and billed — R2 removed one specific cost, not all of them.

Use cases

• User file uploads — avatars, attachments, generated PDFs — written via a Worker binding, served back to users without per-GB egress cost.
• Static asset hosting — images, video, downloadable files for a site, especially when traffic (and therefore egress under S3 pricing) is high and unpredictable.
• Data lake storage — land raw or processed analytics data in R2 and query it from elsewhere (e.g. via R2 SQL, or export/ETL to a warehouse) without egress fees eating into the economics of moving data around.
• Backups — infrequently-written, occasionally-read archives, where Infrequent Access storage's lower per-GB storage price is a good fit as long as you accept the retrieval fee and minimum duration.
• Replacing S3 to cut egress costs — because R2 speaks the S3 API, teams migrate existing S3-backed workloads (especially ones serving lots of reads to end users or other clouds) by swapping endpoint and credentials rather than rewriting storage code.