zip-a-folder

Compress a folder into ZIP/TAR/TGZ/BR/7z. This library is trying to with as less dependencies as possible to other libraries. For ZIP, TAR and Brotli archives it uses the native Node.js compression (zlib). 7z uses the pure JavaScript lzma-js library for LZMA compression.

Feature overview:

ZIP archives (with optional ZIP64)
TAR archives (optionally gzipped or brotli-compressed)
7z archives with LZMA compression (via lzma-js)
Fine-grained zlib/gzip/brotli/LZMA control
Globs (single or comma-separated)
Parallel directory scanning (statConcurrency)
Custom write streams
Compression presets (high, medium, uncompressed)

Incompatible Changes
Installation
Usage
- Create a ZIP file
- Create a GZIP-compressed TAR file
Compression Handling
ZIP Options
TAR / TGZ Options
7z Options
Custom Write Streams
Glob Handling
Destination Path Handling (destPath)
Excluding Files and Directories (exclude)
Module Import Structure
Native Implementation Notes
Unix Permissions Preservation in ZIP
Command Line Interface (CLI)
Running Tests
Thanks

Incompatible Changes

Version 2

Added support for comma-separated glob lists. This may change the behavior for cases previously interpreted as "folder only".

Version 3

Dual-module support (CJS + ESM).

Version 3.1

Added support for destPath to control the internal path layout of created archives.

Version 4

A major rewrite using:

Fully native ZIP writer (no dependencies)
Native TAR + gzip writer
ZIP64 support for large archives
Parallel statting (statConcurrency)
Strict internal path normalization mirroring classic zip-a-folder behavior
Native glob handling via tinyglobby

Version 5

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 (current)

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.

Installation

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        // balanced
COMPRESSION_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'
});

ZIP Options

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 }
});

TAR / TGZ / TAR.BR Options

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`)

Gzip Example

await tar('/dir', '/archive.tgz', {
    compressionType: 'gzip',
    gzipOptions: { level: 6 }
});

Brotli Example

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
        }
    }
});

Uncompressed TAR

await tar('/dir', '/archive.tar', {
    compressionType: 'none'
});

7z Options

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

Basic Example

import { sevenZip } from 'zip-a-folder';

await sevenZip('/path/to/folder', '/path/to/archive.7z');

With Compression Level

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
});

With Glob Patterns

await sevenZip('src/**/*.ts', '/archive.7z');

With Exclusions

await sevenZip('/project', '/archive.7z', {
    exclude: ['node_modules/**', '**/*.log']
});

Note: 7z archives use LZMA compression via the lzma-js library. This provides excellent compression ratios, especially for text-based content. 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

Example:

await zip('**/*.json', '/archive.zip');
await zip('**/*.json, **/*.txt', '/archive2.zip');

If no files match, zip-a-folder throws:

Error: No glob match found

Destination Path Handling (`destPath`)

Adds a prefix inside the archive:

await zip('data/', '/archive.zip', { destPath: 'data/' });

Resulting ZIP layout:

data/file1.txt
data/subdir/file2.txt

Directory Root Inclusion Semantics

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:

await zip('/path/to/folder', '/archive.zip', {
  destPath: 'folder/'
});

Result layout:

folder/file1.txt
folder/sub/file2.txt

Summary

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/**).

Inspired by issue #65 reported by @Pomax.

Module Import Structure

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)
ZIP64 support included
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.

See PR #66: #66

Automated tests were added to validate:

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 installation
npm install -g zip-a-folder

# Or use via npx
npx 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 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 -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.

Thanks

Special thanks to contributors:

@sole – initial work
@YOONBYEONGIN
@Wunschik
@ratbeard
@Xotabu4
@dallenbaldwin
@wiralegawa
@karan-gaur
@malthe
@nesvet
@schplitt – string-literal compression levels refactor (PR #70)
@Pomax – exclude option feature request (issue #65)

Additional thanks to everyone helping shape the native rewrite.

Name		Name	Last commit message	Last commit date
Latest commit History 93 Commits
.circleci		.circleci
bin		bin
dist		dist
lib		lib
test		test
.gitignore		.gitignore
README.md		README.md
biome.json		biome.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsdown.config.ts		tsdown.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

zip-a-folder

Table of Contents

Incompatible Changes

Version 2

Version 3

Version 3.1

Version 4

Version 5

Version 6 (current)

Installation

Usage

Create a ZIP file

Create a GZIP-compressed TAR file (.tgz)

Compression Handling

ZIP Options

TAR / TGZ / TAR.BR Options

Gzip Example

Brotli Example

Uncompressed TAR

7z Options

Basic Example

With Compression Level

With Glob Patterns

With Exclusions

Custom Write Streams

Glob Handling

Destination Path Handling (destPath)

Directory Root Inclusion Semantics

Include the directory itself

Summary

Excluding Files and Directories (exclude)

Module Import Structure

Native Implementation Notes

Unix Permissions Preservation in ZIP

Command Line Interface (CLI)

Installation

Usage

Supported Formats

Options

Examples

Output

Running Tests

Thanks

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Create a GZIP-compressed TAR file (`.tgz`)

Destination Path Handling (`destPath`)

Excluding Files and Directories (`exclude`)

Packages