or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

arborist.mdedges.mdindex.mdlinks.mdshrinkwrap.mdtree-navigation.md
tile.json

tessl/npm-npmcli--arborist

Comprehensive node_modules tree management library for npm dependency resolution and reification

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@npmcli/arborist@8.0.x

To install, run

npx @tessl/cli install tessl/npm-npmcli--arborist@8.0.0

index.mddocs/

@npmcli/arborist

@npmcli/arborist is a comprehensive Node.js library for managing dependency trees. It provides programmatic APIs for loading, analyzing, and manipulating JavaScript dependency structures with sophisticated resolution algorithms, serving as the core dependency resolution engine for npm CLI and other package management tools.

Package Information

  • Package Name: @npmcli/arborist
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install @npmcli/arborist

Core Imports

const { Arborist, Node, Link, Edge, Shrinkwrap } = require('@npmcli/arborist');

For ES modules:

import { Arborist, Node, Link, Edge, Shrinkwrap } from '@npmcli/arborist';

Basic Usage

const Arborist = require('@npmcli/arborist');

// Create arborist instance
const arb = new Arborist({
  path: '/path/to/package/root'
});

// Load actual dependency tree from disk
const actualTree = await arb.loadActual();

// Build ideal tree from package.json and lockfiles
await arb.buildIdealTree({
  add: ['express@^4.18.0'],
  saveType: 'prod'
});

// Apply changes to disk
await arb.reify();

Architecture

@npmcli/arborist is built around several key concepts:

  • Tree Types: Manages three types of dependency trees - actual (on disk), virtual (from lockfiles), and ideal (desired state)
  • Core Classes: Node, Link, and Edge objects represent packages, symbolic links, and dependency relationships
  • Resolution Engine: Implements Node.js module resolution with advanced dependency management features
  • Lockfile Management: Handles npm lockfile versions 1, 2, and 3 with bidirectional conversion
  • Workspace Support: Full monorepo and workspace-aware dependency management

Capabilities

Core Arborist Operations

Primary dependency tree management operations including loading trees, building ideal states, and applying changes to disk.

class Arborist {
  constructor(options?: ArboristOptions): Arborist;
  loadActual(options?: LoadOptions): Promise<Node>;
  loadVirtual(options?: LoadOptions): Promise<Node>;
  buildIdealTree(options?: BuildOptions): Promise<void>;
  reify(options?: ReifyOptions): Promise<void>;
  audit(options?: AuditOptions): Promise<AuditReport>;
  dedupe(options?: DedupeOptions): Promise<void>;
}

interface ArboristOptions {
  path?: string;
  cache?: string;
  registry?: string;
  dryRun?: boolean;
  force?: boolean;
  global?: boolean;
  installStrategy?: 'hoisted' | 'shallow';
  lockfileVersion?: 1 | 2 | 3 | null;
  workspaces?: string[];
  workspacesEnabled?: boolean;
}

Core Arborist Operations

Dependency Tree Navigation

Node-based tree structure with methods for navigating, querying, and manipulating package relationships in the dependency graph.

class Node {
  constructor(options?: NodeOptions): Node;
  resolve(name: string): Node | undefined;
  matches(node: Node): boolean;
  satisfies(requested: Edge): boolean;
  querySelectorAll(query: string, opts?: QueryOptions): Node[];
  
  // Properties
  name: string;
  version: string;
  path: string;
  parent: Node | null;
  children: Map<string, Node>;
  edgesOut: Map<string, Edge>;
  edgesIn: Set<Edge>;
}

Dependency Tree Navigation

Dependency Relationships

Edge objects representing dependency relationships between packages with comprehensive validation and type information.

class Edge {
  constructor(options: EdgeOptions): Edge;
  satisfiedBy(node: Node): boolean;
  reload(hard?: boolean): void;
  
  // Properties
  name: string;
  type: 'prod' | 'dev' | 'optional' | 'peer' | 'peerOptional' | 'workspace';
  spec: string;
  from: Node;
  to: Node | null;
  valid: boolean;
  error: string | null;
}

Dependency Relationships

Symbolic Links

Link objects for handling symbolic links within node_modules with proper target resolution and dependency delegation.

class Link extends Node {
  constructor(options?: LinkOptions): Link;
  
  // Properties
  isLink: true;
  target: Node;
  resolved: string;
}

Symbolic Links

Lockfile Management

Shrinkwrap class for managing package-lock.json and npm-shrinkwrap.json files with support for multiple lockfile versions.

class Shrinkwrap {
  constructor(options?: ShrinkwrapOptions): Shrinkwrap;
  static load(options?: ShrinkwrapOptions): Promise<Shrinkwrap>;
  save(options?: SaveOptions): Promise<void>;
  get(nodePath: string): any;
  add(node: Node): void;
  
  // Properties
  data: object;
  lockfileVersion: number;
  filename: string;
  tree: Node | null;
}

Lockfile Management

Types

interface LoadOptions {
  filter?: (node: Node, kidName: string) => boolean;
  forceActual?: boolean;
}

interface BuildOptions {
  add?: string[];
  rm?: string[];
  update?: boolean | { all?: boolean; names?: string[] };
  saveType?: 'prod' | 'dev' | 'optional' | 'peer' | 'peerOptional';
  saveBundle?: boolean;
  prune?: boolean;
  preferDedupe?: boolean;
  legacyBundling?: boolean;
}

interface ReifyOptions {
  save?: boolean;
  dryRun?: boolean;
  omit?: string[];
  include?: string[];
}

interface AuditOptions {
  fix?: boolean;
  packageLock?: boolean;
  filterSet?: Set<Node>;
}

interface NodeOptions {
  path?: string;
  parent?: Node;
  name?: string;
  root?: Node;
  realpath?: string;
  children?: object;
  dev?: boolean;
  optional?: boolean;
  peer?: boolean;
  extraneous?: boolean;
}

interface EdgeOptions {
  type: 'prod' | 'dev' | 'optional' | 'peer' | 'peerOptional' | 'workspace';
  name: string;
  spec: string;
  from: Node;
  accept?: string;
}

interface LinkOptions extends NodeOptions {
  target?: Node;
  realpath: string;
}

interface ShrinkwrapOptions {
  path?: string;
  lockfileVersion?: 1 | 2 | 3;
  indent?: number;
  newline?: string;
}

interface QueryOptions {
  all?: boolean;
}

interface SaveOptions {
  format?: boolean;
}