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
BucketNamealready exists in the target account and jurisdiction. - Immutable identity – Changing
CLOUDFLARE_ACCOUNT_ID,BucketName, orJurisdictionis blocked; empty the bucket and runnotation destroyor deploy to a new stage. - Override
--replace– Empty the bucket first, then runnotation planwith--replace <id> --override-loss-protection <id>to print the instance-hashednotation deploycommand.
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:
| Parameter | Description |
|---|---|
BucketName | Required immutable Input<string> unique bucket name |
Jurisdiction | Required immutable Input<Jurisdiction> storage jurisdiction |
StorageClass | Required mutable Input<StorageClass> default storage class |
LocationHint | Optional 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:
| Value | Description |
|---|---|
"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:
| Value | Description |
|---|---|
"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:
| Value | Description |
|---|---|
"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.