S3Client.write method | Bun module | Bun

Writes data directly to a path in the bucket. Supports strings, buffers, streams, and web API types.

The path to the file in the bucket

The data to write to the file

Additional S3 options to override defaults

The number of bytes written

// Write string
await bucket.write("hello.txt", "Hello World");

// Write JSON with type
await bucket.write(
"data.json",
JSON.stringify({hello: "world"}),
{type: "application/json"}
);

// Write from fetch
const res = await fetch("https://example.com/data");
await bucket.write("data.bin", res);

// Write with ACL
await bucket.write("public.html", html, {
acl: "public-read",
type: "text/html"
});

Represents a raw buffer of binary data, which is used to store data for the different typed arrays. ArrayBuffers cannot be read from or written to directly, but can be passed to a typed array or DataView Object to interpret the raw buffer as needed.

Read-only. The length of the ArrayBuffer (in bytes).

Resizes the ArrayBuffer to the specified size (in bytes).

MDN

Resize an ArrayBuffer in-place.

Returns a section of an ArrayBuffer.

Creates a new ArrayBuffer with the same byte content as this buffer, then detaches this buffer.

MDN

Creates a new non-resizable ArrayBuffer with the same byte content as this buffer, then detaches this buffer.

MDN

Read-only. The length of the ArrayBuffer (in bytes).

Grows the SharedArrayBuffer to the specified size (in bytes).

MDN

Grow the SharedArrayBuffer in-place.

Returns a section of an SharedArrayBuffer.

A file-like object of immutable, raw data. Blobs represent data that isn't necessarily in a JavaScript-native format. The File interface is based on Blob, inheriting blob functionality and expanding it to support files on the user's system.

MDN Reference

MDN Reference

MDN Reference

Returns a promise that resolves to the contents of the blob as an ArrayBuffer

MDN Reference

Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes) its the same as new Uint8Array(await blob.arrayBuffer())

Read the data from the blob as a FormData object.

This first decodes the data from UTF-8, then parses it as a multipart/form-data body or a application/x-www-form-urlencoded body.

The type property of the blob is used to determine the format of the body.

This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.

Wrap this blob in a Bun.Image pipeline. Equivalent to new Bun.Image(this, options) — the constructor is synchronous (the underlying read happens lazily when an Image terminal is awaited), so this works on Bun.file(), Bun.s3(), fd-backed and in-memory blobs alike:

await Bun.file("photo.jpg").image().resize(400).webp().write("thumb.webp");

Read the data from the blob as a JSON object.

This first decodes the data from UTF-8, then parses it as JSON.

MDN Reference

MDN Reference

Returns a readable stream of the blob's contents

Returns a promise that resolves to the contents of the blob as a string

Blob powered by the fastest system calls available for operating on files.

This Blob is lazy. That means it won't do any work until you read from it.

const file = Bun.file("./hello.json");
console.log(file.type); // "application/json"
console.log(await file.text()); // '{"hello":"world"}'

A UNIX timestamp indicating when the file was last modified.

The name or path of the file, as specified in the constructor.

MDN Reference

MDN Reference

Returns a promise that resolves to the contents of the blob as an ArrayBuffer

MDN Reference

Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes) its the same as new Uint8Array(await blob.arrayBuffer())

Deletes the file (same as unlink)

Does the file exist?

This returns true for regular files and FIFOs. It returns false for directories. Note that a race condition can occur where the file is deleted or renamed after this is called but before you open it.

This does a system call to check if the file exists, which can be slow.

If using this in an HTTP server, it's faster to instead use return new Response(Bun.file(path)) and then an error handler to handle exceptions.

Instead of checking for a file's existence and then performing the operation, it is faster to just perform the operation and handle the error.

For empty Blob, this always returns true.

Read the data from the blob as a FormData object.

This first decodes the data from UTF-8, then parses it as a multipart/form-data body or a application/x-www-form-urlencoded body.

The type property of the blob is used to determine the format of the body.

This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.

Wrap this blob in a Bun.Image pipeline. Equivalent to new Bun.Image(this, options) — the constructor is synchronous (the underlying read happens lazily when an Image terminal is awaited), so this works on Bun.file(), Bun.s3(), fd-backed and in-memory blobs alike:

