libnpmpack

libnpmpack is a Node.js library for programmatically packing tarballs from local directories or from registry/GitHub specifications. It serves as the programmatic API behind the npm pack command, enabling developers to generate compressed .tgz archives without using the command-line interface.

Package Information

• Package Name: libnpmpack
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install libnpmpack

Core Imports

const pack = require('libnpmpack');

Basic Usage

const pack = require('libnpmpack');

// Pack from current directory
const tarball = await pack();

// Pack from a local directory
const localTar = await pack('/path/to/my-package');

// Pack from a registry spec
const registryTar = await pack('abbrev@1.0.3');

// Pack from a GitHub spec
const githubTar = await pack('isaacs/rimraf#PR-192');

// Pack with options - write to disk (must provide packDestination)
const tarball = await pack('file:.', {
  dryRun: false,
  packDestination: '/tmp',
  silent: true
});

Architecture

libnpmpack is built around several key components:

• Specification Parsing: Uses npm-package-arg to parse various package specifications (local, registry, GitHub)
• Manifest Resolution: Integrates with pacote to resolve package manifests and fetch package data
• Lifecycle Scripts: Executes prepack/postpack scripts using @npmcli/run-script for local directory packing
• Dependency Management: Uses @npmcli/arborist for dependency tree analysis
• File System Operations: Handles tarball writing with configurable destination paths

Capabilities

Package Packing

Creates npm package tarballs from various sources including local directories, registry specifications, and GitHub repositories.

/**
 * Packs a tarball from a local directory or from a registry or github spec
 * @param {string} [spec='file:.'] - Package specification to pack
 * @param {PackOptions} [opts={}] - Options for packing
 * @returns {Promise<Buffer>} - Promise that resolves to tarball data Buffer with attached metadata
 */
async function pack(spec = 'file:.', opts = {});

Types

interface PackOptions {
  /** If explicitly false, writes tarball to disk (default: undefined, no writing) */
  dryRun?: boolean;
  
  /** Directory path where to write the tarball file (required when dryRun is false) */
  packDestination?: string;
  
  /** If true, skips prepack/postpack lifecycle scripts (default: false) */
  ignoreScripts?: boolean;
  
  /** If true, runs scripts with inherit stdio instead of pipe (default: false) */
  foregroundScripts?: boolean;
  
  /** Suppresses output (default: false) */
  silent?: boolean;
  
  /** Additional pacote options (registry, cache, etc.) */
  [key: string]: any;
}

interface TarballBuffer extends Buffer {
  /** Source specification that was packed */
  from: string;
  
  /** Resolved package identifier */
  resolved: string;
  
  /** Integrity hash of the tarball */
  integrity: string;
}

Detailed API

pack(spec, opts)

Parameters

spec (string, optional)

• Default: 'file:.'
• Package specification to pack
• Supported formats:
  • Local directory: 'file:.' (current directory) or '/path/to/directory'
  • Registry spec: 'package-name@version' or 'package-name'
  • GitHub spec: 'user/repo#branch-or-tag'

opts (object, optional)

• Default: {}
• Configuration options object

Key Options

dryRun (boolean)

• Default: undefined (no file writing)
• Set to false to write tarball to disk
• When explicitly false, creates file named ${name}-${version}.tgz

packDestination (string)

• Default: undefined
• Directory path where tarball file should be written
• Required when dryRun: false (will throw error if undefined)

ignoreScripts (boolean)

• Default: false
• Set to true to skip prepack/postpack lifecycle scripts
• Only applies to local directory packing

foregroundScripts (boolean)

• Default: false
• Set to true to run scripts with inherit stdio instead of pipe
• Allows script output to be visible in console

silent (boolean)

• Default: false
• Suppresses output during packing process

Return Value

Returns a Promise that resolves to a Buffer containing the tarball data. The Buffer has additional properties:

• from: Source specification that was packed
• resolved: Resolved package identifier
• integrity: Integrity hash of the tarball

Lifecycle Script Behavior

For local directory packing (when spec.type === 'directory' and !opts.ignoreScripts):

1. prepack: Executed before tarball creation

   • Runs with stdio mode based on opts.foregroundScripts
   • Uses package manifest from the directory

2. postpack: Executed after tarball creation

   • Runs with stdio mode based on opts.foregroundScripts
   • Receives environment variables:
     • npm_package_from: tarball.from
     • npm_package_resolved: tarball.resolved
     • npm_package_integrity: tarball.integrity

File Writing Behavior

• By default, tarball is NOT written to disk (unless opts.dryRun === false)
• To write to disk, explicitly set opts.dryRun = false and provide packDestination
• Filename format: ${manifest.name}-${manifest.version}.tgz
• Scoped package names are normalized:
  • Remove leading @
  • Replace / with -
  • Example: @angular/core → angular-core-1.0.0.tgz
• Destination: path.resolve(opts.packDestination, filename)
• Important: packDestination is required when dryRun: false - will throw TypeError if undefined

Error Handling

The function may throw errors in the following cases:

• Invalid package specifications
• Network errors when accessing registry or GitHub
• TypeError when dryRun: false but packDestination is undefined
• File system errors during tarball writing
• Script execution errors (unless ignoreScripts: true)
• Permission errors when writing to destination directory

Usage Examples

const pack = require('libnpmpack');

// Pack current directory (no file written)
const tarball = await pack();
console.log(`Packed ${tarball.from}, size: ${tarball.length} bytes`);

// Pack and write to disk (packDestination is required)
const tarball = await pack('file:.', {
  dryRun: false,
  packDestination: './dist'
});

// Pack from registry with custom registry
const registryTar = await pack('lodash@4.17.21', {
  registry: 'https://registry.npmjs.org/'
});

// Pack from GitHub
const githubTar = await pack('lodash/lodash#4.17.21');

// Pack with script handling
const tarball = await pack('/path/to/my-package', {
  dryRun: false,
  foregroundScripts: true,  // Show script output
  packDestination: './builds'
});

// Pack without running lifecycle scripts
const tarball = await pack('file:.', {
  ignoreScripts: true,
  silent: true
});