or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-lerna--pack-directory

Pack a directory into an npm package tarball

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@lerna/pack-directory@6.4.x

To install, run

npx @tessl/cli install tessl/npm-lerna--pack-directory@6.4.0

index.mddocs/

@lerna/pack-directory

Pack a directory into an npm package tarball. This utility handles the complete packaging workflow including lifecycle script execution, file listing, and tar archive creation, primarily designed for use within the Lerna monorepo management system.

Package Information

  • Package Name: @lerna/pack-directory
  • Package Type: npm
  • Language: JavaScript
  • Node.js: ^14.15.0 || >=16.0.0
  • Installation: This is an internal Lerna utility. Install via npm install lerna for access to Lerna tools.

Core Imports

const { packDirectory } = require("@lerna/pack-directory");

For ES modules:

import { packDirectory } from "@lerna/pack-directory";

Basic Usage

const { packDirectory } = require("@lerna/pack-directory");
const { Package } = require("@lerna/package");

// Pack a package directory
const pkg = new Package(packageJsonPath, packageDirectory);
const packedData = await packDirectory(pkg, pkg.location, {
  log: require("npmlog"),
  lernaCommand: "publish"
});

console.log(`Created tarball: ${packedData.tarFilePath}`);
console.log(`Package size: ${packedData.size} bytes`);

Architecture

The package follows a sequential lifecycle approach:

  • Lifecycle Execution: Runs npm lifecycle scripts in proper order (prepublish, prepare, prepublishOnly, prepack, postpack)
  • File Collection: Uses npm-packlist to determine which files to include in the tarball
  • Archive Creation: Creates compressed tar archives with specific metadata for reproducible builds
  • Integration: Works seamlessly with other Lerna utilities for package management

Capabilities

Pack Directory

Creates a tarball from a directory suitable for npm publishing, with full lifecycle script execution and metadata generation.

/**
 * Pack a directory suitable for publishing, writing tarball to a tempfile
 * @param {Package|string} pkg - Package instance or path to manifest
 * @param {string} dir - Directory to pack  
 * @param {PackConfig} options - Configuration options
 * @returns {Promise<PackedData>} Packed tarball metadata object
 */
function packDirectory(pkg, dir, options);

Parameters:

  • pkg (Package|string): Package instance from @lerna/package or path to package.json
  • dir (string): Directory path to pack (typically the package root directory)
  • options (PackConfig): Configuration object controlling packing behavior

Returns: Promise resolving to a PackedData object containing tarball metadata.

Usage Example:

const { packDirectory } = require("@lerna/pack-directory");
const { Package } = require("@lerna/package");

// Using Package instance
const pkg = new Package("/path/to/package.json", "/path/to/package");
const result = await packDirectory(pkg, pkg.location, {
  log: require("npmlog"),
  lernaCommand: "publish",
  ignorePrepublish: false
});

// Using string path
const result = await packDirectory(
  "/path/to/package.json",
  "/path/to/package", 
  { log: require("npmlog") }
);

Types

/**
 * Configuration object for packDirectory function
 * @typedef {Object} PackConfig
 * @property {typeof log} [log] - Logger instance (defaults to npmlog)
 * @property {string} [lernaCommand] - If "publish", run "prepublishOnly" lifecycle
 * @property {boolean} [ignorePrepublish] - Skip prepublish lifecycle scripts
 */

/**
 * Packed tarball metadata returned by packDirectory
 * @typedef {Object} PackedData
 * @property {Array} bundled - Array of bundled dependencies
 * @property {number} entryCount - Number of entries in the tarball
 * @property {string} filename - Generated tarball filename (e.g., "my-package-1.0.0.tgz")
 * @property {Array<FileEntry>} files - Array of file objects with path, size, and mode
 * @property {string} id - Package identifier in format "name@version"
 * @property {Object} integrity - Integrity hash object for verification
 * @property {string} name - Package name
 * @property {string} shasum - SHA checksum of the tarball
 * @property {number} size - Total tarball size in bytes
 * @property {string} tarFilePath - Absolute path to the generated tarball file
 * @property {number} unpackedSize - Total unpacked size in bytes
 * @property {string} version - Package version
 */

/**
 * File entry in the packed tarball
 * @typedef {Object} FileEntry
 * @property {string} path - Relative file path within the package
 * @property {number} size - File size in bytes
 * @property {string} mode - File permissions mode
 */

Lifecycle Script Integration

The packDirectory function executes npm lifecycle scripts in the following order:

  1. prepublish (unless ignorePrepublish: true)
  2. prepare
  3. prepublishOnly (only if lernaCommand === "publish")
  4. prepack
  5. postpack (after tarball creation)

Scripts are executed using @lerna/run-lifecycle with the provided logger and options.

Error Handling

The function returns a rejected Promise if:

  • Package directory or manifest cannot be read
  • Lifecycle scripts fail with non-zero exit codes
  • File listing or tar creation encounters errors
  • Temporary file operations fail

Common error scenarios:

  • Missing package.json file
  • Invalid package.json format
  • Lifecycle script failures
  • File permission issues
  • Disk space limitations