Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document the PNPM Compatibility DB #81

Merged
merged 1 commit into from
Aug 9, 2022
Merged

Document the PNPM Compatibility DB #81

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
10 changes: 10 additions & 0 deletions websites/rushjs.io/docs/link/pnpm-issue-5132.md
View file
Open in desktop
@@ -0,0 +1,10 @@
---
custom_edit_url:
hide_title: true
---

Redirecting...

<head>
<meta http-equiv="refresh" content="1; url=/pages/advanced/compatibility_db/" />
</head>
24 changes: 24 additions & 0 deletions websites/rushjs.io/docs/pages/advanced/compatibility_db.md
View file
Open in desktop
@@ -0,0 +1,24 @@
---
title: PNPM Compatibility DB
---

Both Yarn and PNPM support a feature called the **Compatibility DB**, which is a public database of **package.json** fixups. These fixups solve known issues that the official maintainer of an NPM package may be unwilling to solve. (The best practice would be to avoid such packages, but often that is impractical.) Compatibility DB fixups are similar to user-authored rules found in **.pnpmfile.cjs**. They are maintained with the [@yarnpkg/extensions](https://www.npmjs.com/package/@yarnpkg/extensions) package.

PNPM's feature protects small projects from common pitfalls, but the approach has some downsides for a large monorepo:

- Hidden magic: The fixups are bundled into the PNPM binary. When trying to coordinate complex cross-project version dependencies, it is awkward for key inputs to be in a file with no Git diff, not even viewable in the GitHub website.
- Unnecessary coupling: Different versions of the `@yarnpkg/extensions` rules are bundled into different PNPM releases. This may cause churn the lockfile when upgrading or downgrading the package manager.
- Applied last: The fixups are applied after **.pnpmfile.cjs**. This means the fixed up versions aren't visible to the user's own transformations or logging, and **.pnpmfile.cjs** is no longer the final authority about version choices.

To avoid these issues, `rush install` and `rush update` always disable the Compatibility DB feature when invoking PNPM.

Details:

- Compatibility DB is implemented by PNPM versions `>= 6.32.12`, `>= 7.0.1` (but not `7.0.0`)
- The `ignore-compatibility-db` switch is implemented in newer PNPM releases: `>= 6.34.0 <7.0.01` and `>= 7.9.0`
- Compatibility DB is disabled by Rush versions `>= 5.76.0` if possible...
- ..otherwise, if the switch is missing, Rush prints a warning recommending to upgrade PNPM

The Compatibility DB fixes are useful. To apply them in your Rush repo, it's recommended to copy these settings into a proper Git-tracked file such as **.pnpmfile.cjs**.

> 💡 Feature idea: Propose an automated mechanism for syncing `@yarnpkg/extensions` into a Git-tracked file under `common/config/rush`.
1 change: 1 addition & 0 deletions websites/rushjs.io/sidebars.js
View file
Open in desktop
Expand Up @@ -67,6 +67,7 @@ const sidebars = {
'pages/advanced/config_files',
'pages/advanced/phantom_deps',
'pages/advanced/npm_doppelgangers',
'pages/advanced/compatibility_db',
'pages/advanced/preferred_versions',
'pages/advanced/incremental_builds',
'pages/advanced/watch_mode',
Expand Down