await Bun.file("photo.jpg").image().resize(400).webp().write("thumb.webp");

Read the data from the blob as a JSON object.

This first decodes the data from UTF-8, then parses it as JSON.

Offset any operation on the file starting at begin and ending at end. end is relative to 0

Similar to TypedArray.subarray. Does not copy the file, open the file, or modify the file.

If begin > 0, () will be slower on macOS

start offset in bytes

absolute offset in bytes (relative to 0)

MIME type for the new BunFile

Offset any operation on the file starting at begin

Similar to TypedArray.subarray. Does not copy the file, open the file, or modify the file.

If begin > 0, Bun.write() will be slower on macOS

start offset in bytes

MIME type for the new BunFile

Slice the file from the beginning to the end, optionally with a new MIME type.

MIME type for the new BunFile

Provides useful information about the file.

MDN Reference

Returns a readable stream of the blob's contents

Returns a promise that resolves to the contents of the blob as a string

Deletes the file.

Write data to the file. This is equivalent to using Bun.write with a BunFile.

The data to write.

The options to use for the write.

Incremental writer for files and pipes.

This Fetch API interface represents a resource request.

MDN Reference

MDN Reference

MDN Reference

Returns the cache mode associated with request, which is a string indicating how the request will interact with the browser's cache when fetching.

MDN Reference

Returns the credentials mode associated with request, which is a string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL.

MDN Reference

Returns the kind of resource requested by request, e.g., "document" or "script".

MDN Reference

Returns a Headers object consisting of the headers associated with request. Note that headers added in the network layer by the user agent will not be accounted for in this object, e.g., the "Host" header.

MDN Reference

Returns request's subresource integrity metadata, which is a cryptographic hash of the resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI]

MDN Reference

Returns a boolean indicating whether or not request can outlive the global in which it was created.

MDN Reference

Returns request's HTTP method, which is "GET" by default.

MDN Reference

Returns the mode associated with request, which is a string indicating whether the request will use CORS, or will be restricted to same-origin URLs.

MDN Reference

Returns the redirect mode associated with request, which is a string indicating how redirects for the request will be handled during fetching. A request will follow redirects by default.

MDN Reference

Returns the referrer of request. Its value can be a same-origin URL if explicitly set in init, the empty string to indicate no referrer, and "about:client" when defaulting to the global's default. This is used during fetching to determine the value of the Referer header of the request being made.

MDN Reference

Returns the referrer policy associated with request. This is used during fetching to compute the value of the request's referrer.

MDN Reference

Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort event handler.

MDN Reference

Returns the URL of request as a string.

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

This Fetch API interface represents the response to a request.

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

Provides information about files and allows JavaScript in a web page to access their content.

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

MDN Reference

Returns a promise that resolves to the contents of the blob as an ArrayBuffer

MDN Reference

Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes) its the same as new Uint8Array(await blob.arrayBuffer())

Read the data from the blob as a FormData object.

This first decodes the data from UTF-8, then parses it as a multipart/form-data body or a application/x-www-form-urlencoded body.

The type property of the blob is used to determine the format of the body.

This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.

Wrap this blob in a Bun.Image pipeline. Equivalent to new Bun.Image(this, options) — the constructor is synchronous (the underlying read happens lazily when an Image terminal is awaited), so this works on Bun.file(), Bun.s3(), fd-backed and in-memory blobs alike:

await Bun.file("photo.jpg").image().resize(400).webp().write("thumb.webp");

Read the data from the blob as a JSON object.

This first decodes the data from UTF-8, then parses it as JSON.

MDN Reference

MDN Reference

Returns a readable stream of the blob's contents

Returns a promise that resolves to the contents of the blob as a string

Represents a file in an S3-compatible storage service. Extends the Blob interface for compatibility with web APIs.

The bucket name containing the file.

const file = s3.file("s3:http://my-bucket/file.txt");
console.log(file.bucket); // "my-bucket"

The name or path of the file in the bucket.

const file = s3.file("folder/image.jpg");
console.log(file.name); // "folder/image.jpg"

Gets a readable stream of the file's content. Useful for processing large files without loading them entirely into memory.

