@lerna/package-graph

What is @lerna/package-graph?

@lerna/package-graph is a utility for managing and analyzing the dependency graph of packages within a monorepo. It helps in understanding the relationships between different packages and can be used to perform operations like finding dependencies, dependents, and traversing the graph.

What are @lerna/package-graph's main functionalities?

Creating a Package Graph

This feature allows you to create a graph of packages from an array of package objects. The graph can then be used to analyze the relationships between the packages.

const { PackageGraph } = require('@lerna/package-graph');
const packages = [
  { name: 'package-a', version: '1.0.0', dependencies: { 'package-b': '^1.0.0' } },
  { name: 'package-b', version: '1.0.0', dependencies: {} }
];
const graph = new PackageGraph(packages);
console.log(graph);

Finding Package Dependencies

This feature allows you to find the dependencies of a specific package within the graph. In this example, it retrieves the dependencies of 'package-a'.

const { PackageGraph } = require('@lerna/package-graph');
const packages = [
  { name: 'package-a', version: '1.0.0', dependencies: { 'package-b': '^1.0.0' } },
  { name: 'package-b', version: '1.0.0', dependencies: {} }
];
const graph = new PackageGraph(packages);
const packageA = graph.get('package-a');
console.log(packageA.localDependencies);

Finding Package Dependents

This feature allows you to find the dependents of a specific package within the graph. In this example, it retrieves the dependents of 'package-b'.

const { PackageGraph } = require('@lerna/package-graph');
const packages = [
  { name: 'package-a', version: '1.0.0', dependencies: { 'package-b': '^1.0.0' } },
  { name: 'package-b', version: '1.0.0', dependencies: {} }
];
const graph = new PackageGraph(packages);
const packageB = graph.get('package-b');
console.log(packageB.localDependents);

Other packages similar to @lerna/package-graph

depgraph

depgraph is a tool for creating and analyzing dependency graphs. It provides similar functionality to @lerna/package-graph, such as creating graphs and finding dependencies and dependents, but it is more general-purpose and can be used outside of monorepos.

madge

madge is a JavaScript library that can create dependency graphs for JavaScript and TypeScript projects. It offers visualization features and can detect circular dependencies, which makes it a more feature-rich alternative for visualizing dependencies compared to @lerna/package-graph.

dependency-cruiser

dependency-cruiser is a tool to analyze and visualize dependencies in JavaScript and TypeScript projects. It offers extensive configuration options and can be used to enforce dependency rules, making it a more comprehensive tool for dependency management compared to @lerna/package-graph.

README

@lerna/package-graph

Lerna's internal representation of a package graph

Usage

You probably shouldn't, at least directly.

Install lerna for access to the lerna CLI.

Changelog

6.0.0 (2022-10-12)

Super fast, modern task-runner implementation for lerna run

As of version 6.0.0, Lerna will now delegate the implementation details of the lerna run command to the super fast, modern task-runner (powered by Nx) by default.

If for some reason you wish to opt in to the legacy task-runner implementation details (powered by p-map and p-queue), you can do so by setting "useNx": false in your lerna.json. (Please let us know via a Github issue if you feel the need to do that, however, as in general the new task-runner should just work how you expect it to as a lerna user).

Interactive configuration for lerna run caching and task pipelines via the new lerna add-caching command

When using the modern task-runner implementation described above, the way to get the most out of it is to tell it about the outputs of your various scripts, and also any relationships that exist between them (such as needing to run the build script before the test, for example).

Simply run lerna add-caching and follow the instructions in order to generate all the relevant configuration for your workspace.

You can learn more about the configuration it generates here: https://lerna.js.org/docs/concepts/task-pipeline-configuration

Automatic loading of .env files in lerna run with the new task-runner implementation

By default the modern task runner powered by Nx will automatically load .env files for you. You can set --load-env-files to false if you want to disable this behavior for any reason.

For more details about what .env files will be loaded by default please see: https://nx.dev/recipes/environment-variables/define-environment-variables

Obsolete options in lerna run with the new task-runner implementation

There are certain legacy options for lerna run which are no longer applicable to the modern task-runner. Please see full details about those flags, and the reason behind their obselence, here:

https://lerna.js.org/docs/lerna6-obsolete-options

New lerna repair command

When configuration changes over time as new versions of a tool are published it can be tricky to keep up with the changes and sometimes it's possible to miss out on optimizations as a result.

When you run the new command lerna repair, lerna will execute a series of code migrations/codemods which update your workspace to the latest and greatest best practices for workspace configuration.

The actual codemods which run will be added to over time, but for now one you might see run on your workspace is that it will remove any explicit "useNx": true references from lerna.json files, because that is no longer necessary and it's cleaner not to have it.

We are really excited about this feature and how we can use it to help users keep their workspaces up to date.