S3

The driver uses fetch and request signing from aws4fetch, so it works in Node.js and edge runtimes.

#Usage

Driver name: s3

#Setup

Create a bucket with your provider and collect the following values:

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

Make sure to install the required dependency:

npm i aws4fetch

Configure the required driver 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:

• accessKeyId (required): Access key ID.
• secretAccessKey (required): Secret access key.
• endpoint (required): S3-compatible service endpoint.
• bucket (required): Bucket name.
• region (required): Bucket region; use auto for Cloudflare R2.
• bulkDelete: Uses the bulk delete API to speed up clear() (default: true). Set it to false when the provider does not implement DeleteObjects.
• lib: An imported aws4fetch module or a function that returns it.

#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 standards-compatible S3 provider should work. Contributions documenting additional tested providers are welcome.

#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