Cloudflare R2 Direct Upload & Presigned URLs Guide

The Tragedy of Backend Relay Uploads: Memory Timeouts and Egress Fees

When building web and mobile applications that handle high-resolution images, 4K videos, or large PDF documents, the most common architectural mistake developers make is using a relay upload strategy: routing files through “Client -> Backend API Server -> Object Storage (S3/R2)”.

[Inefficient Backend Relay Upload Method]
[Client] --- (100MB File Upload) ---> [Node.js / Lambda Server] --- (Resend 100MB) ---> [Storage]
                                     * Server RAM buffering memory spikes
                                     * CPU execution time & timeouts exceeded
                                     * Double bandwidth & egress billing

This relay approach causes critical cloud infrastructure bottlenecks:

1. Server Compute Spikes and OOM Crashes: Buffering files ranging from 100MB to 1GB directly in server memory triggers Out-Of-Memory (OOM) errors. Additionally, holding HTTP connections open for over 30 seconds causes AWS Lambda or Cloudflare Workers to hit execution timeouts.
2. Double Bandwidth Charges: Ingesting raw file data from the client to the server and re-transmitting it to S3 storage doubles your inbound and outbound bandwidth costs.
3. Scalability Bottlenecks: Tying your server infrastructure scaling directly to file upload bandwidth degrades overall application responsiveness.

Cloudflare R2 Presigned URLs and the Direct Upload architecture solve this completely.

Instead of proxying the file payload, your backend (Cloudflare Worker) generates a cryptographically signed Presigned PUT URL in under 1ms. The client (Web or Flutter) then uploads the payload directly to the Cloudflare R2 bucket via a 1:1 connection.

This pattern slashes backend server compute usage by 99%. Paired with Cloudflare R2’s signature feature—$0 outbound egress fees—you get a virtually zero-cost pipeline for handling massive file uploads.

In this guide, you will learn the inner workings of Presigned URLs, single-file direct uploads, 100MB–5GB multipart uploads, CORS security configurations, and real-world performance benchmarks.

Architecture Comparison: Relay vs. Direct Upload

How R2 Direct Upload Works: Presigned PUT URL Encryption

Cloudflare Workers natively support AWS S3 API-compatible cryptography libraries, including @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner.

+-----------------------------------------------------------------------------------+
| Cloudflare R2 Presigned Direct Upload Pipeline                                     |
+-----------------------------------------------------------------------------------+

[Client (Web / Flutter)]         [Cloudflare Worker (1ms)]        [Cloudflare R2 Bucket]
           |                                 |                                |
           |--- 1. Upload request (Name/Size)->|                                |
           |                                 |--- 2. Create HMAC Signed URL ->| (Presigned PUT URL)
           |<-- 3. Return Presigned URL -----|                                |
           |                                                                  |
           |----------------------- 4. Direct HTTP PUT (Binary Payload) ------->|
           |<---------------------- 5. 200 OK (Upload Complete) ----------------|

1. Signature Request: The client sends file metadata—such as file name (video.mp4), mimeType (video/mp4), and file size—to the Worker.
2. Presigned PUT URL Generation: The Worker executes AWS S3 HMAC-SHA256 algorithms to issue an encrypted presigned URL valid for 5 minutes in just 1ms.
3. Direct HTTP PUT Transfer: The client issues a direct HTTP PUT request using the presigned URL, streaming binary data straight into R2.

Step 1: Create an R2 Bucket & Configure CORS

Before client browsers can send direct HTTP PUT requests to a Cloudflare R2 domain, you must configure CORS (Cross-Origin Resource Sharing) rules on your R2 bucket.

wrangler.jsonc R2 Bucket Binding

// wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "edge-r2-direct-upload",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "compatibility_flags": ["nodejs_compat"],

  // Cloudflare R2 Bucket Binding
  "r2_buckets": [
    {
      "binding": "MY_BUCKET",
      "bucket_name": "effidev-media-uploads"
    }
  ]
}

R2 Bucket CORS Policy Setup (cors.json)

Use the wrangler r2 bucket cors set CLI command to specify allowed origins and HTTP methods.

