Bun provides fast, native bindings for interacting with S3-compatible object storage services. Bun's S3 API is designed to be simple and feel similar to fetch'sResponse andBlob APIs (like Bun's local filesystem APIs).
import { s3, write, S3Client }from"bun";// Bun.s3 reads environment variables for credentials// file() returns a lazy reference to a file on S3const metadata= s3.file("123.json");// Download from S3 as JSONconst data=await metadata.json();// Upload to S3awaitwrite(metadata,JSON.stringify({ name:"John", age:30 }));// Presign a URL (synchronous - no network request needed)const url= metadata.presign({ acl:"public-read", expiresIn:60*60*24,// 1 day});// Delete the fileawait metadata.delete();
S3 is thede facto standard internet filesystem. Bun's S3 API works with S3-compatible storage services like:
If you've used thefetch API, you're familiar with theResponse andBlob APIs.S3File extendsBlob. The same methods that work onBlob also work onS3File.
// Read an S3File as textconst text=await s3file.text();// Read an S3File as JSONconst json=await s3file.json();// Read an S3File as an ArrayBufferconst buffer=await s3file.arrayBuffer();// Get only the first 1024 bytesconst partial=await s3file.slice(0,1024).text();// Stream the fileconst stream= s3file.stream();forawait (const chunkof stream) { console.log(chunk);}
Memory optimization
Methods liketext(),json(),bytes(), orarrayBuffer() avoid duplicating the string or bytes in memory when possible.
If the text happens to be ASCII, Bun directly transfers the string to JavaScriptCore (the engine) without transcoding and without duplicating the string in memory. When you use.bytes() or.arrayBuffer(), it will also avoid duplicating the bytes in memory.
These helper methods not only simplify the API, they also make it faster.
Bun automatically handles multipart uploads for large files and provides streaming capabilities. The same API that works for local files also works for S3 files.
// Write a large fileconst bigFile= Buffer.alloc(10*1024*1024);// 10MBconst writer= s3file.writer({// Automatically retry on network errors up to 3 times retry:3,// Queue up to 10 requests at a time queueSize:10,// Upload in 5 MB chunks partSize:5*1024*1024,});for (let i=0; i<10; i++) {await writer.write(bigFile);}await writer.end();
When your production service needs to let users upload files to your server, it's often more reliable for the user to upload directly to S3 instead of your server acting as an intermediary.
To facilitate this, you can presign URLs for S3 files. This generates a URL with a signature that allows a user to securely upload that specific file to S3, without exposing your credentials or granting them unnecessary access to your bucket.
The default behaviour is to generate aGET URL that expires in 24 hours. Bun attempts to infer the content type from the file extension. If inference is not possible, it will default toapplication/octet-stream.
import { s3 }from"bun";// Generate a presigned URL that expires in 24 hours (default)const download= s3.presign("my-file.txt");// GET, text/plain, expires in 24 hoursconst upload= s3.presign("my-file", { expiresIn:3600,// 1 hour method:"PUT", type:"application/json",// No extension for inferring, so we can specify the content type to be JSON});// You can call .presign() if on a file reference, but avoid doing so// unless you already have a reference (to avoid memory usage).const myFile= s3.file("my-file.txt");const presignedFile= myFile.presign({ expiresIn:3600,// 1 hour});
This will automatically redirect the user to the presigned URL for the S3 file, saving you the memory, time, and bandwidth cost of downloading the file to your server and sending it back to the user.
To use Bun's S3 client withMinIO, setendpoint to the URL that MinIO is running on in theS3Client constructor.
import { S3Client }from"bun";const minio=newS3Client({ accessKeyId:"access-key", secretAccessKey:"secret-key", bucket:"my-bucket",// Make sure to use the correct endpoint URL// It might not be localhost in production! endpoint:"http://localhost:9000",});
To use Bun's S3 client withsupabase, setendpoint to the supabase endpoint in theS3Client constructor. The supabase endpoint includes your account ID and /storage/v1/s3 path. Make sure to set Enable connection via S3 protocol on in the supabase dashboard in https://supabase.com/dashboard/project/<account-id>/settings/storage and to set the region informed in the same section.
When using a S3 Virtual Hosted-Style endpoint, you need to set thevirtualHostedStyle option totrue and if no endpoint is provided, Bun will use region and bucket to infer the endpoint to AWS S3, if no region is provided it will useus-east-1. If you provide a the endpoint, there are no need to provide the bucket name.
Credentials are one of the hardest parts of using S3, and we've tried to make it as easy as possible. By default, Bun reads the following environment variables for credentials.
Option name
Environment variable
accessKeyId
S3_ACCESS_KEY_ID
secretAccessKey
S3_SECRET_ACCESS_KEY
region
S3_REGION
endpoint
S3_ENDPOINT
bucket
S3_BUCKET
sessionToken
S3_SESSION_TOKEN
If theS3_* environment variable is not set, Bun will also check for theAWS_* environment variable, for each of the above options.
Option name
Fallback environment variable
accessKeyId
AWS_ACCESS_KEY_ID
secretAccessKey
AWS_SECRET_ACCESS_KEY
region
AWS_REGION
endpoint
AWS_ENDPOINT
bucket
AWS_BUCKET
sessionToken
AWS_SESSION_TOKEN
These environment variables are read from.env files or from the process environment at initialization time (process.env is not used for this).
These defaults are overridden by the options you pass tos3.file(credentials),new Bun.S3Client(credentials), or any of the methods that accept credentials. So if, for example, you use the same credentials for different buckets, you can set the credentials once in your.env file and then passbucket: "my-bucket" to thes3.file() function without having to specify all the credentials again.
S3File instances are created by calling theS3Client instance method or thes3.file() function. LikeBun.file(),S3File instances are lazy. They don't refer to something that necessarily exists at the time of creation. That's why all the methods that don't involve network requests are fully synchronous.
interfaceS3FileextendsBlob {slice(start:number,end?:number):S3File;exists():Promise<boolean>;unlink():Promise<void>;presign(options:S3Options):string;text():Promise<string>;json():Promise<any>;bytes():Promise<Uint8Array>;arrayBuffer():Promise<ArrayBuffer>;stream(options:S3Options):ReadableStream;write(data:|string|Uint8Array|ArrayBuffer|Blob|ReadableStream|Response|Request,options?:BlobPropertyBag, ):Promise<number>;exists(options?:S3Options):Promise<boolean>;unlink(options?:S3Options):Promise<void>;delete(options?:S3Options):Promise<void>;presign(options?:S3Options):string;stat(options?:S3Options):Promise<S3Stat>;/** * Size is not synchronously available because it requires a network request. * *@deprecated Use `stat()` instead. */ size:NaN;// ... more omitted for brevity}
LikeBun.file(),S3File extendsBlob, so all the methods that are available onBlob are also available onS3File. The same API for reading data from a local file is also available for reading data from S3.
Method
Output
await s3File.text()
string
await s3File.bytes()
Uint8Array
await s3File.json()
JSON
await s3File.stream()
ReadableStream
await s3File.arrayBuffer()
ArrayBuffer
That means usingS3File instances withfetch(),Response, and other web APIs that acceptBlob instances just works.
To read a partial range of a file, you can use theslice method.
const partial= s3file.slice(0,1024);// Read the partial range as a Uint8Arrayconst bytes=await partial.bytes();// Read the partial range as a stringconst text=await partial.text();
Internally, this works by using the HTTPRange header to request only the bytes you want. Thisslice method is the same asBlob.prototype.slice.
LikeResponse andBlob,S3File assumes UTF-8 encoding by default.
When calling one of thetext() orjson() methods on anS3File:
When a UTF-16 byte order mark (BOM) is detected, it will be treated as UTF-16. JavaScriptCore natively supports UTF-16, so it skips the UTF-8 transcoding process (and strips the BOM). This is mostly good, but it does mean if you have invalid surrogate pairs characters in your UTF-16 string, they will be passed through to JavaScriptCore (same as source code).
When a UTF-8 BOM is detected, it gets stripped before the string is passed to JavaScriptCore and invalid UTF-8 codepoints are replaced with the Unicode replacement character (\uFFFD).
