Cloudflare R2 Storage

Dyeink uses Cloudflare R2 for storing images, media files, and other user-uploaded content. R2 is S3-compatible and includes free egress, making it cost-effective for serving blog assets.

Prerequisites

A Cloudflare account (sign up at cloudflare.com)
Access to Cloudflare dashboard with billing configured
R2 subscription enabled (includes generous free tier)

Enable R2 in Cloudflare

Subscribe to R2

Log in to your Cloudflare dashboard
Navigate to R2 from the sidebar
Click Purchase R2 Plan if not already enabled
Review pricing and click Proceed

R2 includes 10 GB storage and 1 million Class A operations free per month. Perfect for getting started.

Note your Account ID

Your Account ID is displayed in the R2 overview page and in your URL:

https://dash.cloudflare.com/<ACCOUNT_ID>/r2

Copy and save this Account ID for your environment configuration.

Create R2 Bucket

Create a new bucket

In the R2 dashboard, click Create bucket
Choose a unique bucket name:
- Development: dyeink-dev-uploads
- Production: dyeink-uploads or dyeink-images
Select a location hint (choose closest to your users)
Click Create bucket

Bucket names must be globally unique across all Cloudflare R2 buckets and follow DNS naming conventions.

Configure bucket settings

Click on your newly created bucket
Review the Settings tab:
- Storage class: Standard (default)
- Object lifecycle rules: Optional, configure if needed

Configure Public Access

Enable public access (optional)

For serving public images and assets:

In your bucket, navigate to Settings > Public access
Click Allow Access
You’ll receive a public bucket URL:

https://pub-<random-id>.r2.dev

Public buckets allow anyone to read objects. Only enable for publicly accessible content like blog images.

Custom domain (recommended)

For a branded URL like cdn.yourblog.com:

In bucket settings, go to Settings > Custom Domains
Click Connect Domain
Enter your custom domain (e.g., cdn.yourblog.com)
Follow the DNS configuration instructions
Add the provided CNAME record to your domain’s DNS:

Type: CNAME
Name: cdn
Content: <bucket-id>.r2.cloudflarestorage.com

Click Continue and wait for DNS propagation

Custom domains provide better branding and allow you to change storage providers without breaking image URLs.

Generate API Credentials

Create R2 API token

Navigate to R2 > Overview
Click Manage R2 API Tokens on the right sidebar
Click Create API token
Configure the token:
- Token name: Dyeink Production (or appropriate name)
- Permissions:
  - Select Object Read & Write
- TTL: Leave as “Forever” or set expiration
- Bucket scope: Select specific buckets or all buckets
Click Create API Token

Save credentials

You’ll see three important values:

Access Key ID: <20-character key>
Secret Access Key: <40-character secret>
Endpoint: https://<account-id>.r2.cloudflarestorage.com

The Secret Access Key is only shown once. Save it immediately in a secure location.

Copy these values for your environment configuration.

Environment Configuration

Backend (backend/.env)

# Cloudflare R2 Storage
R2_ACCOUNT_ID=your-cloudflare-account-id
R2_ACCESS_KEY_ID=your-r2-access-key-id
R2_SECRET_ACCESS_KEY=your-r2-secret-access-key
R2_BUCKET_NAME=dyeink-images
R2_PUBLIC_URL=https://your-r2-bucket.r2.dev

Root (.env)

# Cloudflare R2 Storage
R2_ACCOUNT_ID=your-cloudflare-account-id
R2_ACCESS_KEY_ID=your-r2-access-key-id
R2_SECRET_ACCESS_KEY=your-r2-secret-access-key
R2_BUCKET_NAME=dyeink-uploads
R2_PUBLIC_URL=https://pub-xxxx.r2.dev

Never commit R2 credentials to version control. Use environment variables or secrets management.

S3-Compatible Client Setup

R2 is S3-compatible, so you can use standard S3 client libraries.

