# @publint/pack

> Utilities for packing and unpacking npm packages

Latest version **0.1.7** (published 2026-08-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @publint/pack
pnpm add @publint/pack
yarn add @publint/pack
bun add @publint/pack
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.7 |
| Published | 2026-08-19 |
| First published | 2025-01-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 1 |
| Unpacked size | 24 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1299 |
| Author | Bjorn Lu |
| Maintainers | bluwy |
| Keywords | utilities, pack, unpack, npm |

## Links

- npm: https://www.npmjs.com/package/@publint/pack
- Repository: https://github.com/publint/publint
- Issues: https://github.com/publint/publint/issues
- Funding: https://bjornlu.com/sponsor
- npm.io page: https://npm.io/package/@publint/pack

## Dependencies (1)

- [tinyexec](https://npm.io/package/tinyexec.md) ^1.3.0

## Alternatives

- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads

## Recent versions

- 0.1.7 (latest) — 2026-08-19
- 0.1.6 — 2026-07-23
- 0.1.5 — 2026-06-17
- 0.1.4 — 2026-02-05
- 0.1.3 — 2026-01-21
- 0.1.2 — 2025-03-03
- 0.1.1 — 2025-01-13
- 0.1.0 — 2025-01-06

## README

# @publint/pack

Zero-dependencies utilities for packing and unpacking npm packages. Supports:

<!-- The list below should sync with the docs at /docs/index.md -->

- npm (v9, v10, v11, v12)
- yarn (v3, v4)
- pnpm (v8, v9, v10, v11)
- bun

Older versions of these package managers may still work, but they're not officially tested. Yarn 1 is also explicitly not supported.

## API

NOTE: All `pack*` APIs support passing `opts.packageManager` to specify the package manager to use for packing, and `opts.ignoreScripts` to skip running lifecycle scripts.

### `pack()`

- **Type**: `(dir: string, opts?: PackOptions): Promise<string>`

Packs the given directory and returns the packed tarball path. Pass `opts.destination` to change the output directory of the tarball.

```js
import { pack } from '@publint/pack'

const tarballPath = await pack(process.cwd())
console.log(tarballPath)
// => '/Users/bluwy/project/project-1.0.0.tgz'
```

### `packAsList()`

- **Type**: `(dir: string, opts?: PackAsListOptions): Promise<string>`

Packs the given directory and returns a list of relative file paths that were packed.

The relative file paths should be resolved via `getPackDirectory()` if a different packed directory was used.

> [!NOTE]
> Compared to [`npm-packlist`](https://github.com/npm/npm-packlist), this API works at a higher level by invoking the package manager `pack` command to retrieve the list of files packed. While `npm-packlist` is abstracted away from `npm` to expose a more direct API, unfortunately not all package managers pack files the same way, e.g. the patterns in `"files"` may be interpreted differently. Plus, since `npm-packlist` v7, it requires `@npmcli/arborist` to be used together, which is a much larger dependency to include altogether.
>
> This package provides an alternative API that works across package managers with a much smaller package size. However, as it executes commands in a child process, it's usually slightly slower (around 200-500ms minimum depending on package manager used and the project size).

```js
import { packAsList } from '@publint/pack'

const files = await packAsList(process.cwd())
console.log(files)
// => ['src/index.js', 'package.json']
```

### `packAsJson()`

- **Type**: `(dir: string, opts?: PackAsJsonOptions): Promise<string>`

Packs the given directory with the `--json` flag and returns its stdout as JSON. You can run the `<pm> pack --json` command manually to inspect the output shape.

Relative file paths in the output can be resolved via `getPackDirectory()` if a different packed directory was used.

> [!NOTE]
> Does not work in pnpm <9.14.1 and bun as they don't support the `--json` flag.

```js
import { packAsJson } from '@publint/pack'

const json = await packAsJson(process.cwd())
console.log(json)
// => [{ "id": "project@1.0.0", ...  }]
```

### `getPackDirectory()`

- **Type**: `(dir: string, packageManager?: PackageManager): Promise<string>`

Gets the directory that is being packed by the package manager. Usually this is the same as the input `dir`, but some package managers (like pnpm) allows changing the packed directory via the `publishConfig.directory` field in `package.json`.

```js
import { getPackDirectory } from '@publint/pack'
const packDir = await getPackDirectory(process.cwd(), 'pnpm')
console.log(packDir)
// => '<cwd>/dist' (if "publishConfig.directory" is set to "dist" in package.json)
```

### `unpack()`

- **Type**: `(tarball: ArrayBuffer | ReadableStream<Uint8Array>): Promise<UnpackResult>`

Unpacks the given tarball buffer (gzip-decompress + untar). It accepts either a `ReadableStream`, `ArrayBuffer`, or `Uint8Array`. In Node.js,`ArrayBuffer` and `Uint8Array` are faster, while in browsers, `ReadableStream` is faster.

For example, when using `fetch()` in Node.js, use `response.arrayBuffer()` or `response.bytes()`, while in browsers, use `response.body` directly.

It returns an object with `files`, which is the list of unpacked files, and `rootDir`, which is the shared root directory among all files. (See JSDoc for examples)

```js
import { unpack } from '@publint/pack'

const response = await fetch('https://registry.npmjs.org/mylib/-/mylib-1.0.0.tgz')
if (!response.body) throw new Error('Failed to fetch tarball')

const result = await unpack(response.body)
console.log(result)
// => { files: [...], rootDir: 'package' }
```

## License

MIT

---
_Source: https://npm.io/package/@publint/pack · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._