S3

S3 driver allows storing KV data to Amazon S3 or any other S3-compatible provider.

Driver implementation is lightweight and based on fetch working with Node.js as well as edge workers.

Usage

Driver name: s3

Setup

Setup a "Bucket" in your S3-compatible provider. You need this info:

• Access Key ID
• Secret Access Key
• Bucket name
• Endpoint
• Region

Make sure to install required peer dependencies:

npm i aws4fetch

yarn add aws4fetch

pnpm i aws4fetch

bun i aws4fetch

deno i npm:aws4fetch

Then please make sure to set all driver's options:

import { createStorage } from "unstorage";
import s3Driver from "unstorage/drivers/s3";

const storage = createStorage({
  driver: s3Driver({
    accessKeyId: "", // Access Key ID
    secretAccessKey: "", // Secret Access Key
    endpoint: "",
    bucket: "",
    region: "",
  }),
});

Options:

• bulkDelete: Enabled by default to speedup clear() operation. Set to false if provider is not implementing DeleteObject.

Setting Headers

You can specify HTTP headers when storing items using the options parameter:

// Set Content-Type and Cache-Control
await storage.setItemRaw("image.png", imageBuffer, {
  headers: {
    "Content-Type": "image/png",
    "Cache-Control": "max-age=31536000",
  },
});

// Set custom S3 metadata
await storage.setItem("document.json", jsonString, {
  headers: {
    "Content-Type": "application/json",
    "x-amz-meta-author": "john-doe",
  },
});

Supported headers include:

• Content-Type
• Cache-Control
• Content-Disposition
• Content-Encoding
• Content-Language
• Expires
• Custom metadata via x-amz-meta-* prefixed headers

Note: getMeta() only returns custom metadata headers (those with x-amz-meta-* prefix). Standard headers like Content-Type are set on the S3 object but not returned by getMeta().

Tested providers

Any S3-compatible provider should work out of the box. Pull-Requests are more than welcome to add info about other any other tested provider.

Amazon S3

Options:

• Set endpoint to https://s3.[region].amazonaws.com/

Cloudflare R2

Options:

• Set endpoint to https://[uid].r2.cloudflarestorage.com/
• Set region to auto