cloudflare-docs

cloudflare-docs copied to clipboard

Proposed changes

---

title: s3mini pcx_content_type: example

import { Render } from "~/components";

The S3mini client is a zero‑dependency, ~14 kB library that uses SigV4 and runs on Cloudflare Workers, Node 20+ and Bun. Unlike the heavyweight AWS SDKs it expects a bucket‑scoped endpoint and therefore does not take a separate bucket parameter.

Install

npm install s3mini            # Node / Bun / tooling
# or
yarn add s3mini

:::note Edge‑ready S3mini has no runtime dependencies and is purpose‑built for serverless/edge runtimes; bundle size stays under 15 kB with zero polyfills required. :::

Configure credentials

Place the following variables in a .env (or bind them as Secrets / Vars inside your Worker):

R2_ACCESS_KEY_ID=<your‑access‑key>
R2_SECRET_ACCESS_KEY=<your‑secret‑key>
# Bucket‑scoped endpoint → <account‑id>.r2.cloudflarestorage.com/<bucket>
R2_ENDPOINT=https://<account‑id>.r2.cloudflarestorage.com/my‑bucket-name
R2_REGION=auto

Why auto?  R2 is not tied to an AWS region, but S3mini still needs a value for the SigV4 string. Pass auto (or any string) — it will be ignored when generating the canonical request for R2.

Example 1 — Node / Bun script

import { S3mini } from "s3mini"

const s3 = new S3mini({
  accessKeyId: process.env.R2_ACCESS_KEY_ID!,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
  endpoint: process.env.R2_ENDPOINT!,          // bucket‑scoped host
  region: process.env.R2_REGION!               // 'auto' for R2
})

const key = "hello.txt"
await s3.putObject(key, "Hello R2 from S3mini 👋")

const resp = await s3.getObject(key)
console.log(await resp.text())                 // → "Hello R2 from S3mini 👋"

Example 2 — Inside a Cloudflare Worker

import { S3mini } from "s3mini"

const s3 = new S3mini({
  accessKeyId: R2_ACCESS_KEY_ID,                        // bound secret
  secretAccessKey: R2_SECRET_ACCESS_KEY,                // bound secret
  endpoint: `https://my‑bucket.${ACCOUNT_ID}.r2.cloudflarestorage.com`,
  region: "auto",
})

export default {
  async fetch(request: Request) {
    const { pathname } = new URL(request.url)

    if (pathname === "/upload") {
      await s3.putObject("workers‑upload.txt", "Uploaded from a Worker!")
      return new Response("Uploaded ✔️")
    }

    const resp = await s3.getObject("workers‑upload.txt")
    if (!resp) return new Response("Not found", { status: 404 })

    return new Response(resp.body, resp.headers)
  },
}

Additional operations

S3mini supports the essential S3 API (listObjects, deleteObject, multipart uploads, presigned URL generation, …). Because the bucket is derived from endpoint, every call only needs the key (object path) plus any optional headers.

Subject Matter

Adding altearnative client to S3 SDKs

Content Location

in

• https://developers.cloudflare.com/r2/examples/aws/ add
• https://developers.cloudflare.com/r2/examples/aws/s3mini.mdx

Additional information

No response