class

bun.Archive

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.

    On Linux and macOS, nothing is written through a symlink in the target directory that is absolute or leads out of it. The promise rejects when a file entry needs such a symlink, unless options.glob is set, which skips the entry. The code of the error is "EXDEV", and its path is the path of the entry relative to the target directory.

    @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. The promise rejects once the holes read from the archive's sparse files add up to more than 1,024 times the size of the archive. Up to 64 MiB are always read, and never more than 1 GiB.

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