// Basic streaming read
const stream = file.stream();
for await (const chunk of stream) {
console.log('Received chunk:', chunk);
}

MDN Reference

MDN Reference

Alias for delete() method. Provided for compatibility with Node.js fs API naming.

await file.unlink();

Returns a promise that resolves to the contents of the blob as an ArrayBuffer

MDN Reference

Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes) its the same as new Uint8Array(await blob.arrayBuffer())

Deletes the file from S3.

Promise that resolves when deletion is complete

// Basic deletion
await file.delete();

Checks if the file exists in S3. Uses HTTP HEAD request to efficiently check existence without downloading.

Promise resolving to true if file exists, false otherwise

// Basic existence check
if (await file.exists()) {
console.log("File exists in S3");
}

Read the data from the blob as a FormData object.

This first decodes the data from UTF-8, then parses it as a multipart/form-data body or a application/x-www-form-urlencoded body.

The type property of the blob is used to determine the format of the body.

This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.

Wrap this blob in a Bun.Image pipeline. Equivalent to new Bun.Image(this, options) — the constructor is synchronous (the underlying read happens lazily when an Image terminal is awaited), so this works on Bun.file(), Bun.s3(), fd-backed and in-memory blobs alike:

await Bun.file("photo.jpg").image().resize(400).webp().write("thumb.webp");

Read the data from the blob as a JSON object.

This first decodes the data from UTF-8, then parses it as JSON.

Generates a presigned URL for the file. Allows temporary access to the file without exposing credentials.

Configuration for the presigned URL

Presigned URL string

// Basic download URL
const url = file.presign({
expiresIn: 3600 // 1 hour
});

Creates a new S3File representing a slice of the original file. Uses HTTP Range headers for efficient partial downloads.

Starting byte offset

Ending byte offset (exclusive)

Optional MIME type for the slice

A new S3File representing the specified range

// Reading file header
const header = file.slice(0, 1024);
const headerText = await header.text();

MDN Reference

MDN Reference

Get the stat of a file in an S3-compatible storage service.

Promise resolving to S3Stat

MDN Reference

Returns a promise that resolves to the contents of the blob as a string

Uploads data to S3. Supports various input types and automatically handles large files.

The data to upload

Upload configuration options

Promise resolving to number of bytes written

// Writing string data
await file.write("Hello World", {
type: "text/plain"
});

Creates a writable stream for uploading data. Suitable for large files as it uses multipart upload.

Configuration for the upload

A NetworkSink for writing data

// Basic streaming write
const writer = file.writer({
type: "application/json"
});
writer.write('{"hello": ');
writer.write('"world"}');
await writer.end();

A class for creating and extracting tar archives with optional gzip compression.

Bun.Archive provides a fast, native implementation for working with tar archives. It supports creating archives from in-memory data or extracting existing archives to disk or memory.

Create an archive from an object:

const archive = new Bun.Archive({
"hello.txt": "Hello, World!",
"data.json": JSON.stringify({ foo: "bar" }),
"binary.bin": new Uint8Array([1, 2, 3, 4]),
});

Get the archive contents as a Blob.

Uses the compression settings specified when the Archive was created.

A promise that resolves with the archive data as a Blob

Get tarball as Blob:

const archive = new Bun.Archive(data);
const blob = await archive.blob();

Get the archive contents as a Uint8Array.

Uses the compression settings specified when the Archive was created.

A promise that resolves with the archive data as a Uint8Array

Get tarball bytes:

const archive = new Bun.Archive(data);
const bytes = await archive.bytes();

Extract the archive contents to a directory on disk.

Creates the target directory and any necessary parent directories if they don't exist. Existing files will be overwritten.

The directory path to extract to

Optional extraction options

A promise that resolves with the number of entries extracted (files, directories, and symlinks)

Extract all entries:

const archive = new Bun.Archive(tarballBytes);
const count = await archive.extract("./extracted");
console.log(`Extracted ${count} entries`);

Get the archive contents as a Map of File objects.

Each file in the archive is returned as a File object with:

Only regular files are included; directories are not returned. File contents are loaded into memory, so for large archives consider using extract() instead.

