Skip to content

README.md

Latest commit

 

History

History
250 lines (170 loc) · 7.77 KB

README.md

File metadata and controls

250 lines (170 loc) · 7.77 KB

@archiver/archiver

version license

A lightweight streaming interface for creating ZIP and TAR archives in Node.js.

A modern, TypeScript-first rewrite of the popular archiver package.

Comparison with archiver

archiver @archiver/archiver
Package Size 43.1 kB 38.8 kB
Install Size 9.9 MB 241.1 kB
Dependencies 66 total 3 direct, 4 total
Types @types/archiver Built-in
ESM CommonJS only ESM only

Migration

Tip

Coming from archiver? See the Migration Guide.

Install

npm install @archiver/archiver
pnpm add @archiver/archiver
yarn add @archiver/archiver
bun add @archiver/archiver

Note

Requires Node.js 24 or later.

Quick Start

Create a ZIP archive

import { createWriteStream } from "node:fs";
import { ZipArchive } from "@archiver/archiver";

const output = createWriteStream("archive.zip");
const archive = new ZipArchive({ zlib: { level: 9 } });

archive.pipe(output);

// Append a file from disk
archive.file("package.json", { name: "package.json" });

// Append a string as a file
archive.append("Hello, world!", { name: "hello.txt" });

// Append an entire directory
archive.directory("src/", "src");

// Finalize — this resolves when the archive is complete
await archive.finalize();

console.log(`Archive created: ${archive.pointer()} bytes`);

Create a TAR archive

import { createWriteStream } from "node:fs";
import { TarArchive } from "@archiver/archiver";

const output = createWriteStream("archive.tar.gz");
const archive = new TarArchive({ gzip: true, gzipOptions: { level: 6 } });

archive.pipe(output);

archive.directory("dist/", "dist");

await archive.finalize();

API

ZipArchive

import { ZipArchive } from "@archiver/archiver";

const archive = new ZipArchive(options);

ZipArchive Options

Option Type Default Description
comment string "" Archive comment
forceUTC boolean false Use UTC timestamps
forceLocalTime boolean false Force local timestamps
forceZip64 boolean false Force ZIP64 headers
namePrependSlash boolean false Prepend / to entry paths
store boolean false Use STORE method (no compression)
zlib ZlibOptions — Compression options (e.g. { level: 9 })
statConcurrency number 4 Parallel fs.stat workers
highWaterMark number 1048576 Stream buffer size (1 MB)

TarArchive

import { TarArchive } from "@archiver/archiver";

const archive = new TarArchive(options);

TarArchive Options

Option Type Default Description
gzip boolean false Enable gzip compression (.tar.gz)
gzipOptions ZlibOptions — Gzip options (e.g. { level: 6 })
statConcurrency number 4 Parallel fs.stat workers
highWaterMark number 1048576 Stream buffer size (1 MB)

Methods

All methods return this for chaining, except where noted.

append(source, data)

Add an entry from a Buffer, Stream, or string.

archive.append(Buffer.from("contents"), { name: "file.txt" });
archive.append("string contents", { name: "note.txt" });
archive.append(readableStream, { name: "data.bin" });

data properties:

Property Type Required Description
name string Yes Entry name (including path)
date Date No Entry date
mode number No File permissions
prefix string No Path prefix for the entry name
stats fs.Stats No Pre-computed stats (avoids extra fs.stat calls)

file(filepath, data?)

Add a file from disk. The file is stat'd and streamed automatically.

archive.file("/path/to/file.txt", { name: "renamed.txt" });

directory(dirpath, destpath, data?)

Add a directory recursively. Pass a function as data to filter or transform entries.

// Add everything in src/ under the "source" directory
archive.directory("src/", "source");

// Filter entries
archive.directory("project/", "project", (entry) => {
  if (entry.name.includes("node_modules")) return false;
  return entry;
});

glob(pattern, options, data)

Add files matching a glob pattern.

archive.glob("**/*.js", { cwd: "src/" }, { prefix: "scripts" });

symlink(filepath, target, mode?)

Create a symbolic link entry. Does not touch the filesystem.

archive.symlink("current", "releases/v1.0.0");

finalize()

Finalize the archive. Returns a Promise<void> that resolves when the archive is fully written. No more entries can be appended after calling this.

await archive.finalize();

abort()

Abort the archiving process. Clears pending tasks, lets active workers finish, then ends the stream.

archive.abort();

pointer()

Returns the number of bytes emitted so far.

const bytes = archive.pointer();

Events

Both ZipArchive and TarArchive extend Node.js Transform streams and emit the following events:

Event Payload Description
entry EntryData Fired after an entry is processed
progress { entries: { total, processed }, fs: { totalBytes, processedBytes } } Progress update after each entry
warning Error Non-fatal issue (e.g. stat failure)
error Error Fatal error 
archive.on("progress", (progress) => {
  console.log(
    `${progress.entries.processed}/${progress.entries.total} entries`,
  );
});

archive.on("warning", (err) => {
  console.warn(err.message);
});

Contributing

See CONTRIBUTING.md for setup instructions and guidelines.

License

MIT

Credits

This project is a modern rewrite of the original archiver package by Chris Talkington.