Uploading Files to R2: A Practical Guide for Developers

Previously in this course, we covered the Introduction to R2 Storage: Buckets and Object Storage, where we established the core concepts of object storage and created our first bucket. Now that you have a bucket ready, we will shift focus to interacting with it programmatically using the Wrangler CLI to manage your assets.

While the Cloudflare dashboard is excellent for visual management, the CLI allows you to integrate storage operations directly into your deployment pipelines.

Managing R2 via the Wrangler CLI

The Wrangler CLI is the primary tool for interacting with Cloudflare services. To manipulate R2, we use the wrangler r2 command namespace. Before proceeding, ensure you have completed the Introduction to Wrangler CLI to ensure your environment is authenticated.

Uploading a File to R2

Uploading a file, or "putting an object," is straightforward. You target your bucket name and provide the local file path.

Bash
# Syntax: wrangler r2 object put <bucket-name>/<object-key> --file <local-file>
wrangler r2 object put my-assets/hero-image.png --file ./images/hero-image.png

When you execute this, Wrangler handles the multipart upload process for you, ensuring the file is correctly stored in your R2 bucket. If the object key already exists, this command will overwrite it.

Listing Bucket Contents

To verify that your file was successfully uploaded, you can list the objects currently stored in your bucket. This is essential for debugging your application's asset inventory.

Bash
# List all objects in the bucket
wrangler r2 object list my-assets

The output will provide a JSON-formatted list of objects, including metadata like the object size and the ETag (a unique identifier for the specific version of the file).

Configuring Public Access for Assets

By default, R2 buckets are private. However, in many development scenarios, you need to serve images or static files directly. To do this, you must bind your bucket to a public domain.

1. Create a Custom Domain: In the Cloudflare dashboard, ensure your domain is proxied (the orange cloud).
2. Connect Domain to R2: Navigate to the R2 section, select your bucket, and go to Settings > Public Access.
3. Connect Domain: Enter the subdomain (e.g., assets.yourdomain.com) you want to use.

Once connected, your files are accessible via standard HTTP requests. If you upload logo.png to your bucket, it will be available at https://assets.yourdomain.com/logo.png.

Hands-on Exercise

To practice these skills, perform the following steps:

1. Create a local dummy file: echo "Hello R2" > test.txt
2. Upload this file to your bucket using wrangler r2 object put.
3. Use wrangler r2 object list to verify the file appears in the output.
4. (Optional) Delete the file using wrangler r2 object delete <bucket-name>/test.txt to clean up your workspace.

Common Pitfalls

• Case Sensitivity: R2 object keys are case-sensitive. Uploading Image.png and requesting image.png will result in a 404 error.
• Missing Authentication: If you receive a "403 Forbidden" error during upload, run wrangler login to ensure your session hasn't expired.
• Pathing Errors: Always ensure your wrangler.toml file or your CLI command correctly references the bucket name exactly as it appears in the dashboard.
• Public Access Propagation: It can take a few minutes for public access settings to propagate across Cloudflare's global network after you attach a domain.

Frequently Asked Questions

Can I upload entire directories at once? Wrangler's r2 object put command is designed for individual files. To upload entire directories, you would typically write a simple shell script or Node.js utility that iterates through your folder and calls the command for each file.

Is there a limit to the file size? Yes, but R2 is highly scalable. For very large files (multi-gigabyte), you should consider the multipart upload API rather than the basic CLI command to ensure reliability.

Does r2 object list show folders? R2 uses a flat namespace. While you can use "folders" in your key naming (e.g., images/logo.png), R2 treats the entire string as the key. The list command will show all keys, and you can filter them by prefix.

Recap

In this lesson, we moved from the theory of object storage to practical management. We learned to use wrangler r2 object put to upload assets, verified our storage with wrangler r2 object list, and configured public domain access to serve files to the web. These skills form the foundation for integrating dynamic content into your Workers-based applications.

Up next: Integrating R2 with Workers, where we will write code to programmatically serve these assets.