BuildDocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Coconstructor
Bun

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

Optional archive options including compression settings. Defaults to no compression if omitted.

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. Currently 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

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]),
});
  • 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 will be 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 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.

    @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",
});