BuildDocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Bun

class

Archive

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 = Bun.Archive.from({
  "hello.txt": "Hello, World!",
  "data.json": JSON.stringify({ foo: "bar" }),
  "binary.bin": new Uint8Array([1, 2, 3, 4]),
});
  • compress?: ArchiveCompression
    ): Promise<Blob>;

    Get the archive contents as a Blob.

    @param compress

    Optional compression: "gzip", true for gzip, or false/undefined for none

    @returns

    A promise that resolves with the archive data as a Blob

    Get uncompressed tarball:

    const blob = await archive.blob();
  • compress?: ArchiveCompression
    ): Promise<Uint8Array<ArrayBuffer>>;

    Get the archive contents as a Uint8Array.

    @param compress

    Optional compression: "gzip", true for gzip, or false/undefined for none

    @returns

    A promise that resolves with the archive data as a Uint8Array

    Get uncompressed tarball bytes:

    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 = Bun.Archive.from(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 from(
    data: ArchiveInput

    Create an Archive instance from input data.

    @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)
    @returns

    A new Archive instance

    From an object (creates new tarball):

    const archive = Bun.Archive.from({
  "hello.txt": "Hello, World!",
  "nested/file.txt": "Nested content",
});
  • static write(
    path: string,
    data: Archive | ArchiveInput,
    compress?: ArchiveCompression
    ): 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 Archive.from())

    @param compress

    Optional compression: "gzip", true for gzip, or false/undefined for none

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