class

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.

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