README.md

@rushstack/lockfile-explorer

Rush Lockfile Explorer helps you investigate and solve version conflicts when working in a monorepo that uses the PNPM package manager. It's designed for the Rush build orchestrator, but you can also use it to analyze a standalone PNPM workspace without Rush.

Lockfile Explorer helps with problems such as:

• Understanding why multiple versions of an NPM package are appearing in your node_modules folder
• Tracing dependencies to determine which project caused an NPM package to be installed
• Finding and eliminating "doppelgangers" (multiple installations of the same version of the same package)
• Troubleshooting problems involving peer dependencies

This project is a new idea whose design is still evolving. Please provide feedback by creating a GitHub issue or posting in the Rush Stack Zulip chat room. Thank you!

Usage

Here's how to invoke the Rush Lockfile Explorer tool:

# Install the NPM package globally.
#
# (You could substitute "pnpm" or "yarn" instead of "npm" here.  To avoid confusing
# duplicate installs, always use the same tool for global installations!)
npm install -g @rushstack/lockfile-explorer

# Go to your monorepo folder
cd my-rush-repo

# Run "rush install" to ensure common/temp/node_modules is up to date.
# (If your monorepo is using PNPM without Rush, substitute "pnpm install" for this step.)
rush install

# Launch the Lockfile Explorer command line interface (CLI).
# It expects to find a Rush/PNPM workspace in your shell's current working directory.
# As a shorthand, the "lfx" alias can be used here instead of "lockfile-explorer".
lockfile-explorer

The CLI will start a Node.js service on http://localhost/ and launch your default web browser:

Lockfile Explorer main window

How it works

The web app will expect to find a Rush/PNPM workspace in the current working directory where the lockfile-explorer command was invoked. It will read files such as:

• common/config/rush/pnpm-lock.yaml - the PNPM lockfile for your monorepo
• common/config/rush/.pnpmfile.cjs - which transforms package.json files during installation
• The package.json files for your local workspace projects
• The package.json files for external packages installed in the node_modules folders.

Links

• Documentation and tutorials on the Lockfile Explorer project website
• CHANGELOG.md - Find out what's new in the latest version
• @rushstack/trace-import - a command-line tool for troubleshooting how modules are resolved by import and require()

Rush Lockfile Explorer is part of the Rush Stack family of projects.