or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-lerna--list

List local packages in a Lerna monorepo with multiple output formats and filtering options

Workspace: tessl
Visibility: Public
Created: 4 months ago
Last updated: 4 months ago
Describes: pkg:npm/@lerna/list@6.6.x

To install, run

npx @tessl/cli install tessl/npm-lerna--list@6.6.0

@lerna/list

@lerna/list is a command-line tool and programmatic library for listing local packages in a Lerna monorepo. It provides multiple output formats (JSON, NDJSON, parseable, graph, columnified) and extensive filtering capabilities to help developers manage and inspect packages in multi-package repositories.

Package Information

Package Name: @lerna/list
Package Type: npm
Language: TypeScript
Installation: npm install @lerna/list or use via lerna list

Core Imports

// Import the factory function (default export)
import createListCommand from "@lerna/list";

// Import the ListCommand class
import { ListCommand } from "@lerna/list";

// Import the yargs command module
import command from "@lerna/list/command";

For CommonJS:

// Default export (factory function)
const createListCommand = require("@lerna/list");

// Named export (ListCommand class)
const { ListCommand } = require("@lerna/list");

// Command module
const command = require("@lerna/list/command");

Basic Usage

Command Line Usage

# List all public packages
lerna list

# List with detailed information
lerna list --long

# List all packages including private ones
lerna list --all

# Output as JSON
lerna list --json

# List with dependency graph
lerna list --graph

Programmatic Usage

import createListCommand from "@lerna/list";

// Create a ListCommand instance
const listCommand = createListCommand(process.argv);

// The command will execute its lifecycle methods when constructed
// through the Lerna Command base class system

Capabilities

Factory Function

Creates a new ListCommand instance for programmatic execution.

/**
 * Factory function that creates and returns a ListCommand instance
 * @param argv - Command line arguments array (process.argv format)
 * @returns ListCommand instance ready for execution
 */
function createListCommand(argv: NodeJS.Process["argv"]): ListCommand;

ListCommand Class

Main command implementation providing package listing functionality.

/**
 * Command class for listing packages in a Lerna monorepo
 * Extends the base Command class from @lerna/core
 */
class ListCommand extends Command {
  /** Command does not require git repository */
  readonly requiresGit: boolean;
  
  /** Private result storage for formatted output */
  private result: { text: string; count: number };
  
  /**
   * Initializes the command by filtering packages and formatting output
   * @returns Promise that resolves when initialization is complete
   */
  initialize(): Promise<void>;
  
  /**
   * Executes the command by outputting the formatted package list
   * and logging success message
   */
  execute(): void;
}

Command Module

Yargs command module configuration for CLI integration.

/**
 * Yargs command module for CLI integration
 */
interface CommandModule {
  /** Primary command name */
  command: "list";
  
  /** Command aliases for convenience */
  aliases: ["ls", "la", "ll"];
  
  /** Command description */
  describe: "List local packages";
  
  /**
   * Configures yargs with listable and filter options
   * @param yargs - Yargs instance to configure
   */
  builder(yargs: any): any;
  
  /**
   * Handles command execution by creating ListCommand instance
   * @param argv - Parsed command arguments
   */
  handler(argv: any): any;
}

Command Options

Output Format Options

--json: Show information as JSON array with name, version, private status, and location
--ndjson: Show information as newline-delimited JSON
--parseable / -p: Show parseable output instead of columnified view
--graph: Show dependency graph as JSON-formatted adjacency list

Display Options

--all / -a: Show private packages that are normally hidden
--long / -l: Show extended information (version and location)
--toposort: Sort packages in topological order instead of lexical by directory

Filtering Options

--scope <glob>: Include only packages with names matching the given glob pattern
--ignore <glob>: Exclude packages with names matching the given glob pattern
--no-private: Exclude packages marked as private in package.json
--since <ref>: Only include packages changed since the specified git reference
--include-dependents: Include all transitive dependents regardless of other filters
--exclude-dependents: Exclude all transitive dependents when using --since
--include-dependencies: Include all transitive dependencies regardless of other filters
--include-merged-tags: Include tags from merged branches when using --since
--include-filtered-dependencies: Include filtered dependencies in the result (deprecated, use --include-dependencies)
--include-filtered-dependents: Include filtered dependents in the result (deprecated, use --include-dependents)

