Workers API

Workers let you run code at the edge. When you bind an R2 bucket to a Worker, you can read and write objects directly using the Workers API.

1. Create a bucket

A bucket stores your objects in R2. To create a new R2 bucket:

Wrangler CLI

Dashboard

Log in to your Cloudflare account:
```
npx wrangler login
```
Create a bucket named my-bucket:
```
npx wrangler r2 bucket create my-bucket
```
If prompted, select the account you want to create the bucket in.
Verify the bucket was created:
```
npx wrangler r2 bucket list
```

In the Cloudflare Dashboard, go to R2 object storage.

dash.cloudflare.com
Select Create bucket.
Enter a name for your bucket.
Select a location for your bucket and a default storage class.
Select Create bucket.

2. Create a Worker with an R2 binding

Create a new Worker project:
npm
yarn
pnpm
npm create cloudflare@latest -- r2-worker
yarn create cloudflare r2-worker
pnpm create cloudflare@latest r2-worker
When prompted, select Hello World example and JavaScript (or TypeScript) as your template.
Move into the project directory:
```
cd r2-worker
```

Add an R2 binding to your Wrangler configuration file. Replace my-bucket with your bucket name:

wrangler.jsonc

wrangler.toml

{
  "r2_buckets": [
    {
      "binding": "MY_BUCKET",
      "bucket_name": "my-bucket"
    }
  ]
}

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

(Optional) If you are using TypeScript, regenerate types:
```
npx wrangler types
```

3. Read and write objects

Use the binding to interact with your bucket. This example stores and retrieves objects based on the URL path:

JavaScript

TypeScript

src/index.js

export default {
	async fetch(request, env) {
		// Get the object key from the URL path
		// For example: /images/cat.png → images/cat.png
		const url = new URL(request.url);
		const key = url.pathname.slice(1);

		// PUT: Store the request body in R2
		if (request.method === "PUT") {
			await env.MY_BUCKET.put(key, request.body);
			return new Response(`Put ${key} successfully!`);
		}

		// GET: Retrieve the object from R2
		const object = await env.MY_BUCKET.get(key);
		if (object === null) {
			return new Response("Object not found", { status: 404 });
		}
		return new Response(object.body);
	},
};

src/index.ts

export default {
	async fetch(request, env): Promise<Response> {
		// Get the object key from the URL path
		// For example: /images/cat.png → images/cat.png
		const url = new URL(request.url);
		const key = url.pathname.slice(1);

		// PUT: Store the request body in R2
		if (request.method === "PUT") {
			await env.MY_BUCKET.put(key, request.body);
			return new Response(`Put ${key} successfully!`);
		}

		// GET: Retrieve the object from R2
		const object = await env.MY_BUCKET.get(key);
		if (object === null) {
			return new Response("Object not found", { status: 404 });
		}
		return new Response(object.body);
	},
} satisfies ExportedHandler<Env>;

4. Test and deploy

Test your Worker locally:
```
npx wrangler dev
```
Local development
By default, wrangler dev uses a local R2 simulation. Objects you store during development exist only on your machine in the .wrangler/state folder and do not affect your production bucket.
To connect to your real R2 bucket during development, add "remote": true to your R2 binding in your Wrangler configuration file. Refer to remote bindings for more information.

Once the dev server is running, test storing and retrieving objects:

# Store an object
curl -X PUT http://localhost:8787/my-file.txt -d 'Hello, R2!'

# Retrieve the object
curl http://localhost:8787/my-file.txt

Deploy to production:
```
npx wrangler deploy
```

After deploying, Wrangler outputs your Worker's URL (for example, https://r2-worker.<YOUR_SUBDOMAIN>.workers.dev). Test storing and retrieving objects:

# Store an object
curl -X PUT https://r2-worker.<YOUR_SUBDOMAIN>.workers.dev/my-file.txt -d 'Hello, R2!'

# Retrieve the object
curl https://r2-worker.<YOUR_SUBDOMAIN>.workers.dev/my-file.txt

Refer to the Workers R2 API documentation for the complete API reference.