@publint/pack

@publint/pack

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

• npm (v9, v10, v11)
• yarn (v3, v4)
• pnpm (v8, v9, v10)
• 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.

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.

Compared to 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).

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.

Does not work in pnpm <9.14.1 and bun as they don't support the --json flag.

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.

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)

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