Optional glob pattern(s) to filter files. Supports the same syntax as Bun.Glob, including negation patterns (prefixed with !). Patterns are matched against paths normalized to use forward slashes (/).

A promise that resolves with a Map where keys are file paths (always using forward slashes / as separators) and values are File objects

Get all files:

const entries = await archive.files();
for (const [path, file] of entries) {
console.log(`${path}: ${file.size} bytes`);
}

Create and write an archive directly to disk in one operation.

This is more efficient than creating an archive and then writing it separately, as it streams the data directly to disk.

The file path to write the archive to

The input data for the archive (same as new Archive())

Optional archive options including compression settings

A promise that resolves when the write is complete

Write uncompressed tarball:

await Bun.Archive.write("output.tar", {
"file1.txt": "content1",
"file2.txt": "content2",
});

Configuration options for S3 operations

The access key ID for authentication. Defaults to S3_ACCESS_KEY_ID or AWS_ACCESS_KEY_ID environment variables.

The Access Control List (ACL) policy for the file. Controls who can access the file and what permissions they have.

// Setting public read access
const file = s3.file("public-file.txt", {
acl: "public-read",
bucket: "my-bucket"
});

The S3 bucket name. Defaults to S3_BUCKET or AWS_BUCKET environment variables.

// Using explicit bucket
const file = s3.file("my-file.txt", { bucket: "my-bucket" });

The Content-Disposition header value. Controls how the file is presented when downloaded.

// Setting attachment disposition with filename
const file = s3.file("report.pdf", {
contentDisposition: "attachment; filename=\"quarterly-report.pdf\""
});

The Content-Encoding header value. Specifies what content encodings have been applied to the object, for example to indicate that it has been compressed.

// Setting gzip encoding
const file = s3.file("data.json.gz", {
contentEncoding: "gzip"
});

The S3-compatible service endpoint URL. Defaults to S3_ENDPOINT or AWS_ENDPOINT environment variables.

// AWS S3
const file = s3.file("my-file.txt", {
endpoint: "https://s3.us-east-1.amazonaws.com"
});

The size of each part in multipart uploads (in bytes).

// Configuring multipart uploads
const file = s3.file("large-file.dat", {
partSize: 10 * 1024 * 1024, // 10 MiB parts
queueSize: 4 // Upload 4 parts in parallel
});

const writer = file.writer();
// ... write large file in chunks

Number of parts to upload in parallel for multipart uploads.

Increasing this value can improve upload speeds for large files but will use more memory.

The AWS region. Defaults to S3_REGION or AWS_REGION environment variables.

const file = s3.file("my-file.txt", {
bucket: "my-bucket",
region: "us-west-2"
});

When set to true, confirms that the requester knows they will be charged for the request and data transfer costs. Required for accessing objects in Requester Pays buckets.

// Accessing a file in a Requester Pays bucket
const file = s3.file("data.csv", {
bucket: "requester-pays-bucket",
requestPayer: true
});
const content = await file.text();

Number of retry attempts for failed uploads.

// Setting retry attempts
const file = s3.file("my-file.txt", {
retry: 5 // Retry failed uploads up to 5 times
});

The secret access key for authentication. Defaults to S3_SECRET_ACCESS_KEY or AWS_SECRET_ACCESS_KEY environment variables.

Optional session token for temporary credentials. Defaults to S3_SESSION_TOKEN or AWS_SESSION_TOKEN environment variables.

// Using temporary credentials
const file = s3.file("my-file.txt", {
accessKeyId: tempAccessKey,
secretAccessKey: tempSecretKey,
sessionToken: tempSessionToken
});

By default, Amazon S3 uses the STANDARD Storage Class to store newly created objects.

// Setting explicit Storage class
const file = s3.file("my-file.json", {
storageClass: "STANDARD_IA"
});

The Content-Type of the file. Automatically set based on file extension when possible.

// Setting explicit content type
const file = s3.file("data.bin", {
type: "application/octet-stream"
});

Use virtual hosted style endpoint. default to false, when true if endpoint is informed it will ignore the bucket

// Using virtual hosted style
const file = s3.file("my-file.txt", {
virtualHostedStyle: true,
endpoint: "https://my-bucket.s3.us-east-1.amazonaws.com"
});