Next.js boilerplate with Cloudflare R2

CORS and lifecycle rules live in the repo

• infra/r2/cors.json and infra/r2/lifecycle.json are the source of truth, applied with bun run r2:cors and bun run r2:lifecycle. Rules clicked into the Cloudflare dashboard exist in one account, are invisible in review, and are the reason "uploads work in production but not in preview" takes an afternoon to diagnose.
• Every origin that uploads must appear in AllowedOrigins: production, each preview URL you upload from, and http://localhost:3000. A missing origin fails in the browser with a message that never says CORS, and the time goes into debugging the signature instead.
• Never use "*" for AllowedOrigins on a bucket that accepts writes. A presigned URL is a bearer credential, and a wildcard lets any page a victim visits use one it managed to obtain.
• AllowedHeaders must include every header the browser sends on the PUT. The dropzone sends content-type, so content-type is listed. Add a header to the upload and add it here in the same change.
• Lifecycle rules are the only thing that cleans up abandoned data. Keep the tmp/ expiry and the incomplete-multipart abort: multipart parts are stored and billed even though the object does not exist, and nothing else ever removes them.
• Changing the bucket name means changing R2_BUCKET and re-running bun run r2:setup and bun run r2:cors. A new bucket starts with no CORS rules at all.

The region is always auto

• R2 has one global namespace and no S3-style regions. The S3Client is constructed with region: "auto", and passing a real AWS region makes the request signature fail with an error that does not mention the region.
• The endpoint is https://<R2_ACCOUNT_ID>.r2.cloudflarestorage.com, built from the account id. It is not the bucket's public URL and never appears in a browser.
• A location hint chosen when the bucket was created decides where the data first lands. It is not a region and it is not part of any URL.
• If a call fails with a signature error, check these three before anything else: region: "auto", the endpoint host, and whether the content-type on the PUT matches the one that was signed.

S3-compatible is not S3

• The common surface works with @aws-sdk/client-s3, which is why this battery uses it. The long tail does not: some checksum modes, ACLs, object lock and storage classes are unsupported or behave differently.
• Test anything beyond PutObject, GetObject, HeadObject, DeleteObject, ListObjectsV2 and the multipart commands rather than assuming it works. A parameter R2 does not implement is usually ignored rather than rejected, which is worse than an error.
• Do not set ACLs. R2 has no per-object ACLs: a bucket is private until a custom domain is attached, and that is the whole access model.
• HeadBucketCommand is the cheapest call that exercises the endpoint, the signature and the token's scope at once. That is what bun run verify uses.

Public access is DNS work, not a checkbox

• A bucket is private until you connect a custom domain or enable the r2.dev subdomain. R2_PUBLIC_BASE_URL is unset by default and publicUrl() returns null, which is correct for anything a user uploaded.
• r2.dev is rate-limited and explicitly not for production. Use a custom domain, which also puts Cloudflare's cache in front of the bucket.
• Cache headers are set at write time via CacheControl on putObject. An object written without one is served with no caching directive and every read is a paid class B operation.

Credentials

• R2_ACCOUNT_ID and R2_BUCKET are values, not secrets, but there is no reason to publish them. R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY are credentials with full read/write on the bucket and are server-side only.
• The secret is shown once at token creation. Rotating means creating a new token, deploying both halves, then deleting the old one, in that order.

A signed URL is a bearer credential

Whoever holds one can use it: no session, no cookie, no further check, from any browser, until it expires. Treat it exactly as you would treat a password you just minted.

• Every route that signs anything calls requireUploader(request) from @/lib/storage/authorize first, before it reads the body and before it touches storage. Nothing below that line may run for an anonymous or cross-origin request.
• Authentication is not authorisation. A signed-in user asking for a signed URL to someone else's key is authenticated and must still be refused. Before signing a read or a delete, call isOwnedBy(key, uploader.id) or look the row up in your database.
• Keys are derived on the server from the session: objectKey({ ownerId: uploader.id, ... }). A key taken from the request body is a request to write wherever the caller likes, and the first segment of the key is the entire ownership model.
• Keep lifetimes short. Fifteen minutes is generous for a page that renders an image; a day means the URL outlives the chat message it was pasted into. R2 caps a presigned URL at seven days and that is a limit, not a suggestion.
• Never log a signed URL, never put one in an analytics property, an error report or a support conversation, and never render one into a page that is cached. The signing response sets cache-control: no-store for that reason.
• R2 has no row level security and no equivalent. There is no second line of defence behind the check in authorize.ts: the credentials in src/lib/storage/index.ts can read, overwrite and delete every object in the bucket. Whatever that file decides is what happens.

Uploads go straight to R2, never through a route handler

• The browser uploads with the URL the server signed. A route handler that receives the file body is wrong here for four separate reasons: the platform's request body limit (a few megabytes on most serverless hosts), function time billed for the whole transfer, memory pressure from buffering, and a second full copy of every byte across the network.
• putObject() is for files your own code produces: a generated PDF, a thumbnail, an export. Never for anything a user is sending.
• Anything above roughly 100 MB wants multipart, not a single presigned PUT. A failed PUT restarts from zero.
• Progress belongs to the browser. XMLHttpRequest in <FileDropzone /> reports it; fetch still cannot.

Validate before you sign

• assertUploadable() checks the filename, the content type against the allowlist and the claimed size. Allowlist, never blocklist: a blocklist loses to the next extension somebody thinks of.
• The size the browser reports is a claim: it can request a 1 KB upload and then send 5 GB. R2 has no per-bucket file size limit to fall back on, so a short URL lifetime, a narrow content type and a lifecycle rule that expires unconfirmed objects are what actually bound the damage.
• content-type is part of the signature. A PUT that sends a different value is rejected with a signature mismatch, which is the most common cause of "my upload returns 403". The dropzone sends exactly the headers the signing response returned; keep it that way.
• SVG is deliberately absent from the allowlist. It is a document format that can execute script, and serving one from your own origin is stored XSS.

Server-only, always

• src/lib/storage/index.ts holds R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY. It must never be imported, transitively or otherwise, from a client component, and neither key ever carries a NEXT_PUBLIC_ prefix.
• Never expose a storage helper as a server action that takes a key from the caller without an ownership check. A server action is a public endpoint.
• Scope the R2 API token to one bucket with Object Read & Write. An account-wide token in a web app is a blast radius you never needed.

Reading objects

• Private by default: reads go through getSignedDownloadUrl().
• If an object is genuinely public, do not sign it at all. Serve it from publicUrl() through a custom domain, where Cloudflare's cache answers most requests and the zero egress fee does the rest. Signing a public asset defeats the cache and costs a class B operation per view.
• Never mix public and private objects in one bucket. One bucket per access model.

Deleting

• Deletes are authorised the same way as reads: prove ownership first. These credentials can delete anything in the bucket.
• Deleting the row and deleting the object are two operations that fail independently. Delete the object first, then the row: an orphaned object costs storage, an orphaned row breaks the page.
• S3-compatible deletes are idempotent, so a cleanup job may safely delete a key that has already gone.