package
Compress a complete folder or a glob list into a zip/tgz/br/7z file
npm install zip-a-folderGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 5 packages.
542.2 kB
Includes dependencies.
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:
@napi-rs/lzma)statConcurrency)high, medium, uncompressed)Added support for comma-separated glob lists. This may change the behavior for cases previously interpreted as "folder only".
Dual-module support (CJS + ESM).
Added support for destPath to control the internal path layout of created archives.
A major rewrite using:
statConcurrency)tinyglobbyCOMPRESSION_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.exclude option — an array of glob patterns for files/directories to omit from the archive. See issue #65 by @Pomax.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.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.brotliOptions for fine-grained control over brotli compression parameters.compressionLevel option (1-9) for 7z archives to control LZMA compression level.@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.@napi-rs/lzma). Specifically: ^22.20 || ^24.12 || >=25.
Node 20 and Node 23 are no longer supported.sevenZip() completes (caused by open handles in the old pure-JS worker thread)... 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... 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.RangeError that crashed the calling process.Requires Node.js
^22.20 || ^24.12 || >=25(imposed by the native@napi-rs/lzmadependency).
npm install zip-a-folderimport { zip } from 'zip-a-folder';
await zip('/path/to/folder', '/path/to/archive.zip');.tgz)import { tar } from 'zip-a-folder';
await tar('/path/to/folder', '/path/to/archive.tgz');Supported compression levels:
COMPRESSION_LEVEL.high // highest compression (default)
COMPRESSION_LEVEL.medium // balanced
COMPRESSION_LEVEL.uncompressed // STORE for zip, no-gzip for tarv5:
COMPRESSION_LEVELis now aconstobject with string values ('high','medium','uncompressed'). Thecompressionoption 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'
});| Option | Type | Description |
|---|---|---|
comment | string | ZIP file comment |
forceLocalTime | boolean | Use local timestamps instead of UTC |
forceZip64 | boolean | Always include ZIP64 headers |
namePrependSlash | boolean | Prefix all ZIP entry names with / |
store | boolean | Force STORE method (no compression) |
zlib | ZlibOptions | Passed directly to zlib.deflateRaw |
statConcurrency | number | Parallel stat workers (default: 4) |
destPath | string | Prefix inside the archive (>=3.1) |
exclude | string[] | Glob patterns for paths to omit |
customWriteStream | WriteStream | Manually handle output |
Example:
await zip('/dir', '/archive.zip', {
comment: "Created by zip-a-folder",
forceZip64: true,
namePrependSlash: true,
store: false,
statConcurrency: 16,
zlib: { level: 9 }
});| Option | Type | Description |
|---|---|---|
compressionType | 'none' | 'gzip' | 'brotli' | Compression algorithm (default: 'gzip') |
gzip | boolean | Enable gzip compression (deprecated, use compressionType) |
gzipOptions | ZlibOptions | Passed to zlib.createGzip |
brotliOptions | BrotliOptions | Passed to zlib.createBrotliCompress |
statConcurrency | number | Parallel stat workers |
exclude | string[] | Glob patterns to omit |
compression | COMPRESSION_LEVEL | Convenience preset (high, medium, uncompressed) |
await tar('/dir', '/archive.tgz', {
compressionType: 'gzip',
gzipOptions: { level: 6 }
});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 compression
await tar('/dir', '/archive.tar.br', {
compressionType: 'brotli'
});
// With compression level preset
await tar('/dir', '/archive.tar.br', {
compressionType: 'brotli',
compression: COMPRESSION_LEVEL.high
});
// With custom brotli options
await tar('/dir', '/archive.tar.br', {
compressionType: 'brotli',
brotliOptions: {
params: {
[zlib.constants.BROTLI_PARAM_QUALITY]: 11, // 0-11, higher = better compression
[zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT
}
}
});await tar('/dir', '/archive.tar', {
compressionType: 'none'
});Create 7z archives with LZMA compression using the sevenZip() function.
| Option | Type | Description |
|---|---|---|
compression | COMPRESSION_LEVEL | Convenience preset (high, medium, uncompressed) |
compressionLevel | number (1-9) | LZMA compression level (default: 5) |
statConcurrency | number | Parallel stat workers (default: 4) |
exclude | string[] | Glob patterns to omit |
customWriteStream | WriteStream | Manually handle output |
import { sevenZip } from 'zip-a-folder';
await sevenZip('/path/to/folder', '/path/to/archive.7z');import { sevenZip, COMPRESSION_LEVEL } from 'zip-a-folder';
// Using preset
await sevenZip('/dir', '/archive.7z', {
compression: COMPRESSION_LEVEL.high
});
// Using explicit level (1-9)
await sevenZip('/dir', '/archive.7z', {
compressionLevel: 9
});await sevenZip('src/**/*.ts', '/archive.7z');await sevenZip('/project', '/archive.7z', {
exclude: ['node_modules/**', '**/*.log']
});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.
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:
The first parameter may be:
Glob patterns are resolved relative to process.cwd(). Patterns that escape the working directory — those containing .. segments or absolute paths — throw an error:
await zip('**/*.json', '/archive.zip'); // OK: in-cwd glob
await zip('**/*.json, **/*.txt', '/archive2.zip'); // OK: comma-separated
await zip('../secrets/*', '/archive.zip'); // throws: escapes cwd
await zip('/etc/pass*', '/archive.zip'); // throws: absolute pathIf no files match, zip-a-folder throws:
Error: No glob match founddestPath)Adds a prefix inside the archive:
await zip('data/', '/archive.zip', { destPath: 'data/' });Resulting ZIP layout:
data/file1.txt
data/subdir/file2.txtWhen 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).
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:
await zip('/path/to/folder', '/archive.zip', {
destPath: 'folder/'
});Result layout:
folder/file1.txt
folder/sub/file2.txtdestPath: '<dirname>/'This applies equally to tar().
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:
excludeis applied to directory sources and glob sources alike.- For glob sources, the patterns are passed as additional
ignoreentries to tinyglobby.- Patterns are matched against relative paths inside the source directory (POSIX-style).
- To exclude a whole directory tree, add both
dirname/anddirname/**(or justdirname/**).
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';zlib, raw buffering)@napi-rs/lzma — native pre-built binaries for 17 platforms, WASM fallback otherwiseA recent contribution restored correct handling of file modes for Unix systems inside ZIP archives:
fs.stat().mode are passed through to the ZIP entries and preserved.This brings parity back with v3 behavior and ensures executables and other POSIX permissions are preserved when packaging for Linux/Debian and similar environments.
See PR #66: https://github.com/maugenst/zip-a-folder/pull/66
Automated tests were added to validate:
zip-a-folder includes a CLI for quick archive creation from the terminal.
# Global installation
npm install -g zip-a-folder
# Or use via npx
npx zip-a-folder ./folder ./archive.zipzip-a-folder <source> <target> [options]| 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 |
| 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 |
# Create a ZIP archive
zip-a-folder ./my-folder ./archive.zip
# Create a gzipped TAR with verbose output
zip-a-folder ./src ./backup.tgz -v
# Create a 7z archive with maximum compression
zip-a-folder ./project ./project.7z -c high
# Create archive excluding node_modules
zip-a-folder ./app ./app.zip -e "node_modules/**" -e "**/*.log"
# Create brotli-compressed TAR
zip-a-folder ./data ./data.tar.br -v
# Use glob patterns
zip-a-folder "src/**/*.ts" ./source.zip
# Quiet mode (only errors)
zip-a-folder ./folder ./archive.zip -qBy default, the CLI shows a summary with:
Use -v for detailed file-by-file progress, or -q to suppress all output.
Tests are written in Vitest with full coverage (100% statements/branches/functions/lines):
npm testCoverage 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()):
bun test ./test/tests-7z.bun.test.tsSpecial thanks to contributors:
exclude option feature request (issue #65)Additional thanks to everyone helping shape the native rewrite.