AWS SDK v3 (Node.js)
AWS SDK v2 (Node.js)

import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';

const s3Client = new S3Client({
  region: 'auto',
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: {
    accessKeyId: process.env.R2_ACCESS_KEY_ID,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
  },
});

// Upload a file
async function uploadFile(key, body, contentType) {
  const command = new PutObjectCommand({
    Bucket: process.env.R2_BUCKET_NAME,
    Key: key,
    Body: body,
    ContentType: contentType,
  });

  await s3Client.send(command);
  return `${process.env.R2_PUBLIC_URL}/${key}`;
}

const AWS = require('aws-sdk');

const s3 = new AWS.S3({
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  accessKeyId: process.env.R2_ACCESS_KEY_ID,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
  signatureVersion: 'v4',
});

// Upload a file
function uploadFile(key, body, contentType) {
  return s3.upload({
    Bucket: process.env.R2_BUCKET_NAME,
    Key: key,
    Body: body,
    ContentType: contentType,
  }).promise();
}

Configure CORS

If your frontend needs direct access to R2, configure CORS settings.

Set CORS policy

Navigate to your bucket in the R2 dashboard
Go to Settings > CORS policy
Add a CORS rule:

[
  {
    "AllowedOrigins": [
      "http://localhost:5173",
      "https://yourdomain.com"
    ],
    "AllowedMethods": [
      "GET",
      "PUT",
      "POST",
      "DELETE"
    ],
    "AllowedHeaders": [
      "*"
    ],
    "ExposeHeaders": [
      "ETag"
    ],
    "MaxAgeSeconds": 3600
  }
]

Click Save

Test CORS

Make a request from your frontend to verify CORS is working:

fetch('https://your-bucket.r2.dev/test.jpg', {
  method: 'GET',
})
  .then(response => console.log('CORS working!', response))
  .catch(error => console.error('CORS error:', error));

CDN and Caching

R2 integrates seamlessly with Cloudflare’s CDN for optimal performance.

Enable Cloudflare CDN

If using a custom domain:

Ensure your domain is proxied through Cloudflare (orange cloud icon)
Cloudflare will automatically cache static assets
Configure cache rules in Caching > Configuration

Set cache headers

Configure appropriate cache headers when uploading:

const command = new PutObjectCommand({
  Bucket: process.env.R2_BUCKET_NAME,
  Key: key,
  Body: body,
  ContentType: contentType,
  CacheControl: 'public, max-age=31536000, immutable', // 1 year
});

Use versioned filenames (e.g., image-v2.jpg) with long cache times for better performance.

Purge cache when needed

Use Cloudflare’s API or dashboard to purge cached files:

Navigate to Caching > Configuration
Click Purge Everything or Custom Purge
Enter specific URLs to purge

Verification

Test upload

Create a test script to upload a file:

test-r2.js

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';

const s3Client = new S3Client({
  region: 'auto',
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: {
    accessKeyId: process.env.R2_ACCESS_KEY_ID,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
  },
});

async function testUpload() {
  try {
    const command = new PutObjectCommand({
      Bucket: process.env.R2_BUCKET_NAME,
      Key: 'test.txt',
      Body: 'Hello, R2!',
      ContentType: 'text/plain',
    });

    await s3Client.send(command);
    console.log('✓ Upload successful!');
    console.log(`URL: ${process.env.R2_PUBLIC_URL}/test.txt`);
  } catch (error) {
    console.error('✗ Upload failed:', error.message);
  }
}

testUpload();

Run it:

node test-r2.js

Verify in dashboard

Navigate to your bucket in R2 dashboard
You should see test.txt in the object list
Click on it to view details and download

Test public access

Visit the public URL in your browser:

https://your-bucket.r2.dev/test.txt

You should see “Hello, R2!” displayed.

Best Practices

Use unique, versioned filenames to avoid cache issues
Implement image optimization before uploading (resize, compress)
Store original files separately from optimized versions
Use appropriate content types for all uploads
Implement file size limits to prevent abuse
Generate thumbnails and multiple sizes for responsive images
Use signed URLs for private content