Command Aliases

The list command supports several convenient aliases:

lerna list / lerna ls: Standard package listing
lerna la: Equivalent to lerna list --all (shows private packages)
lerna ll: Equivalent to lerna list --long (shows detailed information)

Output Formats

Default Format (Columnified)

package-1
package-2
package-3

Long Format (`--long`)

package-1 v1.0.0 packages/package-1
package-2 v1.0.0 packages/package-2
package-3 v1.0.0 packages/package-3

JSON Format (`--json`)

[
  {
    "name": "package-1",
    "version": "1.0.0",
    "private": false,
    "location": "/path/to/packages/package-1"
  },
  {
    "name": "package-2", 
    "version": "1.0.0",
    "private": false,
    "location": "/path/to/packages/package-2"
  }
]

NDJSON Format (`--ndjson`)

{"name":"package-1","version":"1.0.0","private":false,"location":"/path/to/packages/package-1"}
{"name":"package-2","version":"1.0.0","private":false,"location":"/path/to/packages/package-2"}

Parseable Format (`--parseable`)

Basic parseable output shows absolute paths:

/path/to/packages/package-1
/path/to/packages/package-2

With --long, parseable output includes name and version:

/path/to/packages/package-1:package-1:1.0.0
/path/to/packages/package-2:package-2:1.0.0

Private packages are marked with PRIVATE flag:

/path/to/packages/package-3:package-3:1.0.0:PRIVATE

Graph Format (`--graph`)

Shows dependency relationships as an adjacency list:

{
  "package-1": ["package-2"],
  "package-2": [],
  "package-3": ["package-1", "package-2"]
}

Types

/**
 * Base Command class from @lerna/core
 */
declare class Command {
  /** Command name derived from class name */
  name: string;
  
  /** Whether command is composed (called from other commands) */
  composed: boolean;
  
  /** Command options and configuration */
  options: any;
  
  /** Lerna project instance */
  project: Project;
  
  /** npmlog logger instance */
  logger: any;
  
  /** Package graph for the monorepo */
  packageGraph?: PackageGraph;
  
  /** Execution options */
  execOpts?: { cwd: string; maxBuffer?: number };
}

/**
 * Result object containing formatted output and count
 */
interface ListResult {
  /** Formatted text output */
  text: string;
  
  /** Number of packages found */
  count: number;
}

/**
 * Package representation from @lerna/core
 */
interface Package {
  /** Package name */
  name: string;
  
  /** Package version */
  version: string;
  
  /** Whether package is marked as private */
  private: boolean;
  
  /** Absolute path to package directory */
  location: string;
  
  /** Package dependencies */
  dependencies?: Record<string, string>;
  
  /** Package dev dependencies */
  devDependencies?: Record<string, string>;
  
  /** Package peer dependencies */
  peerDependencies?: Record<string, string>;
  
  /** Package optional dependencies */
  optionalDependencies?: Record<string, string>;
}

/**
 * Options interface for listable formatting
 */
interface ListableOptions {
  /** Show as JSON array */
  json?: boolean;
  
  /** Show as newline-delimited JSON */
  ndjson?: boolean;
  
  /** Show all packages including private */
  all?: boolean;
  
  /** Show extended information */
  long?: boolean;
  
  /** Show parseable output */
  parseable?: boolean;
  
  /** Sort topologically */
  toposort?: boolean;
  
  /** Show dependency graph */
  graph?: boolean;
}

Architecture

@lerna/list is implemented as a legacy wrapper package that provides backward compatibility while leveraging the shared Lerna command infrastructure:

Wrapper Layer: The published @lerna/list package re-exports functionality from the core Lerna command library
Command Implementation: The actual ListCommand class extends the base Command class from @lerna/core
CLI Integration: Uses yargs command modules for seamless integration with the Lerna CLI
Core Dependencies: Leverages shared utilities from @lerna/core for package filtering, formatting, and output

The command follows Lerna's standard command lifecycle:

Initialization: Filters packages based on options and formats output
Execution: Outputs the formatted results and logs success statistics

This architecture ensures consistency with other Lerna commands while providing the flexibility to use the package independently or as part of the broader Lerna toolchain.