Cloudflare R2 Uploader

The simplest way to upload files to Cloudflare R2.

A lightweight, zero-config uploader for Cloudflare R2 with built-in file validation, automatic UUID file names, folder support, and multipart uploads for large files.

Designed for Next.js, Node.js, and any environment that supports the Web File API.

✨ Features

• 🚀 Extremely simple API
• 📁 Upload files to custom folders
• ⚡ Multipart uploads for large files
• 📦 Automatic chunked uploads
• 🖼️ File type validation
• 📏 File size validation
• 🔑 Automatic UUID file names
• 🌐 Instantly returns the public file URL
• 🛡️ Built on the official AWS S3 SDK
• 💙 Made specifically for Cloudflare R2

Installation

npm install cloudflare-r2-uploader

Environment Variables

Create a .env file.

R2_BUCKET=your-bucket-name
R2_PUBLIC_URL=https://pub-xxxxxxxxxxxxxxxx.r2.dev
R2_ACCOUNT_ID=xxxxxxxxxxxxxxxx
R2_ACCESS_ID=xxxxxxxxxxxxxxxx
R2_SECRET_KEY=xxxxxxxxxxxxxxxx

| Variable | Description | |----------|-------------| | R2_BUCKET | Cloudflare R2 bucket name | | R2_PUBLIC_URL | Public URL of your bucket | | R2_ACCOUNT_ID | Cloudflare Account ID | | R2_ACCESS_ID | R2 Access Key ID | | R2_SECRET_KEY | R2 Secret Access Key |

Usage

Import the functions you need.

import { upload, stream } from "cloudflare-r2-uploader";

upload()

Perfect for small and medium-sized files.

const url = await upload(file);

console.log(url);

Returns

https://pub-xxxxxxxxxxxxxxxx.r2.dev/79d8a92e-a2bc-48e7-bd94-0b6c9eb1f7dc.jpg

stream()

Ideal for uploading large files using Cloudflare R2 Multipart Upload.

const url = await stream(file);

console.log(url);

By default uploads in 5 MB chunks (minimum supported by S3/R2 Multipart Upload).

Upload to a Folder

const url = await upload(file, {
    folder: "avatars"
});

or

const url = await stream(file, {
    folder: "videos"
});

Result

https://pub-xxxxxxxxxxxxxxxx.r2.dev/avatars/79d8a92e-a2bc-48e7-bd94-0b6c9eb1f7dc.jpg

Validation

Maximum File Size

maxSize is specified in MB.

await upload(file, {
    maxSize: 10
});

Allowed File Types

await upload(file, {
    allowedTypes: [
        "image/",
        "application/pdf"
    ]
});

Upload Videos

await upload(file, {
    allowedTypes: [
        "video/"
    ]
});

Upload PDFs Only

await upload(file, {
    allowedTypes: [
        "application/pdf"
    ]
});

Allow Multiple Types

await upload(file, {
    allowedTypes: [
        "image/",
        "video/",
        "audio/",
        "application/pdf"
    ]
});

Multipart Upload

Large files can be uploaded in chunks.

await stream(file, {
    chunkSize: 10
});

chunkSize is specified in MB.

If a value smaller than 5 MB is provided, it is automatically changed to 5 MB, which is the minimum supported part size for Cloudflare R2 Multipart Upload.

Example:

await stream(file, {
    chunkSize: 2
});

Internally becomes

chunkSize = 5;

API

upload(file, options)

| Option | Type | Default | Description | |---------|------|---------|-------------| | folder | string | "" | Upload inside a folder | | maxSize | number | 5 | Maximum file size (MB) | | allowedTypes | string[] | ["image/"] | Allowed MIME types |

stream(file, options)

| Option | Type | Default | Description | |---------|------|---------|-------------| | folder | string | "" | Upload inside a folder | | chunkSize | number | 5 | Upload chunk size (MB) | | maxSize | number | Infinity | Maximum file size (MB) | | allowedTypes | string[] | ["image/"] | Allowed MIME types |

Error Handling

try {
    const url = await upload(file);
} catch (error) {
    console.error(error.message);
}

Possible errors

| Error | Description | |--------|-------------| | File is required | No file was provided | | Invalid file. Expected a File object. | Invalid input | | File size must be under X MB | File exceeds the maximum allowed size | | File type "..." is not allowed. | MIME type is not permitted |

Examples

Upload an Image

const image = await upload(file, {
    folder: "users"
});

Upload a PDF

const pdf = await upload(file, {
    folder: "documents",
    allowedTypes: [
        "application/pdf"
    ]
});

Upload a Large Video

const video = await stream(file, {
    folder: "videos",
    chunkSize: 20,
    allowedTypes: [
        "video/"
    ]
});

Requirements

• Node.js 18+
• Cloudflare R2 Bucket
• Public Bucket URL
• R2 API Credentials

License

MIT

Made with ❤️ for the Cloudflare community.