Enable the selfhost Directus Support Cloudflare R2 for Storage
If you’re building a modern web app with Directus as your headless CMS and wondering whether you can plug in Cloudflare R2 for file storage, the short answer is: yes, but with a little setup. Let’s break it down so you know exactly what to expect and how to get it working smoothly.
What Is Cloudflare R2, and Why Should You Care?
Cloudflare R2 is an S3-compatible object storage service that lets you store large amounts of unstructured data—like images, videos, backups, or even ML datasets—without the dreaded egress fees that come with traditional cloud storage providers. That means you can serve files globally without worrying about surprise bills when your traffic spikes.
For Directus users, this is a big deal. Directus is a powerful open-source headless CMS, but it doesn’t come with built-in support for R2—yet. However, because R2 is fully S3-compatible, you can configure it as a custom storage adapter using Directus’s existing S3 driver.
How to Connect Cloudflare R2 to Directus
Here’s a step-by-step guide to get your Directus instance storing files in R2:
1. Create Your R2 Bucket
Head over to your Cloudflare dashboard, navigate to the R2 section, and create a new bucket. You’ll also need to generate an API token with the right permissions to read and write to that bucket.
2. Configure Directus to Use R2
In your Directus environment file (usually .env or docker-compose.yml), set the following variables:
STORAGE_LOCATIONS="s3"
STORAGE_S3_DRIVER="s3"
STORAGE_S3_KEY="your-access-key-id"
STORAGE_S3_SECRET="your-secret-access-key"
STORAGE_S3_BUCKET="your-bucket-name"
STORAGE_S3_ENDPOINT="https://your-account-id.r2.cloudflarestorage.com"
STORAGE_S3_REGION="auto"
Make sure the endpoint matches your R2 account URL. You can find this in your Cloudflare R2 dashboard.
3. Test the Integration
Upload a file through the Directus admin panel. If everything’s configured correctly, your file should now be stored in your R2 bucket and served via Cloudflare’s global CDN.
Common Pitfalls and Fixes
Some users have reported issues where R2 doesn’t seem to work even after configuration. This usually boils down to:
Incorrect endpoint format: Make sure you’re using the full R2 endpoint, not just a generic S3 URL.
Missing region: Even though R2 doesn’t use traditional regions, setting it to
"auto"is required for compatibility.Permissions: Double-check that your API token has the correct permissions to access the bucket.
If you’re still stuck, the Directus GitHub community is active, and issues like #23733 have been resolved with community help.
Why Use R2 with Directus?
Here’s why this combo is a match made in developer heaven:
| Feature | Benefit |
| No egress fees | Save money when serving files globally |
| S3 compatibility | Use existing S3 tools and libraries |
| Global CDN | Fast file delivery via Cloudflare’s edge network |
| Scalability | Handle large media libraries or data lakes with ease |
Final Thoughts
While Directus doesn’t have a native R2 adapter (yet), its S3 compatibility makes integration straightforward. Once configured, you’ll enjoy cost-effective, scalable, and fast file storage—perfect for content-heavy apps, media libraries, or even AI/ML workflows.
So go ahead, plug in R2, and let your Directus-powered app scale without the storage bill shock.
Author Opinion
As someone who’s worked with both Directus and Cloudflare R2, I can say this combo is a game-changer for developers who want performance without vendor lock-in. The setup is a bit manual, but once it’s running, it’s rock-solid. I’d love to see Directus officially support R2 in the future, but for now, the S3 workaround does the job beautifully.
Author: Erik Chen