Example: Image Upload with Optimization

import sharp from 'sharp';
import { nanoid } from 'nanoid';

async function uploadImage(file) {
  // Generate unique filename
  const filename = `${nanoid()}.webp`;

  // Optimize image
  const optimized = await sharp(file.buffer)
    .resize(1200, 1200, { fit: 'inside', withoutEnlargement: true })
    .webp({ quality: 80 })
    .toBuffer();

  // Upload to R2
  const command = new PutObjectCommand({
    Bucket: process.env.R2_BUCKET_NAME,
    Key: `images/${filename}`,
    Body: optimized,
    ContentType: 'image/webp',
    CacheControl: 'public, max-age=31536000, immutable',
  });

  await s3Client.send(command);

  return `${process.env.R2_PUBLIC_URL}/images/${filename}`;
}

Troubleshooting

403 Forbidden errors

Verify R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY are correct
Check that the API token has appropriate permissions
Ensure the bucket name matches exactly
Verify the token hasn’t expired

CORS errors

Verify CORS policy is configured in bucket settings
Check that AllowedOrigins matches your frontend domain exactly
Ensure AllowedMethods includes the HTTP method you’re using
Clear browser cache and try again

Public URL returns 404

Verify public access is enabled for the bucket
Check that the object key (filename) is correct
Ensure the file was uploaded successfully (check R2 dashboard)
Wait a few minutes for DNS propagation if using custom domain

Slow upload/download speeds

Check your network connection
Verify you’re using the correct region endpoint
Consider using Cloudflare’s CDN with a custom domain
Implement multipart uploads for large files

Cost Optimization

R2 pricing (as of 2026):

Storage: $0.015/GB/month (first 10 GB free)
Class A operations (writes): $4.50/million (first 1M free)
Class B operations (reads): $0.36/million (first 10M free)
Egress: FREE (no bandwidth charges)

Delete unused files and old versions regularly
Implement lifecycle policies to automatically delete temporary files
Use image optimization to reduce storage costs
Monitor usage in Cloudflare Analytics
Consider implementing a file retention policy

Security Best Practices

Never expose R2 credentials in frontend code
Use signed URLs for private content instead of public buckets
Rotate API tokens regularly
Implement file type validation before upload
Scan uploaded files for malware
Set up rate limiting for upload endpoints
Use separate buckets for development and production
Monitor access logs for suspicious activity

Get Started

Core Features

Configuration

Cloudflare R2 Storage

Prerequisites

Enable R2 in Cloudflare

Create R2 Bucket

Configure Public Access

Generate API Credentials

Environment Configuration

Backend (backend/.env)

Root (.env)

S3-Compatible Client Setup

Configure CORS

CDN and Caching

Verification

Best Practices

Example: Image Upload with Optimization

Troubleshooting

Cost Optimization

Security Best Practices

Next Steps

Deployment

Auth0 Setup

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Documentation Index

​Prerequisites

​Enable R2 in Cloudflare

​Create R2 Bucket

​Configure Public Access

​Generate API Credentials

​Environment Configuration

​Backend (backend/.env)

​Root (.env)

​S3-Compatible Client Setup

​Configure CORS

​CDN and Caching

​Verification

​Best Practices

​Example: Image Upload with Optimization

​Troubleshooting

​Cost Optimization

​Security Best Practices

​Next Steps

Deployment

Auth0 Setup

Build docs developers (and LLMs) love

Prerequisites

Enable R2 in Cloudflare

Create R2 Bucket

Configure Public Access

Generate API Credentials

Environment Configuration

Backend (backend/.env)

Root (.env)

S3-Compatible Client Setup

Configure CORS

CDN and Caching

Verification

Best Practices

Example: Image Upload with Optimization

Troubleshooting

Cost Optimization

Security Best Practices

Next Steps