[
  {
    "AllowedOrigins": ["https://effidev.dev", "http://localhost:3000"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedHeaders": ["Content-Type", "x-amz-*"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

npx wrangler r2 bucket cors set effidev-media-uploads --file=cors.json

Step 2: Implement Edge Presigned URL API with Hono.js

Here is a Hono.js server implementation running on Cloudflare Workers that uses the AWS S3 SDK to issue Presigned PUT URLs.

Install Dependencies

npm install hono @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

Presigned URL Handler (src/index.ts)

// src/index.ts
import { Hono } from "hono";
import { cors } from "hono/cors";
import {
  S3Client,
  PutObjectCommand,
  CreateMultipartUploadCommand,
  UploadPartCommand,
  CompleteMultipartUploadCommand,
} from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

type Env = {
  Bindings: {
    MY_BUCKET: R2Bucket;
    R2_ACCOUNT_ID: string;
    R2_ACCESS_KEY_ID: string;
    R2_SECRET_ACCESS_KEY: string;
    R2_BUCKET_NAME: string;
  };
};

const app = new Hono<Env>();
app.use("*", cors());

// Factory function for S3-compatible Cloudflare R2 client
function getR2S3Client(env: Env["Bindings"]) {
  return new S3Client({
    region: "auto",
    endpoint: `https://${env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
    credentials: {
      accessKeyId: env.R2_ACCESS_KEY_ID,
      secretAccessKey: env.R2_SECRET_ACCESS_KEY,
    },
  });
}

// -------------------------------------------------------------------
// 1. Single File (under 100MB) Presigned PUT URL Generator API
// -------------------------------------------------------------------
app.post("/api/upload/presigned-url", async (c) => {
  const { fileName, contentType, fileSize } = await c.req.json();

  // Security validation: Limit single uploads to 100MB
  if (fileSize > 100 * 1024 * 1024) {
    return c.json({ error: "File size exceeds 100MB limit. Use multipart upload." }, 400);
  }

  const s3Client = getR2S3Client(c.env);
  const fileKey = `uploads/${Date.now()}_${crypto.randomUUID().slice(0, 8)}_${fileName}`;

  const command = new PutObjectCommand({
    Bucket: c.env.R2_BUCKET_NAME || "effidev-media-uploads",
    Key: fileKey,
    ContentType: contentType,
  });

  // Generate Presigned PUT URL valid for 5 minutes (300 seconds) — takes 1ms
  const presignedUrl = await getSignedUrl(s3Client, command, { expiresIn: 300 });

  return c.json({
    success: true,
    fileKey,
    uploadUrl: presignedUrl,
    expiresIn: 300,
  });
});

Step 3: Multipart Upload API for Large Files (100MB–5GB)

For videos or large binary payloads, divide the payload into chunks, upload them in parallel, and combine them using the Multipart Upload API pattern.

// -------------------------------------------------------------------
// 2. Large File Multipart Upload - Step 1: Initiate Multipart Session
// -------------------------------------------------------------------
app.post("/api/upload/multipart/initiate", async (c) => {
  const { fileName, contentType } = await c.req.json();
  const s3Client = getR2S3Client(c.env);
  const fileKey = `videos/${Date.now()}_${fileName}`;

  const command = new CreateMultipartUploadCommand({
    Bucket: c.env.R2_BUCKET_NAME,
    Key: fileKey,
    ContentType: contentType,
  });

  const response = await s3Client.send(command);

  return c.json({
    uploadId: response.UploadId,
    fileKey: fileKey,
  });
});

// -------------------------------------------------------------------
// 3. Large File Multipart Upload - Step 2: Issue Presigned URL per Part
// -------------------------------------------------------------------
app.post("/api/upload/multipart/presigned-part", async (c) => {
  const { fileKey, uploadId, partNumber } = await c.req.json();
  const s3Client = getR2S3Client(c.env);

  const command = new UploadPartCommand({
    Bucket: c.env.R2_BUCKET_NAME,
    Key: fileKey,
    UploadId: uploadId,
    PartNumber: partNumber,
  });

  const uploadUrl = await getSignedUrl(s3Client, command, { expiresIn: 600 });
  return c.json({ partNumber, uploadUrl });
});

// -------------------------------------------------------------------
// 4. Large File Multipart Upload - Step 3: Complete & Assemble Upload
// -------------------------------------------------------------------
app.post("/api/upload/multipart/complete", async (c) => {
  const { fileKey, uploadId, parts } = await c.req.json();
  // Example parts: [{ PartNumber: 1, ETag: '"e123..."' }, { PartNumber: 2, ETag: '"f456..."' }]
  const s3Client = getR2S3Client(c.env);

  const command = new CompleteMultipartUploadCommand({
    Bucket: c.env.R2_BUCKET_NAME,
    Key: fileKey,
    UploadId: uploadId,
    MultipartUpload: { Parts: parts },
  });

  await s3Client.send(command);

  return c.json({
    success: true,
    fileUrl: `https://pub-effidev-media.r2.dev/${fileKey}`,
  });
});

export default app;

Step 4: Client Integration (Web / Flutter)

Web Browser JavaScript Example

The client requests uploadUrl from the backend Worker and streams binary content directly using fetch(uploadUrl, { method: 'PUT', body: file }).

// Frontend Single File Direct Upload Function
async function uploadFileDirectToR2(file) {
  // 1. Request a 1ms signed URL from the Worker
  const res = await fetch("/api/upload/presigned-url", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      fileName: file.name,
      contentType: file.type,
      fileSize: file.size,
    }),
  });

  const { uploadUrl, fileKey } = await res.json();

  // 2. HTTP PUT directly to Cloudflare R2 bucket (zero backend relay!)
  const uploadRes = await fetch(uploadUrl, {
    method: "PUT",
    headers: {
      "Content-Type": file.type,
    },
    body: file, // Binary payload (File / Blob)
  });

  if (uploadRes.ok) {
    console.log("R2 Direct Upload Success:", fileKey);
    return fileKey;
  } else {
    throw new Error("Direct upload failed to R2 bucket");
  }
}

Real-World Performance & Cost Benchmark

Here is a benchmark report comparing the traditional backend relay method against Cloudflare R2 Presigned Direct Upload when processing 10GB of media files (100 files at 100MB each).

Performance & Cost Comparison

Conclusion: A Serverless, Zero-Relay Storage Architecture

Stop wasting server memory, fighting connection timeouts, and paying massive egress fees just to handle file uploads.

Combining Cloudflare Workers with R2 Presigned URL Direct Uploads yields compelling advantages:

1. ZERO Server Overhead: The backend Worker issues a signed URL in 1ms and exits immediately, avoiding CPU and RAM consumption.
2. $0 Egress Fees: Cloudflare R2 eliminates outbound traffic costs entirely.
3. Unlimited Scalability: Clients stream directly into R2 edge buckets, keeping server load flat even during massive traffic spikes.
4. Large File Multipart Support: Parallel chunk pipelines handle files up to 5GB cleanly at the edge.

Switch your legacy upload relays to R2 Presigned Direct Upload today to achieve a 99% cost reduction and a seamless user experience.

Related article: Check out our AWS S3 to Cloudflare R2 Migration Guide: $0 Egress & 95% Image Processing Cost Savings for more details on building cost-effective R2 architectures.