Binding reference Bindings

Use R2 for object storage, but route browser delivery on purpose

R2 is straightforward in config and well-supported locally, but browser-facing delivery should usually go through a Worker route instead of assuming bucket URLs.

Devflare treats R2 as a first-class binding in worker code and tests. The main discipline is deciding which files are public, which are private, and which paths should stay app-controlled.

Config key: bindings.r2
Authoring shape: Record<string, string>
Best for: Files, uploads, generated assets, and private object delivery through a Worker

Author it in the simplest shape that still says what you mean

R2 is the least ambiguous storage binding to author: you bind a name in env to a bucket name in config.

The real architectural choice is not the config key. It is whether the browser talks to a public bucket, a signed upload path, or a worker-controlled route that checks auth first.

R2 binding authoring

import { defineConfig } from 'devflare/config'

export default defineConfig({

name: 'r2-worker',

bindings: {

r2: {

ASSETS: 'assets-bucket',

PRIVATE_FILES: 'private-files-bucket'

}

})

When this binding fits best

Use R2 for large objects, uploads, or file delivery that does not belong in D1 or KV.
Keep private file delivery in a Worker route so auth and response headers stay under your control.
If the browser needs a direct public asset origin, use a public bucket on a custom domain on purpose rather than by accident.

Notes worth keeping visible

Do not assume local bucket URLs are a public contract your app can safely depend on.
Use after binding changes so bucket names show up correctly in .
Preview-scoped buckets are useful, but they should still be cleaned up intentionally when previews expire.

The browser-delivery rule

If the browser needs the file in local dev, route through your worker unless you intentionally chose a public bucket contract.

Cloudflare docs vs the Devflare layer

Cloudflare R2 docs is the platform reference. This page is the Devflare translation layer: keep readable in source, understand the typed env surface, and know which local, preview, or remote lane actually matches the binding.

Reference

Cloudflare R2 docs

Cloudflare Docs

Platform reference for buckets, object APIs, public-versus-private delivery, and account features.

Question	Cloudflare docs	This Devflare page
Primary focus	Platform reference for buckets, object APIs, public-versus-private delivery, and account features.	How to author , what the runtime surface looks like, and how R2 fits a Devflare project.
Testing and runtime lens	Cloudflare’s docs focus on the raw binding API, product semantics, and platform limits for the binding itself.	First-class local runtime and tests. Use the Devflare guidance when you need the honest local harness or the right remote gate instead of only the product API shape.
When to open it	When you need the platform contract, limits, APIs, or account-level product details.	When you are wiring, testing, previewing, or reviewing the binding inside a Devflare app.

Go deeper only if this one-page guide stops being enough

Subpage

R2 internals

Internals

See normalization, Wrangler , and the preview or runtime details behind the authored shape.

Subpage

Testing R2

Testing

Start from with or and only escalate when the binding or deployment model genuinely needs it.

Subpage

R2 example

Example

Adapt one small end-to-end path before you hide the binding behind a bigger abstraction.