This section contains a series of hands-on tutorials that explore various lockfile versioning scenarios. The demo content can be checked out from this repo:
The demo packages have names like
They are not real packages; instead you publish them to a Verdaccio service
that is running on your
http://localhost network, which is used by
rush install in the demo branches.
Preparing the Verdaccio environment
If you want to invoke
rush install or
rush update in the demo branches, the Verdaccio
NPM registry service must be running. Launch it like this:
If you haven't done so already, install Rush and PNPM tools 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 @microsoft/rush
npm install -g pnpm
mainbranch of the lockfile-explorer-demos repository. Since you'll need two clones of the repository, we recommend to name this folder
git clone https://github.com/microsoft/lockfile-explorer-demos.git lockfile-explorer-demos-verdaccio
Use the PNPM package manager to install the tooling dependencies:
Launch the Verdaccio service:
In a separate shell window run
pnpm publish-allto publish all of the demo NPM packages to
# (Open a separate shell window, since "pnpm start" is still running from step 3)
# The packages are published into Verdaccio's database, which is stored
# in ./temp/verdaccio/storage
Now that Verdaccio is running, proceed to the "Checking out a demo branch" section below.
Deleting the Verdaccio database
pnpm publish-allsees that a given package was already published, it will skip it. If you want to experiment with modifying one of the demo package.json files, you MUST delete the Verdaccio database before redoing
- Stop the service if it's already running (CTRL+C)
- Delete the temporary files
rm -Rf temp
- Now you can redo the steps above ("Preparing the Verdaccio environment")
Checking out a demo branch
Is your "rush install" stalling with ECONNREFUSED warnings?
WARN GET http://127.0.0.1:54321/@rushstack/p/-/p-2.0.3.tgz error (ECONNREFUSED).
Will retry in 10 seconds. 2 retries left.
How to fix it: Make sure Verdaccio is running! See above.
Here's the steps for checking out the
demo/sample-1 branch. Other branches can be checked out
in the same way.
We'll need a second clone for checking out branches. The documentation assumes this one is called
mainbranch clone is
git clone https://github.com/microsoft/lockfile-explorer-demos.git lockfile-explorer-demos
Check out the demo branch:
# We occasionally update the demos, so make sure you have the latest branch
# WARNING: THIS COMMAND WILL DELETE ANY LOCAL CHANGES YOU MADE
git checkout -f -B demo/sample-1 remotes/origin/demo/sample-1
Install the NPM packages using Rush:
# Verdaccio must be running for this command!
# If you made changes to package.json, use "rush update --full" here instead
# NOTE: If Rush complains that package checksum hashes have changed, you may need
# to do "rush purge" first.
The GitHub branch for each scenario will be labeled like this:
GitHub checkout branch: demo/sample-1
The lockfile is always found in Rush's standard location of the branch: common/config/rush/pnpm-lock.yaml
Each demo includes a visual illustration of the lockfile for that branch. Here's the illustration for
Some notes about the above notation:
The circled nodes (
E) are local workspace projects. In the Lockfile Explorer UI, these appear in the "Projects" tab.
The rectangular nodes (
J@1_N2) are installed external NPM package folders. In the Lockfile Explorer UI, these are called "lockfile entries" and appear on the Packages tab. The labels use a shorthand for the PNPM entry identifier; for example
J@1_N2is shorthand for
@rushstack/j/1.0.0_@firstname.lastname@example.org the above lockfile.
The vertical dashed line indicates the boundary between local workspace projects and external NPM packages.
The blue arrows indicate dependency relationships: If
B, this means
Ahas a dependency on
B. If the package.json version specifier is relevant, it is shown next to the arrow. For example,
J: ^1.0.0is shorthand for
"@rushstack/j": "^1.0.0"in the
If the package.json has
"peerDependencies", they are shown as green lines. If the peer is satisfied, then the arrow points to the resolved target lockfile entry.
Here's a quick list of the demo branches used in this tutorial series: