Bun S3
Upload, download, list, and presign files with Bun's native Bun.S3Client on AWS S3, Cloudflare R2, MinIO, or any S3-compatible bucket, with no AWS SDK.
files-sdk/bun-s3 runs the Files API on Bun.S3Client, the S3 client built into the Bun runtime, instead of @aws-sdk/client-s3. It talks to AWS S3 and, through the endpoint option, to any S3-compatible service such as Cloudflare R2, MinIO, or DigitalOcean Spaces. Use it when your app already runs on Bun and you want S3 storage without installing the AWS SDK.
Installation
This adapter has no extra peer dependencies, but it requires the Bun runtime - it’s built on Bun’s native Bun.S3Client, which Node doesn’t provide. (Outside Bun it throws unless you hand it a Bun.S3Client-shaped client yourself.)
npm install files-sdkpnpm add files-sdkyarn add files-sdkbun add files-sdknub add files-sdkaube add files-sdkUsage
import { Files } from "files-sdk";
import { bunS3 } from "files-sdk/bun-s3";
const files = new Files({
adapter: bunS3({
bucket: "uploads",
region: "us-east-1",
// accessKeyId / secretAccessKey auto-loaded by Bun from
// S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY (or AWS_* equivalents)
}),
});
// Or hand it the singleton Bun.s3 client directly:
new Files({ adapter: bunS3({ client: Bun.s3 }) });
When you pass client, the client owns its bucket, region, endpoint, and credentials, so the adapter throws at construction if you also pass bucket, region, endpoint, virtualHostedStyle, accessKeyId, secretAccessKey, or sessionToken. publicBaseUrl and defaultUrlExpiresIn still apply.
The main differences from files-sdk/s3:
copy()streams bytes through your process, because Bun doesn’t expose a server-sideCopyObjectprimitive.upload()throws onmetadataandcacheControl, becauseBun.S3Client.write()has no equivalent options.signedUploadUrl()throws onmaxSizeand a positiveminSize, because Bun exposes presigned URLs only, not S3 POST policy fields. It also throws oncontentType: Bun’s presigned PUT signs only thehostheader, so it can’t enforce a Content-Type. (TheuseFilesgateway falls back to proxying such uploads through your server.)- Pause/resume via
controlworks within one process only, and there are no provider-native conditional operations.
Reach for files-sdk/s3 on the same bucket when you need any of those.
Environment variables
The bucket, region, endpoint, and credentials can all come from the environment. Bun resolves these itself, not files-sdk: it checks the S3_* name first, then the AWS_* fallback, and an option you pass explicitly wins over both.
| Option | Environment variable | Fallback |
|---|---|---|
accessKeyId |
S3_ACCESS_KEY_ID |
AWS_ACCESS_KEY_ID |
secretAccessKey |
S3_SECRET_ACCESS_KEY |
AWS_SECRET_ACCESS_KEY |
sessionToken |
S3_SESSION_TOKEN |
AWS_SESSION_TOKEN |
region |
S3_REGION |
AWS_REGION |
endpoint |
S3_ENDPOINT |
AWS_ENDPOINT |
bucket |
S3_BUCKET |
AWS_BUCKET |
Bun reads them from .env files or the process environment, not through process.env, so pass an option explicitly for any value you compute at runtime. With no region and no endpoint, Bun targets AWS S3 in us-east-1.
S3_ACCESS_KEY_ID=AKIA...
S3_SECRET_ACCESS_KEY=...
S3_REGION=eu-west-1
S3_BUCKET=uploads
// Everything comes from .env
const files = new Files({ adapter: bunS3() });
Connect to Cloudflare R2, MinIO, and other S3-compatible services
Set endpoint to point the client at an S3-compatible API. Requests use path-style addressing (https://<endpoint>/<bucket>/<key>) unless you set virtualHostedStyle: true.
Cloudflare R2
const files = new Files({
adapter: bunS3({
bucket: "uploads",
endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
region: "auto",
accessKeyId: process.env.R2_ACCESS_KEY_ID,
secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
}),
});
Use an R2 API token’s access key ID and secret access key. If you need server-side copy, upload metadata, or a Workers R2Bucket binding, use the dedicated files-sdk/r2 adapter instead; its fetch client also needs no @aws-sdk/* packages.
MinIO and local development
const files = new Files({
adapter: bunS3({
bucket: "uploads",
endpoint: "http://localhost:9000",
accessKeyId: "minioadmin",
secretAccessKey: "minioadmin",
}),
});
Path-style addressing is the default, which is what MinIO expects, so no extra flag is needed.
AWS S3 with virtual-hosted-style URLs
On AWS, region is enough: Bun derives the endpoint from the region and bucket. Set virtualHostedStyle: true to address the bucket as https://<bucket>.s3.<region>.amazonaws.com.
const files = new Files({
adapter: bunS3({
bucket: "uploads",
region: "eu-west-1",
virtualHostedStyle: true,
}),
});
Other providers
The same endpoint option covers other S3-compatible services, for example https://<region>.digitaloceanspaces.com for DigitalOcean Spaces or https://<project-ref>.supabase.co/storage/v1/s3 for Supabase Storage. Many of them also have a dedicated files-sdk adapter, such as DigitalOcean Spaces, Wasabi, or Hetzner, that fills in the endpoint for you but runs on the AWS SDK.
Upload files with Bun S3
upload() accepts a string, bytes, a Blob or File, or a ReadableStream. Bun.file() returns a Blob, so you can upload a file from disk directly.
// A string
await files.upload("notes/hello.txt", "Hello from Bun");
// A file on disk - Bun.file() is a Blob, and its type becomes the Content-Type
await files.upload("reports/q3.pdf", Bun.file("./q3.pdf"));
// A stream, such as a fetch() or request body
const res = await fetch("https://example.com/video.mp4");
const result = await files.upload("videos/clip.mp4", res.body!, {
contentType: "video/mp4",
});
// → { key, size, contentType, etag, lastModified }
The stored Content-Type is the contentType option when you pass one, otherwise a Blob’s own type, text/plain; charset=utf-8 for a string, and application/octet-stream for anything else. Stream bodies are wrapped in a Response and handed to Bun’s writer. onProgress is reported by the SDK: byte by byte for stream bodies, and as a start and finish event for buffered ones.
Download and stream files
// Buffered
const note = await files.download("notes/hello.txt");
await note.text(); // "Hello from Bun"
// Streamed - pipe a large object to the client without buffering it
const video = await files.download("videos/clip.mp4", { as: "stream" });
const response = new Response(video.stream(), {
headers: { "Content-Type": video.contentType },
});
// A byte range (end is inclusive), fetched with a ranged GET
const firstKiB = await files.download("videos/clip.mp4", {
range: { start: 0, end: 1023 },
});
download() reads the object’s metadata with Bun’s stat() before it reads the body, so each download is a HEAD request followed by a GET. See byte ranges for the range semantics.
List files in a bucket
// One page, filtered by prefix
const { items, cursor } = await files.list({ prefix: "reports/", limit: 100 });
// Every page
for await (const file of files.listAll({ prefix: "reports/" })) {
console.log(file.key, file.size, file.lastModified);
}
// One folder level: subfolders come back in `prefixes`
const { prefixes } = await files.list({ prefix: "photos/", delimiter: "/" });
// Match keys by glob
for await (const file of files.search("reports/**/*.csv")) {
console.log(file.key);
}
Bun’s list response carries no Content-Type, so each item’s contentType is inferred from the key’s extension (application/octet-stream when unknown). Call head() when you need the stored value. See list and search for pagination and pattern syntax.
Presigned URLs with Bun S3
Presigned download URLs
url() returns a presigned GET URL. Bun signs it locally, so the call makes no network request.
const url = await files.url("reports/q3.pdf"); // expires in 1 hour
const short = await files.url("reports/q3.pdf", { expiresIn: 300 });
// Force a download with a filename
const attachment = await files.url("reports/q3.pdf", {
responseContentDisposition: 'attachment; filename="q3.pdf"',
});
The default lifetime is 1 hour (the adapter’s defaultUrlExpiresIn, not Bun’s own 24-hour default). SigV4 caps a presigned URL at 7 days, so an expiresIn above 604800 seconds throws instead of returning a URL the server would reject.
If the bucket is public or sits behind a CDN, set publicBaseUrl and url(key) returns ${publicBaseUrl}/${key} without signing. Passing expiresIn or responseContentDisposition still produces a signed URL, because a permanent URL can’t expire and has no signature to bind the override into.
Presigned upload URLs
signedUploadUrl() returns a presigned PUT URL that a browser can upload to directly.
// On your server
const upload = await files.signedUploadUrl("avatars/abc.png", {
expiresIn: 60,
});
// → { method: "PUT", url }
// In the browser
await fetch(upload.url, { method: "PUT", body: file });
maxSize, a positive minSize, and contentType all throw here (see the differences above), so enforce size and type limits in your own endpoint before you issue the URL, or use files-sdk/s3 for a POST policy. A browser upload to another origin also needs a CORS rule on the bucket that allows PUT from your site.
Use the Bun.S3Client directly
files.raw is the underlying Bun.S3Client: the one the adapter constructed, or the client you passed. Use it for Bun features the unified API doesn’t cover. See escape hatch.
Errors
Bun’s S3 errors are normalized to FilesError, with the original error in cause:
NotFound-NoSuchKey,NotFound, or HTTP 404.exists()returnsfalseinstead of throwing.Unauthorized-AccessDenied,ERR_S3_MISSING_CREDENTIALS,ERR_S3_INVALID_SIGNATURE,ERR_S3_INVALID_SESSION_TOKEN, or HTTP 401/403. That includes a 401/403 on the HEAD behindhead(),exists(),download(), andcopy(): Bun reports a failed HEAD without a status, so the adapter re-sends it as a presigned HEAD to read the status, and the call isn’t retried as aProvidererror.Conflict-PreconditionFailed, or HTTP 409/412.Provider- everything else. The message is Bun’s own, orBun S3 errorwhen it has none.
Bun S3 vs files-sdk/s3 vs files-sdk/s3-fetch
All three speak the same S3 protocol and return the same Files results, so you can switch between them without changing application code.
files-sdk/bun-s3 |
files-sdk/s3 |
files-sdk/s3-fetch |
|
|---|---|---|---|
| Runtime | Bun only | Node.js and Bun | Any runtime with fetch and Web Crypto, including Cloudflare Workers |
| Extra packages | None | @aws-sdk/* peers |
None |
| Credentials | Options or S3_* / AWS_* env vars, resolved by Bun |
AWS credential chain (env vars, IAM role, shared profile, …) | Options or AWS_* env vars |
ReadableStream uploads |
Handed to Bun’s writer | Multipart via the optional @aws-sdk/lib-storage |
Buffered in memory, one PUT |
copy() |
Streamed through your process | Server-side CopyObject |
Server-side CopyObject |
Upload metadata / cacheControl |
Throws | ✅ | ✅ |
signedUploadUrl with maxSize |
Throws | ✅ presigned POST policy | Throws |
signedUploadUrl with contentType |
Throws | ✅ | ✅ |
Resumable uploads (control) |
In-process only | ✅ across processes | Throws |
| Conditional operations | ❌ | ✅ on AWS S3 | ❌ |
Pick files-sdk/bun-s3 for a Bun app that only needs the core operations and should carry no AWS SDK. Pick files-sdk/s3 when you need server-side copy, metadata, size-capped browser uploads, resumable uploads, or the full AWS credential chain; it runs on Bun too. Pick files-sdk/s3-fetch for Cloudflare Workers and other edge runtimes.
Options
client?BunS3ClientLike
A pre-configured `Bun.S3Client`-shaped instance — for example the global `Bun.s3`, or one constructed with specific credentials elsewhere in your app. When set, the adapter uses it as-is and rejects any of `bucket`, `region`, `endpoint`, `virtualHostedStyle`, `accessKeyId`, `secretAccessKey`, `sessionToken` at construction (they would be silently ignored otherwise). When unset, the adapter constructs its own client from the options below.
BunS3ClientLikebucket?string
S3 bucket name. Scopes operations and is exposed as `adapter.bucket`. Falls back to `S3_BUCKET` / `AWS_BUCKET` via Bun's built-in resolution.
stringregion?string
AWS region (e.g. `us-east-1`). Falls back to `S3_REGION` / `AWS_REGION` via Bun's resolution.
stringendpoint?string
Override the S3 service endpoint. Use this to point at S3-compatible services (R2, DigitalOcean Spaces, Wasabi, MinIO, ...).
stringvirtualHostedStyle?boolean
Use virtual-hosted-style addressing (`https://<bucket>.<endpoint>`) instead of path-style. Defaults to `false` — flip on for endpoints that require it.
booleanaccessKeyId?string
Static access key ID. Skip to let Bun resolve it from `S3_ACCESS_KEY_ID` / `AWS_ACCESS_KEY_ID`.
stringsecretAccessKey?string
Static secret access key. Skip to let Bun resolve it from `S3_SECRET_ACCESS_KEY` / `AWS_SECRET_ACCESS_KEY`.
stringsessionToken?string
Static session token for temporary credentials. Skip to let Bun resolve it from `S3_SESSION_TOKEN` / `AWS_SESSION_TOKEN`.
stringpublicBaseUrl?string
Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips signing — use this if your bucket is fronted by a CDN or has a public-read policy. Passing `expiresIn` or `responseContentDisposition` still forces a signed URL even when this is set, because a permanent CDN URL can't expire and has no signature in which to bind the override. When unset, `url()` returns a presigned GetObject (1-hour default).
stringdefaultUrlExpiresIn?number
Default expiry, in seconds, for the presigned URLs returned by `url()` when no per-call `expiresIn` is given. Defaults to 3600 (1 hour). Per-call `url(key, { expiresIn })` overrides.
numberCompatibility
| Method | Status | Notes |
|---|---|---|
upload |
⚠️ | User metadata and cacheControl throw - Bun.S3Client.write() exposes neither field. Reach for s3() on the same bucket if you need them. Stream bodies are wrapped in a Response and handed to Bun’s writer. Pause/resume via control is in-process only — Bun’s S3 client exposes no resumable upload id, so chunks are buffered and a token cannot resume in a new process. |
download |
✅ | |
delete |
✅ | |
list |
⚠️ | Bun’s list response carries no Content-Type, so contentType is inferred from the key’s extension (application/octet-stream when unknown), like the rest of the S3 family. Use head() for the stored value. delimiter folding works. |
search |
✅ | |
head |
✅ | |
exists |
✅ | |
copy |
⚠️ | Client-side stream copy - Bun.S3Client doesn’t expose a server-side CopyObject, so the source is streamed through this process and re-uploaded. Doubled bandwidth, not atomic, and drops Content-Disposition/cache headers/user metadata/ACL (only Content-Type is preserved). Reach for s3() on the same bucket for server-side copy. |
url |
✅ | Presigned URLs are capped at 7 days (the SigV4 limit); a longer expiresIn throws. |
signedUploadUrl |
⚠️ | PUT URL only - Bun exposes presigned URLs, not S3 POST policy fields, so maxSize and a positive minSize throw (no content-length-range policy). contentType throws too, because Bun signs only the host header and can’t bind a Content-Type. Enforce upload caps and types at your application gateway instead. |
| conditional operations | ❌ | Not advertised; conditional calls fail before any request. |