package
Zero dependency streaming tar parser and writer for JavaScript.
npm install modern-tarGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Estimated unpacked size across 1 packages.
95.8 kB
Includes dependencies.
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.
npm install modern-tarThis 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.These APIs use the Web Streams API and can be used in any modern JavaScript environment.
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 entries
const extracted = await unpackTar(archive);
const decoder = new TextDecoder();
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 { createTarPacker } from 'modern-tar';
const { readable, controller } = createTarPacker();
const gzipResponse = new Response(
readable.pipeThrough(new CompressionStream('gzip')),
{ headers: { 'Content-Type': 'application/gzip' } }
);
const body = controller.add({ name: 'hello.txt', size: 5 });
const writer = body.getWriter();
await writer.write(new TextEncoder().encode('hello'));
await
import { unpackTar } from 'modern-tar';
// Download and unpack a .tar.gz without buffering the compressed archive
const 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
These APIs use Node.js streams when interacting with the local filesystem.
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 file
const tarStream = packTar('./my/project');
const fileStream = createWriteStream('./project.tar');
await pipeline(tarStream, fileStream);
// Extract a tar file to a directory
const tarReadStream = createReadStream('./project.tar', {
highWaterMark: 256 * 1024 // 256 KB for optimal performance
});
const extractStream = unpackTar(
import { packTar, unpackTar } from 'modern-tar/fs';
import { createReadStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
// Pack with filtering
const 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 options
const sourceStream = createReadStream('./archive.tar', {
import { packTar, type TarSource } from 'modern-tar/fs';
import { createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
// Pack multiple sources
const sources: TarSource[] = [
{ type: 'file', source: './package.json', target: 'project/package.json' },
{ type: 'directory', source: './src', target: 'project/src' },
{ type: 'content', content: 'Hello World!', target: 'project/hello.txt' },
{ type: 'content', content: '#!/bin/bash\necho "Executable"', target: 'bin/script.sh', mode: 0o755
import { packTar, unpackTar } from 'modern-tar/fs';
import { createWriteStream, createReadStream } from 'node:fs';
import { createGzip, createGunzip } from 'node:zlib';
import { pipeline } from 'node:stream/promises';
// Pack directory and compress to .tar.gz
const tarStream = packTar('./my/project');
await pipeline(tarStream, createGzip(), createWriteStream('./project.tar.gz'));
// Decompress and extract .tar.gz
const gzipStream = createReadStream('./project.tar.gz', {
highWaterMark: 256 * 1024 // 256 KB for optimal performance
});
awaitSee the API Reference.
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.
See the Results.
The core library uses the Web Streams API and requires:
If you use CompressionStream or DecompressionStream, Firefox 113+ and
Safari 16.4+ are required.
tar-stream and tar-fs - For the inspiration and test fixtures.MIT