Lerna Symlink Binary

An internal Lerna tool for symlinking binary executables from source packages to destination packages' node_modules/.bin directories. This utility enables cross-package executable access in monorepos by creating symbolic links for declared binaries, supporting Lerna's internal package management workflows.

Package Information

• Package Name: @lerna/symlink-binary
• Package Type: npm
• Language: JavaScript (CommonJS)
• Installation: npm install @lerna/symlink-binary
• Node.js Support: ^14.15.0 || >=16.0.0
• TypeScript: No built-in types; uses JSDoc for type information

Core Imports

const { symlinkBinary } = require("@lerna/symlink-binary");

Basic Usage

const { symlinkBinary } = require("@lerna/symlink-binary");
const { Package } = require("@lerna/package");

// Using path strings
await symlinkBinary("/path/to/source-package", "/path/to/dest-package");

// Using Package instances
const srcPackage = Package.lazy("/path/to/source-package");
const destPackage = Package.lazy("/path/to/dest-package");
await symlinkBinary(srcPackage, destPackage);

Capabilities

Binary Symlinking

Creates symbolic links for binary executables from a source package to the destination package's node_modules/.bin directory. Handles all declared binaries in the source package's bin field, creating appropriate symlinks even if the binaries don't exist yet (anticipating build-time generation).

/**
 * Symlink bins of srcPackage to node_modules/.bin in destPackage
 * @param {Object|string} srcPackageRef - Source package reference (Package instance or path string)
 * @param {Object|string} destPackageRef - Destination package reference (Package instance or path string)  
 * @returns {Promise} Promise that resolves when all symlinks are created successfully
 */
function symlinkBinary(srcPackageRef, destPackageRef);

Parameters:

• srcPackageRef (Object|string): Source package reference. Can be a Package instance or absolute path string to the source package directory.
• destPackageRef (Object|string): Destination package reference. Can be a Package instance or absolute path string to the destination package directory.

Returns:

• Promise: Resolves when all symlinks are created successfully. Resolves immediately if the source package has no declared binaries.

Behavior:

• Automatically converts path strings to Package instances using Package.lazy() - this provides lazy loading of package metadata
• Reads binary declarations from the source package's bin field in package.json
• Handles contents property: if the source package has a contents field, resolves binaries relative to that subdirectory instead of package root
• Creates symbolic links for all declared binaries, even if the binary files don't exist yet (anticipates build-time generation)
• Creates the destination's node_modules/.bin directory if it doesn't exist using fs.mkdirp()
• Uses concurrent processing via p-map for multiple symlink operations
• Creates executable symlinks using createSymlink(src, dst, "exec") - the "exec" type ensures proper executable permissions
• Preserves existing symlinks when adding new ones
• Gracefully handles packages without binary declarations (returns resolved Promise immediately)

Usage Examples:

const { symlinkBinary } = require("@lerna/symlink-binary");

// Basic path-based usage
await symlinkBinary(
  "/workspace/packages/cli-tool", 
  "/workspace/packages/app"
);

// Using with Package instances  
const { Package } = require("@lerna/package");
const srcPkg = Package.lazy("/workspace/packages/cli-tool");
const destPkg = Package.lazy("/workspace/packages/app"); 
await symlinkBinary(srcPkg, destPkg);

// Multiple sequential operations
await symlinkBinary("/workspace/tools/build-tool", "/workspace/app");
await symlinkBinary("/workspace/tools/lint-tool", "/workspace/app");
// Both tools' binaries will be available in /workspace/app/node_modules/.bin/

// Working with packages that have a 'contents' field
// If source package.json has "contents": "dist", binaries resolve from /workspace/tools/compiled-tool/dist/
await symlinkBinary("/workspace/tools/compiled-tool", "/workspace/app");

Error Handling: The function will reject the returned Promise if:

• Package paths are invalid or don't exist
• Package.lazy() fails to load package metadata (e.g., missing package.json)
• File system permissions prevent symlink creation
• Destination directory cannot be created (permission issues)
• The createSymlink operation fails (e.g., source file doesn't exist and can't be linked)
• Concurrent symlink operations fail due to filesystem conflicts

Dependencies

• @lerna/create-symlink: Creates symbolic links with proper executable permissions
• @lerna/package: Provides Package class for package metadata handling
• fs-extra: Enhanced file system operations, specifically mkdirp for directory creation
• p-map: Concurrent promise mapping for parallel symlink operations