rolldown-pnpm-config

A rolldown plugin whose output is a pnpm config-dependency pnpmfile. You author your catalogs and pnpm settings as one declarative config. Run a build and you get a self-contained pnpmfile.mjs. pnpm 11 loads it and calls its updateConfig hook to merge your settings into a consuming repo.

Install

npm install -D rolldown-pnpm-config rolldown
# or
pnpm add -D rolldown-pnpm-config rolldown

The build runs on Node.js. The emitted pnpmfile.mjs targets pnpm 11 in the consuming repo — the pnpm version that loads .mjs pnpmfiles.

Quick start

A vanilla rolldown setup is three files: the config you author, a build entry that re-exports the runtime hooks and a rolldown config that runs the plugin.

Author your catalogs and pnpm settings as a plain PluginConfig object. The name field is required — use the npm name of the config package itself; it tags runtime warnings as [<name>] so consuming repos know which config dependency is speaking:

import type { PluginConfig } from "rolldown-pnpm-config";

export const plugin = {
  name: "@acme/pnpm-config",
  catalogs: {
    default: { packages: { typescript: "^5.9.0", vitest: "^4.0.0" } },
  },
  overrides: { "tar@<6.2.1": ">=6.2.1" },
  publicHoistPattern: ["@types/*"],
  allowBuilds: { esbuild: true },
  strictDepBuilds: true,
  minimumReleaseAge: { value: 1440, enforcement: "warn" },
  confirmModulesPurge: false,
} satisfies PluginConfig;

Add a build entry that re-exports the runtime hooks from the plugin's virtual pnpmfile module. The reference directive pulls in the package's shipped virtual-module types, so the import type-checks with no hand-written declaration. Save it as src/pnpmfile.ts:

/// <reference types="rolldown-pnpm-config/virtual" />
export { hooks } from "rolldown-pnpm-config/virtual/pnpmfile";

Run PnpmConfigPlugin over your authored config and point rolldown at the build entry:

import { defineConfig } from "rolldown";
import { PnpmConfigPlugin } from "rolldown-pnpm-config";
import { plugin } from "./pnpm-config.js"; // the config above, saved as pnpm-config.ts

export default defineConfig({
  input: "src/pnpmfile.ts",
  // the emitted pnpmfile runs under Node, so target node — externalizes node: builtins
  platform: "node",
  output: { file: "pnpmfile.mjs", format: "esm" },
  plugins: [PnpmConfigPlugin(plugin)],
});

Build it:

npx rolldown -c
# writes a self-contained pnpmfile.mjs to the project root

The output pulls in only Node's own builtins, so pnpm can load it without any node_modules present. Ship it as a pnpm config dependency and pnpm 11 calls its updateConfig hook to merge your settings into the consuming repo.

Keeping catalogs current

The bundled rolldown-pnpm-config upgrade command rewrites the version ranges in your config file in place. Run it with no arguments and it autodetects the config — the single top-level .ts file in the current directory that calls PnpmConfigPlugin(...):

npx rolldown-pnpm-config upgrade
# opens a radio-group table, one row per package, then on <Enter>:
# Applied <n> change(s).

The command shows an interactive table by default — every catalog package at once, one row per package, ●/○ bubbles, modeled on pnpm up -i. --yes takes the latest in-range version for every package without prompting and fails hard on any warning or unresolvable package name; --dry-run runs the identical table and skips only the write; --catalog <name> restricts the table to one catalog. Pass --preview for a non-interactive projection of what an upgrade would do, with --full to show up-to-date entries too. The output is colorized in a supporting terminal. For packages that declare a strategy, the command also resyncs their materialized peer range, preserving any prerelease identifier rather than rebuilding it from parsed version parts. See upgrading catalogs for the full surface.

Exporting to pnpm-workspace.yaml

For repos that develop the plugin itself and cannot consume it as a config dependency, rolldown-pnpm-config export materializes the managed config directly into pnpm-workspace.yaml. Pass --dry-run to print a colored canonical diff without writing; add --full to emit the entire tree rather than changed lines with context. file:, link:, workspace: and portal: overrides already present in the file are preserved by default on every run.

The rolldown-pnpm-config preview command opens an interactive tabbed view — Changes, Full and Simulated — without writing anything. In a non-interactive terminal it falls back to printing the Changes diff, so it is safe to run in CI.

The optional local field on PluginConfig adjusts managed settings for this repo's export only — the built pnpmfile and its runtime behavior are unaffected. A bare value overwrites the managed value; the directive form merges it:

local: {
  // union: add local patterns on top of the managed list
  publicHoistPattern: { strategy: "union", value: ["@acme/*"] },
  // difference: drop one managed override entry
  overrides: { strategy: "difference", value: { "lodash@<4.17.21": ">=4.17.21" } },
  // bare value: overwrite the managed field entirely
  strictDepBuilds: false,
},

publicHoistPattern also accepts excludeByRepo — a map keyed by consuming repo name — to drop specific patterns when the config runs in a named repo:

publicHoistPattern: {
  value: ["@types/*", "@acme/cli"],
  excludeByRepo: { "consumer-a": ["@acme/cli"] },
}

See exporting to pnpm-workspace.yaml for the full surface.

Distributing dependency patches

A plugin author can ship pnpm dependency patches through the plugin. Author a .patch with stock pnpm into public/patches/ — the bundler copies public/ into the published package, so the file travels with the plugin. At build the plugin discovers each patch, rewrites its path to the consumer-resolved node_modules/.pnpm-config/<name>/patches/<file>.patch and bakes it into the emitted pnpmfile. Every consumer then applies it automatically through updateConfig, with no hand-written patchedDependencies entry:

export const plugin = {
  name: "@acme/pnpm-config",
  // default once public/patches/ has files; a bare map is the manual escape hatch
  patchedDependencies: { strategy: "rewrite" },
} satisfies PluginConfig;

A sibling patches/ folder stays local to your repo and never ships. On rolldown-pnpm-config export your own pnpm-workspace.yaml gets the patches with their local on-disk paths, merged by key so sibling and hand-written entries survive. See distributing dependency patches for the full surface.

Documentation

• Getting started — Wire the plugin into a vanilla rolldown build and emit a pnpmfile.
• Using @savvy-web/bundler — The same plugin with the build wiring done for you, emitting both .mjs and .cjs.
• Concepts — What the emitted pnpmfile does: config dependencies, catalogs and the enforcement model.
• pnpm settings coverage — Every pnpm-workspace.yaml setting the plugin manages and the ones it leaves to each consumer.
• Upgrading catalogs — The upgrade CLI that rewrites catalog version ranges in place.
• Exporting to pnpm-workspace.yaml — The export and preview CLI, the local merge directive and per-repo excludeByRepo filtering.
• Distributing dependency patches — Ship pnpm patches through the plugin so every consumer applies them automatically.

License

MIT