@unsonet/pack

A fast and flexible Node.js tool for packaging files and browser extensions into .zip, .tar.gz, and .crx archives with automatic project detection, templated filenames, and cross-platform support.

---

Features

• 📦 Pack folders or files into:

  • .zip
  • .tar.gz
  • .crx (Chrome/Edge/Brave/Chromium extensions)

• 🧠 Automatic project detection (package.json, manifest.json)

• 🧹 Ignore patterns support via @unsonet/ignore-patterns

• 🧩 Template-based filenames ({{name}}, {{version}}, etc.)

• 🌍 Cross-platform (Windows / macOS / Linux)

• 🧪 CLI + programmatic API

• 🔍 Auto browser executable resolution for CRX packaging

• ⚡ Safe staging into temp directories

---

Installation

npm install @unsonet/pack

or

yarn add @unsonet/pack

---

CLI Usage

Basic

npx @unsonet/pack ./dist

Output format

npx @unsonet/pack ./dist --ext zip
npx @unsonet/pack ./dist --ext tar.gz
npx @unsonet/pack ./dist --ext crx

Multiple inputs

npx @unsonet/pack ./dist ./assets ./manifest.json

Output directory

npx @unsonet/pack ./dist --output ./release

Custom name template

npx @unsonet/pack ./dist --name "{{name}}-v{{version}}"

Ignore files

npx @unsonet/pack ./dist --ignore "node_modules,dist,test"

Or disable ignore:

--ignore null

Force overwrite

npx @unsonet/pack ./dist --force

---

CRX (Browser Extension) Packaging

Automatic browser detection

Supported browsers:

• chrome
• chromium
• edge
• brave
• opera

npx @unsonet/pack ./extension --ext crx --browser chrome

Custom browser path

npx @unsonet/pack ./extension --ext crx --browserPath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

Requirements

• Browser must support --pack-extension
• manifest.json must exist in input (or detected in project tree)

---

Programmatic API

Basic usage

import { pack } from '@unsonet/pack';

const result = await pack({
  input: './dist',
  ext: 'zip',
});

console.log(result.outputPath);

---

Multiple inputs

await pack({
  input: ['./dist', './assets'],
  ext: 'zip',
});

---

Full options

await pack({
  input: string | string[];

  output?: string;
  ext?: 'zip' | 'tar.gz' | 'crx';
  name?: string;

  force?: boolean;
  cwd?: string;

  ignore?: string | null;

  browser?: 'chrome' | 'chromium' | 'edge' | 'brave' | 'opera';
  browserPath?: string;

  startSymbols?: string;
  endSymbols?: string;
});

---

Output

The result of packaging:

interface PackResult {
  outputPath: string;
  filename: string;
  extension: 'zip' | 'tar.gz' | 'crx';
  createdAt: string;
  inputPaths: string[];
  browserPath?: string;
}

---

Filename templating

You can customize output filenames using templates:

Variables

Variable	Description
name	Project name
version	Project version
version-kebab	version with dots replaced by -
version-snake	version with dots replaced by _
folder	project folder name
timestamp	ISO timestamp safe for filenames

Example

await pack({
  input: './dist',
  name: '{{name}}-{{version}}-{{timestamp}}',
});

---

Project detection

Automatically reads:

package.json

• name
• version

manifest.json (extensions)

• detects extension mode
• reads version if present

Fallback:

• folder name
• local version

---

Ignore patterns

Uses @unsonet/ignore-patterns.

Examples:

ignore: "node_modules,dist,.git"

or

ignore: null // disables ignoring

---

CRX constraints

CRX mode requires:

• valid browser executable
• manifest.json
• valid extension structure

Throws if:

• browser not found
• manifest missing
• browser fails to generate .crx

---

Temporary staging

Internally the library:

1. Creates temp directory
2. Copies input into /payload
3. Applies ignore rules
4. Packs archive
5. Cleans up automatically

---

Platform support

Feature	Windows	macOS	Linux
ZIP	✔	✔	✔
TAR.GZ	✔	✔	✔
CRX	✔	✔	✔

---

Error handling

Common errors:

• Input path not found
• Output file already exists (use force)
• zip not installed
• tar not installed
• Browser executable not found
• Invalid extension type

---

Example workflow

import { pack } from '@unsonet/pack';

await pack({
  input: './dist',
  ext: 'zip',
  ignore: 'node_modules',
  name: '{{name}}-prod-{{version}}',
  force: true,
});

---

Binary (CLI)

After install:

pack --help

(or via npx)

---

License

MIT