Compress a folder into ZIP/TAR/TGZ/BR/7z. This library tries to use as few dependencies as possible.
For ZIP, TAR and Brotli archives it uses the native Node.js compression (zlib).
7z uses @napi-rs/lzma — a native binary addon with pre-built binaries for 17 platforms (Linux, macOS, Windows, ARM, musl, FreeBSD) and a WASM fallback for everything else. No compiler or build tools required.
Feature overview:
ZIP archives (with optional ZIP64)
TAR archives (optionally gzipped or brotli-compressed)
7z archives with native LZMA compression (via @napi-rs/lzma)
COMPRESSION_LEVEL is now a plain const object whose values are string literals ('uncompressed', 'medium', 'high') instead of a numeric enum.
The public API (COMPRESSION_LEVEL.high, etc.) is unchanged — only the underlying type changed from a TypeScript enum to a const satisfies object. See PR #70 by @schplitt.
Added exclude option — an array of glob patterns for files/directories to omit from the archive. See issue #65 by @Pomax.
Version 6
Native Brotli compression support for TAR archives using Node.js built-in zlib.brotliCompressSync(). Create .tar.br files with the new compressionType: 'brotli' option. Brotli typically provides better compression ratios than gzip, especially for text-based content.
New 7z archive format support via the sevenZip() function. Uses pure JavaScript LZMA compression (via lzma-js library) — no external binaries required. Provides excellent compression ratios with the industry-standard 7z format.
New brotliOptions for fine-grained control over brotli compression parameters.
New compressionLevel option (1-9) for 7z archives to control LZMA compression level.
Version 7 (current)
Native LZMA via @napi-rs/lzma replaces the pure-JavaScript lzma-js for 7z compression.
Pre-built binaries are downloaded automatically at npm install for 17 platforms (Linux x64/arm64 GNU+musl, macOS x64/arm64, Windows x64/arm64/x32, FreeBSD, Android, RISC-V) with a WASM fallback for everything else. No compiler or node-gyp required.
This is a significant performance improvement — compression is 5–10× faster than the old pure-JS implementation.
Node.js ≥ 22.20 required (imposed by @napi-rs/lzma). Specifically: ^22.20 || ^24.12 || >=25.
Node 20 and Node 23 are no longer supported.
The 7z options API is unchanged — no migration needed.
Fixes issue #73: the process no longer hangs after sevenZip() completes (caused by open handles in the old pure-JS worker thread).
Version 7.0.1 (security patch)
Security fix (glob mode — all formats): Glob patterns that escape the working directory (patterns containing .. segments, or absolute paths) now throw a descriptive error instead of silently packaging files from outside cwd. Reported by Abdullah Hassan (@DragonPwn) via coordinated disclosure.
ZIP entry-name hardening: Archive entry names containing .. path segments (e.g. produced by a destPath: '../../poc' option) now throw an error at the point the entry is added, preventing Zip-Slip on extraction by tools that don't sanitize entry names.
ZIP length validation: Passing a comment or entry name whose UTF-8 byte length exceeds 65535 (the ZIP format's 16-bit limit) now throws a descriptive error instead of an uncaught RangeError that crashed the calling process.
Installation
Requires Node.js ^22.20 || ^24.12 || >=25 (imposed by the native @napi-rs/lzma dependency).
npm install zip-a-folder
Usage
Create a ZIP file
import { zip } from 'zip-a-folder';await zip('/path/to/folder', '/path/to/archive.zip');
Create a GZIP-compressed TAR file (.tgz)
import { tar } from 'zip-a-folder';await tar('/path/to/folder', '/path/to/archive.tgz');
Compression Handling
Supported compression levels:
COMPRESSION_LEVEL.high // highest compression (default)COMPRESSION_LEVEL.medium // balancedCOMPRESSION_LEVEL.uncompressed // STORE for zip, no-gzip for tar
v5:COMPRESSION_LEVEL is now a const object with string values ('high', 'medium', 'uncompressed').
The compression option accepts either the constant (COMPRESSION_LEVEL.high) or the plain string ('high') directly.
Example:
import { zip, COMPRESSION_LEVEL } from 'zip-a-folder';await zip('/path/to/folder', '/path/to/archive.zip', { compression: COMPRESSION_LEVEL.medium // or just 'medium'});
Brotli compression is supported natively via Node.js zlib module (available since Node.js v10.16.0).
Brotli typically provides better compression ratios than gzip, especially for text-based content.
import { tar, COMPRESSION_LEVEL } from 'zip-a-folder';import * as zlib from 'zlib';// Simple brotli compressionawait tar('/dir', '/archive.tar.br', { compressionType: 'brotli'});// With compression level presetawait tar('/dir', '/archive.tar.br', { compressionType: 'brotli', compression: COMPRESSION_LEVEL.high});// With custom brotli optionsawait tar('/dir', '/archive.tar.br', { compressionType: 'brotli', brotliOptions: { params: {
Note: 7z archives use native LZMA compression via @napi-rs/lzma. Pre-built binaries are automatically
selected at install time for your platform — no compiler required. A WASM fallback is used on unsupported
platforms. The 7z format stores files as a solid archive, meaning all file data is concatenated and compressed
together for better compression efficiency.
Custom Write Streams
ZIP and TAR can be written into any stream.
If customWriteStream is used, the targetFilePath can be empty or undefined.
import fs from 'fs';import { zip } from 'zip-a-folder';const ws = fs.createWriteStream('/tmp/output.zip');await zip('/path/to/folder', undefined, { customWriteStream: ws });
Important:
zip-a-folder does not validate custom streams. You must ensure:
parent directory exists
you're not writing into the source directory (to avoid recursion)
Glob Handling
The first parameter may be:
A path to a directory
A single glob
A comma-separated list of globs
Glob patterns are resolved relative to process.cwd(). Patterns that escape the working directory — those containing .. segments or absolute paths — throw an error:
When passing a directory path as the first argument (e.g. zip('/path/to/folder', '/archive.zip')), the archive by default contains the contents of that directory at the archive root (i.e. you will see the files inside folder/, not a top-level folder/ directory itself).
Include the directory itself
If you want the archive to unpack into the named folder (so the top level of the archive contains folder/), set destPath to that folder name plus a trailing slash:
Default: directory contents only (no enclosing folder)
To include the folder: use destPath: '<dirname>/'
This applies equally to tar().
Excluding Files and Directories (exclude)
The exclude option accepts an array of picomatch-style glob patterns.
Matching entries (files and directories) are omitted from the archive entirely —
when a directory is excluded its entire subtree is skipped.
import { zip } from 'zip-a-folder';const packed = await zip('/path/to/project', '/path/to/archive.zip', { exclude: [ // dot-files (.env, .DS_Store, …) '**/.*', // dot-directories (.git, .vscode, …) and their contents '**/.*/**', // build output and dependencies 'dist/**', 'dist/', 'node_modules/**', 'node_modules/', ]});
Notes:
exclude is applied to directory sources and glob sources alike.
For glob sources, the patterns are passed as additional ignore entries to tinyglobby.
Patterns are matched against relative paths inside the source directory (POSIX-style).
To exclude a whole directory tree, add both dirname/ and dirname/** (or just dirname/**).
Note: As of v4 and the modernized build, all code is bundled into a single entry file. Do not import submodules (e.g. dist/lib/mjs/core/types). Always import from the main entry point:
import { zip, tar, COMPRESSION_LEVEL } from 'zip-a-folder';
If you need types, import from the main entry point as well:
import type { ZipArchiveOptions, TarArchiveOptions } from 'zip-a-folder';
Native Implementation Notes
ZIP and TAR are written using pure Node.js (zlib, raw buffering)
File system scanning performed with a parallel stat queue
Globs handled via the tinyglobby package
Archive layout matches the original zip-a-folder for compatibility
ZIP writer supports dependency-free deflate and manual header construction
TAR writer produces POSIX ustar format with proper 512-byte block alignment
Unix Permissions Preservation in ZIP
A recent contribution restored correct handling of file modes for Unix systems inside ZIP archives:
The "Version Made By" field is now set to Unix (upper byte = 3) in the Central Directory.
File modes from fs.stat().mode are passed through to the ZIP entries and preserved.
Modes are mapped into the upper 16 bits of the "External File Attributes" field per the ZIP spec.
This brings parity back with v3 behavior and ensures executables and other POSIX permissions are preserved
when packaging for Linux/Debian and similar environments.
Central Directory "Version Made By" upper byte is 3 (Unix).
External File Attributes store the POSIX mode (both files and directories), including directory flag.
FileCollector behavior and glob handling are fully covered, pushing coverage to 100% lines/functions.
Command Line Interface (CLI)
zip-a-folder includes a CLI for quick archive creation from the terminal.
Installation
# Global installationnpm install -g zip-a-folder# Or use via npxnpx zip-a-folder ./folder ./archive.zip
Usage
zip-a-folder <source> <target> [options]
Supported Formats
Extension
Description
.zip
ZIP archive (deflate compression)
.tar
TAR archive (uncompressed)
.tgz
TAR archive with gzip compression
.tar.gz
TAR archive with gzip compression
.tar.br
TAR archive with brotli compression
.7z
7z archive with LZMA compression
Options
Option
Description
-h, --help
Show help message
-V, --version
Show version number
-v, --verbose
Show detailed progress (files being processed)
-q, --quiet
Suppress all output except errors
-c, --compression <level>
Compression preset: high, medium, uncompressed
-l, --level <number>
Compression level (1-9, format-specific)
-e, --exclude <pattern>
Glob pattern to exclude (can be used multiple times)
-d, --dest-path <path>
Destination path prefix inside archive
Examples
# Create a ZIP archivezip-a-folder ./my-folder ./archive.zip# Create a gzipped TAR with verbose outputzip-a-folder ./src ./backup.tgz -v# Create a 7z archive with maximum compressionzip-a-folder ./project ./project.7z -c high# Create archive excluding node_moduleszip-a-folder ./app ./app.zip -e "node_modules/**" -e "**/*.log"# Create brotli-compressed TARzip-a-folder ./data ./data.tar.br -v# Use glob patternszip-a-folder "src/**/*.ts" ./source.zip# Quiet mode (only errors)zip-a-folder ./folder ./archive.zip -q
Output
By default, the CLI shows a summary with:
Source and target paths
Archive format
File count
Original and compressed sizes
Compression ratio
Processing time
Use -v for detailed file-by-file progress, or -q to suppress all output.
Running Tests
Tests are written in Vitest with full coverage (100% statements/branches/functions/lines):
npm test
Coverage is reported automatically via @vitest/coverage-v8.
A separate Bun test suite covers the full test matrix under Bun's runtime and also acts as a regression guard for issue #73 (process hang after sevenZip()):