constructor

Archive.constructor

constructor Archive(
data: ArchiveInput,
options?: ArchiveOptions

Create an Archive instance from input data.

By default, archives are not compressed. Use { compress: "gzip" } to enable compression.

@param data

The input data for the archive:

  • Object: Creates a new tarball with the object's keys as file paths and values as file contents
  • Blob/TypedArray/ArrayBuffer: Wraps existing archive data (tar or tar.gz)
@param options

Archive options, including compression settings

From an object (creates uncompressed tarball):

const archive = new Bun.Archive({
  "hello.txt": "Hello, World!",
  "nested/file.txt": "Nested content",
});

Referenced types

type ArchiveInput =
| Record<string, BlobPart>
| Blob
| ArrayBufferView
| ArrayBufferLike

Input data for creating an archive. Can be:

  • An object mapping paths to file contents (string, Blob, TypedArray, or ArrayBuffer)
  • A Blob containing existing archive data
  • A TypedArray or ArrayBuffer containing existing archive data

interface ArchiveOptions

Options for creating an Archive instance.

By default, archives are not compressed. Use { compress: "gzip" } to enable compression.

// No compression (default)
new Bun.Archive(data);

// Enable gzip with default level (6)
new Bun.Archive(data, { compress: "gzip" });

// Specify compression level
new Bun.Archive(data, { compress: "gzip", level: 9 });
  • compress?: 'gzip'

    Compression algorithm to use. Only "gzip" is supported. If not specified, no compression is applied.

  • level?: number

    Compression level (1-12). Only applies when compress is set.

    • 1: Fastest compression, lowest ratio
    • 6: Default balance of speed and ratio
    • 12: Best compression ratio, slowest

class Archive

Create and extract tar archives, with optional gzip compression.

Bun.Archive builds an archive from in-memory data, or wraps an existing archive so you can extract it 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]),
});
  • blob(): Promise<Blob>;

    Get the archive contents as a Blob.

    Uses the compression settings specified when the Archive was created.

    @returns

    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.

    @returns

    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();
  • path: string,
    options?: ArchiveExtractOptions
    ): Promise<number>;

    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 are overwritten.

    @param path

    The directory path to extract to

    @param options

    Optional extraction options

    @returns

    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`);
  • glob?: string | readonly string[]
    ): Promise<Map<string, File>>;

    Get the archive contents as a Map of File objects.

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

    • name: The file path within the archive
    • lastModified: The file's modification time from the archive
    • Standard Blob methods (text(), arrayBuffer(), stream(), etc.)

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

    @param glob

    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 (/).

    @returns

    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`);
}
  • static write(
    path: string,
    data: Archive | ArchiveInput,
    options?: ArchiveOptions
    ): Promise<void>;

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

    The data streams directly to disk, which is more efficient than creating an archive and then writing it separately.

    @param path

    The file path to write the archive to

    @param data

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

    @param options

    Optional archive options including compression settings

    @returns

    A promise that resolves when the write is complete

    Write uncompressed tarball:

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