Managing dependencies

Adding new dependencies...

...to a package

To add new dependencies to a package, run pnpm add <pkg> from the package folder. Add -D to add a devDependency.

pnpm will add and install the requested dependency. If the package is already used in the release group (the pnpm workspace), the pnpm add command will use the same version.

Read more in the pnpm add documentation.

...to a subset of packages

pnpm supports a robust package filtering syntax that can be used with most pnpm commands, including add. You can run commands only on packages that match a particular scope, depend on specific other packages, those that are in a particular directory, and even those that have been edited since a previous commit.

...to the root package of a release group

If you want to add a dependency to the root package in the release group, append -w to the pnpm add command. That is:

pnpm add @types/react @types/react-dom -D -w

Removing dependencies...

You can remove a dependency from a package by running pnpm remove <pkg> from the package folder.

Read more in the pnpm remove documentation.

Finding outdated dependencies

To find outdated dependencies, you can use pnpm outdated. It checks for outdated packages which you can then upgrade using pnpm update.

Read more in the pnpm outdated documentation.

Upgrading external dependencies

At some point, you'll need to update dependencies in the repo to a new version. Upgrading dependencies can be dangerous and destabilizing, especially when upgrading across major versions. For clarity in this section, we will use the terms "safe" and "unsafe" to mean the following:

• A safe upgrade is one that SHOULD NOT break or invalidate existing code. That is, a safe upgrade should require no code changes to upgrade.
• An unsafe upgrade is one that MAY break or invalidate existing code. You should expect to need additional code or config changes in order to integrate the new version.

We try to express the relative safety of an upgrade type with the dependency range we use with that dependency in package.json. For example, most of our dependencies are safe to update to new minor versions, so we use caret (^) dependency ranges in package.json. However, some of our dependencies, like eslint and typescript, are only safe to update to new patch versions, so we use tilde (~) dependency ranges for them.

There are two tools we use to help manage dependencies in the repo: pnpm and npm-check-updates (ncu). pnpm can do most things, but ncu offers finer-grain control over the updates. Some packages also don't use pnpm, which means ncu is the better option for those packages.

"Safe"/lockfile-only upgrades

To upgrade a dependency to the latest version allowed by the package.json dependency range, you technically don't need to update the package.json files, only the lockfiles. However, for clarity, we try to update the package.json to express the new "minimum version" expected. For example, if a dependency had the range ^14.1.2, and version 14.2.0 is available, then we prefer to update the package.json range to be ^14.2.0 even though updating the resolved version in the lockfile is enough. pnpm update will usually update package.json in addition to the lockfile.

With pnpm

To update all dependencies to their latest versions according to their dependency ranges, use pnpm update. By default it will update all dependencies, which is probably not what you want, but there are lots of filtering options.

You can also pass the -i flag to use an interactive terminal UX to select the packages to update.

Read more in the pnpm update documentation.

Example 1

Upgrade css-loader to the latest version compatible with the dependency range in package.json across all packages in the release group.

pnpm update css-loader -r

Example 2

Upgrade react and react-dom in @fluid-experimental packages only.

pnpm update react react-dom -r --filter '@fluid-experimental/*'

With npm-check-updates

TODO

"Unsafe" upgrades

With pnpm

Update typescript to the latest release across all packages in the release group. Important: this may make unsafe major version upgrades!

pnpm update typescript -r --latest

With npm-check-updates

TODO

Upgrading Fluid dependencies

While you can technically use any tool to upgrade Fluid dependencies, we recommend you use flub bump deps, which is designed for this scenario.

Using different versions of dependencies

pnpm enables us to use different versions of dependencies in different projects within the same release group (workspace in pnpm terms). While there are legitimate uses for this capability, we prefer to use the same version of dependencies across the repo whenever possible.

The pnpm dedupe command can be used to deduplicate dependencies in the lockfile. It will remove older versions from the lockfile if their dependency ranges can be met with a newer version.