uploads-on-r2 is a Cloudflare Worker for WordPress operators who want media served from an R2 bucket without changing any URL. It answers /wp-content/uploads/ requests from the bucket and falls back to the origin when a file is not there yet. The code is at https://github.com/IndianOpinion/uploads-on-r2, under the MIT licence. Version v0.1.0 was released on 14 November 2026.
A WordPress site keeps uploads on the origin’s disk. Every cache miss for a media file costs the origin a request, the disk is the only copy that serves, and when the origin is slow or down every image breaks with it. Moving files to an object store fixes storage, but themes, feeds and years of published HTML all point at the same URLs. Rewriting them is slow, risky and never complete.
The Worker sits on the uploads path of the zone and serves those same URLs from the bucket. The worst case, a missing object or a Worker error, is the site you had before.
The main lesson shaped the design. A Worker in front of the origin bypasses the web server’s own deny rules. A naive version that serves anything in the bucket will serve private upload folders, such as WordPress personal-data exports and plugin logs, to the public. This version denies private folders on the decoded key and reads only media extensions.
GET and HEAD for media extensions from R2 on unchanged URLs, with content type, ETag, Last-Modified, conditional requests (304, 412) and single byte ranges (206, 416).x-uploads-source header: r2, edge-cache, origin, origin-error, deny or negative-cache.scripts/sync-uploads.sh, a copy-only rclone wrapper that fills the bucket.The code is strict TypeScript with no runtime dependencies. src/handler.ts holds the request pipeline and takes its origin fetch and cache as injected dependencies. The pure parts live apart: key.ts (path to key, deny list), http.ts (dates, ETags, preconditions, ranges), content-type.ts, stream.ts and config.ts.
Every request goes through fixed steps:
. or .. segments give 404.no-store 404. R2, the cache and the origin are never asked.GET and HEAD of a media extension go further.A short negative cache holds repeated origin 404s for 60 seconds by default. R2 is still read first, so a file synced a second later is served at once. Ranges on an edge-cache hit are cut locally with a stream slicer, not by relying on the Cache API.
The sync script copies and never deletes:
scripts/sync-uploads.sh \
--source /var/www/example.com/wp-content/uploads \
--remote r2:your-bucket \
--rclone /usr/local/bin/rclone \
--max-age 30m
Check which path answered:
curl -sI https://example.com/wp-content/uploads/2026/01/photo.jpg | grep -i x-uploads-source
wp-personal-data-exports/, wc-logs/, woocommerce_uploads/ and wpcf7_uploads/. They also apply under a multisite sites/<n>/ folder. EXTRA_DENY_PREFIXES adds more..php.jpg goes out with an image content type and nosniff.EDGE_CACHE_MAX_BYTES is clamped to 64 MiB.type/subtype with no comma list, of the same kind as the extension.EDGE_CACHE_MAX_BYTES became a ceiling, not just a default, because the cache write can buffer a whole object for a slow client.--source starting with a hyphen is now prefixed so rclone never reads it as a flag.Location header through unchanged. With ORIGIN_OVERRIDE set, a redirect would name the override host. That variable is for testing only.Test status: this is v0.1.0, tested on stubs and an in-memory bucket. 100 Vitest tests run inside the Workers runtime with an in-memory R2 bucket, and 8 bats tests cover the sync script. TypeScript, eslint and prettier are clean, and wrangler deploy --dry-run passes. CI has not yet run on GitHub, and the Worker has not been deployed to a live zone from this repo.
You need a Cloudflare account that holds both the zone and an R2 bucket, Node 22.12 or later, and Wrangler (a dev dependency). The package is not published to npm.
git clone https://github.com/IndianOpinion/uploads-on-r2.git
cd uploads-on-r2
npm ci
npm run build
npx wrangler deploy
Before deploying, copy your uploads into the bucket, and edit wrangler.toml to replace your-worker, example.com and your-bucket. Keep the route on the uploads path, not the whole zone.