R2Bucket

API reference for Cloudflare R2 Bucket resource

R2Bucket

Creates and manages Cloudflare R2 Buckets for object storage with S3-compatible API.

Props

name · string

Name of the bucket. Names can only contain lowercase letters (a-z), numbers (0-9), and hyphens (-).

Hide default

${app}-${stage}-${id}

locationHint · string

Optional location hint for the bucket. Indicates the primary geographical location data will be accessed from.

storageClass · Standard | InfrequentAccess

Optional storage class for the bucket.

jurisdiction · default | eu | fedramp

Optional jurisdiction for the bucket. Determines the regulatory jurisdiction the bucket data falls under.

devDomain · boolean · default: "false"

Whether to allow public access through the r2.dev subdomain. Only for development purposes - use custom domains for production.

domains · string | R2BucketCustomDomainOptions | (string | R2BucketCustomDomainOptions)[]

The custom domain(s) to attach to the bucket.

delete · boolean · default: "true"

Whether to delete the bucket when the resource is removed from Alchemy.

empty · boolean · default: "false"

Whether to empty the bucket and delete all objects during resource deletion.

adopt · boolean · default: "false"

Whether to adopt an existing bucket with the same name if it exists.

cors · R2BucketCORSRule[]

CORS rules for the bucket.

Show properties

allowed · object · required

Show properties

methods · string[] · required

HTTP methods allowed. Options: GET, PUT, POST, DELETE, HEAD

origins · string[] · required

Allowed origins for CORS requests.

headers · string[]

Allowed headers for CORS requests.

exposeHeaders · string[]

Headers that can be exposed back to the client.

maxAgeSeconds · number

Amount of time browsers are allowed to cache CORS preflight responses (in seconds).

lifecycle · R2BucketLifecycleRule[]

Lifecycle rules for the bucket.

Show properties

id · string

Unique identifier for this rule.

enabled · boolean · default: "true"

Whether or not this rule is in effect.

conditions · object

Show properties

prefix · string · required

Transitions will only apply to objects/uploads that start with the given prefix.

deleteObjectsTransition · object

Transition to delete objects.

Show properties

condition · object · required

Age or date-based condition for deletion.

storageClassTransitions · object[]

Transitions to change the storage class of objects.

dataCatalog · boolean

Enable data catalog for bucket.

Output

name · string

The name of the bucket.

location · string

Location of the bucket.

creationDate · Date

Time at which the bucket was created.

devDomain · string

The r2.dev subdomain for the bucket, if devDomain is true.

domains · string[]

The custom domains for the bucket, if applicable.

type · r2_bucket

Type identifier for the binding.

Examples

Basic R2 Bucket

const bucket = await R2Bucket("storage", {
  name: "my-app-data"
});

Bucket with Location Hint

const euBucket = await R2Bucket("eu-data", {
  name: "eu-user-data",
  locationHint: "eu",
  jurisdiction: "eu"
});

Bucket with Public Access

const publicBucket = await R2Bucket("public-assets", {
  name: "public-assets",
  devDomain: true
});

Bucket with CORS

const bucket = await R2Bucket("api-storage", {
  cors: [{
    allowed: {
      methods: ["GET", "PUT"],
      origins: ["https://example.com"],
      headers: ["Content-Type"]
    },
    exposeHeaders: ["ETag"],
    maxAgeSeconds: 3600
  }]
});

Bucket with Lifecycle Rules

const bucket = await R2Bucket("logs", {
  lifecycle: [{
    id: "delete-old-logs",
    enabled: true,
    conditions: { prefix: "logs/" },
    deleteObjectsTransition: {
      condition: { maxAge: 2592000, type: "Age" }
    }
  }]
});

Auto-Empty on Deletion

const tempBucket = await R2Bucket("temp-storage", {
  name: "temp-storage",
  empty: true
});