StorageR2

R2

Provision Cloudflare R2 object storage buckets with explicit jurisdictions and default storage classes, then bind them into Workers with typed env access.

Deploying R2 resources requires CLOUDFLARE_ACCOUNT_ID and a CLOUDFLARE_API_TOKEN with R2 edit permissions (see Cloudflare Overview). For low-latency lookups of small key-value payloads, see KV.

Using R2 in Workers

Declare a bucket with r2.R2Bucket from @notation/cloudflare/resources and return it from bindings() on $worker or worker(). WorkerHandler and WorkerEnv type the binding property as Cloudflare's R2Bucket.

Declare an R2Bucket in infra/storage.ts, then upload, serve, and delete objects through env.ASSETS inside a Worker:

import { $worker, type WorkerHandler } from "@notation/cloudflare/workers";
import { orderAssets } from "../infra/storage";

export const worker = $worker({
  id: "assets",
  compatibilityDate: "2026-10-12",
  bindings: () => ({ ASSETS: orderAssets }),
});

export default {
  async fetch(request, env) {
    const key = new URL(request.url).pathname.slice(1);
    if (!key) return new Response("Missing key", { status: 400 });

    if (request.method === "PUT") {
      await env.ASSETS.put(key, request.body);
      return Response.json({ key, stored: true }, { status: 201 });
    }

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

    const object = await env.ASSETS.get(key);
    return object ? new Response(object.body) : new Response("Not found", { status: 404 });
  },
} satisfies WorkerHandler<typeof worker>;
import { r2 } from "@notation/cloudflare/resources";

export const orderAssets = new r2.R2Bucket("order-assets", {
  config: {
    BucketName: "orders-app-prod-assets",
    Jurisdiction: "default",
    LocationHint: "enam",
    StorageClass: "Standard",
  },
});

Binding an R2Bucket compiles to a Cloudflare r2_bucket binding that ensures the bucket exists before the Worker uploads, forwarding Jurisdiction whenever it is not "default".

Storage classes

StorageClass sets the default storage class ("Standard" or "InfrequentAccess") applied to newly uploaded objects. Changing StorageClass updates the bucket in place without migrating existing objects.

Jurisdictions

Jurisdiction controls where Cloudflare stores objects and routes bucket requests ("default", "eu", "us", "fedramp", or "fedramp-high"). Because AccountId, BucketName, and Jurisdiction form the bucket's compound identity, Jurisdiction cannot change after creation.

You can also pass an optional LocationHint ("apac", "eeur", "enam", "weur", "wnam", or "oc") to suggest initial placement when creating the bucket. Cloudflare treats LocationHint as advisory, and changing or removing it later does not move or update an existing bucket.

Bucket lifecycle

Notation guards bucket identity and stored objects across creates, replacements, and deletions.

Replacement protection

R2Bucket enforces strict ownership and replacement guards during reconciliation:

  • No silent adoption – Creation fails if BucketName already exists in the target account and jurisdiction.
  • Immutable identity – Changing CLOUDFLARE_ACCOUNT_ID, BucketName, or Jurisdiction is blocked; empty the bucket and run notation destroy or deploy to a new stage.
  • Override --replace – Empty the bucket first, then run notation plan with --replace <id> --override-loss-protection <id> to print the instance-hashed notation deploy command.

Deletion

Cloudflare rejects deleting non-empty buckets, so notation destroy names the bucket, account, and jurisdiction when objects remain. Missing external buckets succeed silently.

Recovery

notation plan detects externally deleted buckets and schedules recreation. If a create request fails ambiguously, Notation probes and reconciles on the next deploy.

Reference

R2Bucket

r2.R2Bucket (cloudflare/r2/R2Bucket) from @notation/cloudflare/resources derives AccountId from CLOUDFLARE_ACCOUNT_ID and accepts four Input<...> config parameters:

ParameterDescription
BucketNameRequired immutable Input<string> unique bucket name
JurisdictionRequired immutable Input<Jurisdiction> storage jurisdiction
StorageClassRequired mutable Input<StorageClass> default storage class
LocationHintOptional creation-only Input<LocationHint> placement hint

All four parameters accept literals, OutputRef, and Derived values; CredentialRef is rejected.

Naming rules

BucketName must be 3 to 64 lowercase ASCII letters, digits, or hyphens (-), and cannot start or end with a hyphen. R2Bucket requires an explicit BucketName rather than generating a physical name, so include an app or stage qualifier when sharing an account and jurisdiction across stages.

Jurisdiction codes

Jurisdiction accepts five values:

ValueDescription
"default"Default global routing
"eu"European Union data residency
"us"United States jurisdiction
"fedramp"FedRAMP Moderate jurisdiction
"fedramp-high"FedRAMP High jurisdiction

"default" is omitted from compiled Worker r2_bucket bindings.

Location hint codes

LocationHint accepts six advisory region codes:

ValueDescription
"apac"Asia-Pacific
"eeur"Eastern Europe
"enam"Eastern North America
"weur"Western Europe
"wnam"Western North America
"oc"Oceania

Storage class values

StorageClass accepts two values:

ValueDescription
"Standard"Default storage class for frequently accessed objects
"InfrequentAccess"Lower-cost storage class for infrequently accessed objects

"Standard" is also assumed when Cloudflare omits the field on read.