Zero-dependency, cross-platform, streaming tar archive library for every JavaScript runtime. Built with the browser-native Web Streams API for performance and memory efficiency.
Features
🚀 Streaming Architecture - Supports large archives without loading everything into memory.
📋 Standards Compliant - Full USTAR format support with PAX extensions. Compatible with GNU tar, BSD tar, and other standard implementations.
🗜️ Compression - Supports gzip compression and decompression with native compression streams.
📝 TypeScript First - Full type safety with detailed TypeDoc documentation.
⚡ Zero Dependencies - No external dependencies, minimal bundle size.
🌐 Cross-Platform - Works in browsers, Node.js, Cloudflare Workers, and other JavaScript runtimes.
📁 Node.js Integration - Additional high-level APIs for directory packing and extraction.
Installation
npm install modern-tar
Usage
This package provides two entry points:
modern-tar: The core, cross-platform streaming API (works everywhere).
modern-tar/fs: High-level filesystem utilities for Node.js.
Core Usage
These APIs use the Web Streams API and can be used in any modern JavaScript environment.
Simple
import { packTar, unpackTar } from 'modern-tar';// Entry bodies can be strings, bytes, Blobs, or ReadableStreams.const archive = await packTar([ { header: { name: "file.txt", size: 5 }, body: "hello" }, { header: { name: "dir/", type: "directory", size: 0 } }, { header: { name: "dir/nested.txt", size: 3 }, body: new Uint8Array([97, 98, 99]) } // "abc"]);// Unpack tar buffer into entriesconst extracted = await unpackTar(archive);const decoder = new TextDecoder();
Streaming
import { createTarDecoder } from 'modern-tar';const response = await fetch('/archive.tar');if (!response.ok) throw new Error(`Download failed: ${response.status}`);if (!response.body) throw new Error('No response body');const entries = response.body.pipeThrough(createTarDecoder());for await (const entry of entries) { if (!entry.header.name.endsWith(".txt")) {
import { unpackTar } from 'modern-tar';// Download and unpack a .tar.gz without buffering the compressed archiveconst response = await fetch('https://api.example.com/archive.tar.gz');if (!response.ok) throw new Error(`Download failed: ${response.status}`);if (!response.body) throw new Error('No response body');const entries = await unpackTar( response.body.pipeThrough(new DecompressionStream('gzip')));const decoder = new
Node.js Filesystem Usage
These APIs use Node.js streams when interacting with the local filesystem.
Simple
import { packTar, unpackTar } from 'modern-tar/fs';import { createWriteStream, createReadStream } from 'node:fs';import { pipeline } from 'node:stream/promises';// Pack a directory into a tar fileconst tarStream = packTar('./my/project');const fileStream = createWriteStream('./project.tar');await pipeline(tarStream, fileStream);// Extract a tar file to a directoryconst tarReadStream = createReadStream('./project.tar', { highWaterMark: 256 * 1024 // 256 KB for optimal performance});const extractStream = unpackTar(
Filtering and Transformation
import { packTar, unpackTar } from 'modern-tar/fs';import { createReadStream } from 'node:fs';import { pipeline } from 'node:stream/promises';// Pack with filteringconst packStream = packTar('./my/project', { filter: (filePath, stats) => !filePath.includes('node_modules'), map: (header) => ({ ...header, mode: 0o644 }), // Set all files to 644 dereference: true // Follow symlinks instead of archiving them});// Unpack with advanced optionsconst sourceStream = createReadStream('./archive.tar', {
Current benchmarks indicate we're much faster than other popular tar libraries for small file archives (packing and unpacking). On the other hand, larger files hit an I/O bottleneck resulting in similar performance between libraries.