pnpm-plugin-alex-857

A pnpm config plugin that provides a shared catalog of dependency versions and common pnpm settings for monorepos.

What it does

• Catalog: Injects a default catalog from pnpm-catalog.json so you can use catalog: in your dependencies.
• Config: Sets strictPeerDependencies: true, hoist: false, and hoistWorkspacePackages: true.
• install-catalog: A script to add all catalog packages to your project in one go.

Developer checklist

Use this checklist when setting up a monorepo with this plugin:

• [ ] One-time setup – From the monorepo root, run pnpm run setup then pnpm install. Commit pnpm-workspace.yaml so others can run pnpm install directly.
• [ ] Add scripts – Copy the scripts block from Step 2 below into your root package.json
• [ ] Use the catalog – Add dependencies with catalog: in root or workspace package.json, or run pnpm run install:catalog to add all catalog packages at once
• [ ] Verify – Run pnpm install and confirm install and postinstall complete without errors

Why setup first? pnpm reads pnpm-workspace.yaml once at the start of pnpm install. It does not re-read after lifecycle scripts. So the catalog and configDependencies must already be in the file before pnpm install runs, or you get ERR_PNPM_CATALOG_ENTRY_NOT_FOUND_FOR_SPEC. Running pnpm run setup once writes them, then pnpm install works. Commit the updated yaml so teammates don’t need to run setup.

Setup (step by step)

Step 1: One-time setup (required when using catalog:)

From your monorepo root, run once (e.g. first clone or when you get ERR_PNPM_CATALOG_ENTRY_NOT_FOUND_FOR_SPEC):

pnpm run setup
pnpm install

Then commit pnpm-workspace.yaml. After that, anyone can run pnpm install without running setup.

pnpm run setup installs the plugin and writes packages, catalog, and configDependencies into pnpm-workspace.yaml. pnpm does not re-read that file during the same pnpm install, so the catalog must be there before you run pnpm install.

Step 2: Add scripts to your root package.json

Copy and paste this scripts block into your root package.json:

"scripts": {
    "setup": "pnpm add --config pnpm-plugin-alex-857@latest && node node_modules/.pnpm-config/pnpm-plugin-alex-857/install-workspace.js",
    "postinstall": "pnpm run install:catalog",
    "install:catalog": "node node_modules/.pnpm-config/pnpm-plugin-alex-857/install-catalog.js"
}

• setup: Run once (or when you see the catalog error). Installs the plugin and writes packages + catalog + configDependencies into pnpm-workspace.yaml. Then run pnpm install; commit the yaml so others don’t need to run setup.
• postinstall: Runs after pnpm install and adds all catalog packages to the root (if not already present).
• install:catalog: Manual script to add all catalog packages at once.

Step 3: Use the catalog in your dependencies

In your root or workspace package.json, reference catalog versions with catalog::

{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "react-router": "catalog:",
    "react-router-config": "catalog:",
    "react-router-dom": "catalog:",
    "recharts": "catalog:"
  }
}

Or add a single package from the catalog:

pnpm add react@catalog:

Updating the plugin

If there is a new update in pnpm-plugin-alex-857, developers only need to run:

pnpm install

To get the latest plugin, run pnpm run setup then pnpm install (and commit the updated pnpm-workspace.yaml if you want to pin the version).

Config applied by the plugin

When the plugin is installed, it sets:

| Setting | Value | |--------|--------| | strictPeerDependencies | true | | hoist | false | | hoistWorkspacePackages | true |

Catalog

The default catalog is defined in the plugin’s pnpm-catalog.json (e.g. react, react-dom, react-router, react-router-dom, react-router-config, recharts).

To use a custom catalog in your repo, place a pnpm-catalog.json in the project root; the install-catalog script will use it if found there.

License

ISC