Meridian pnpm Workspace Standard
This standard owns Meridian's repository-level pnpm-workspace.yaml policy.
It explains the intent behind workspace settings, the boundary between package
manager configuration and other repository files, and the evidence required
when a repository deviates from the baseline.
The canonical public reference for this standard is:
https://agents.meridianstack.dev/standards/pnpm-workspace
The current pnpm 12 reference documents pnpm-workspace.yaml as the home for
workspace and non-auth configuration, while .npmrc owns authentication and
registry settings. See pnpm Settings and the
pnpm workspace documentation.
File ownership
| File | Owns | Does not own |
|---|---|---|
pnpm-workspace.yaml | Workspace package globs, catalogues, pnpm resolution/build/supply-chain settings and deliberate exceptions. | Reusable credentials, provider access policy or package-local implementation. |
Root package.json | Repository identity, packageManager, compatible engines, root scripts and root development dependencies. | pnpm settings that affect the workspace installation as a whole. |
Package package.json | Package identity, scripts, runtime/build dependencies and package-local engine constraints. | Workspace-wide catalogues or repository-wide lifecycle policy. |
.npmrc | Registry routing and authentication configuration. | General pnpm settings, secrets committed to source, or workspace package selection. |
| Provider configuration | Build/deploy commands, watch paths, provider bindings and hosted access intent. | pnpm workspace policy or package-manager credentials. |
Provider-specific build and deployment additions belong in
[pnpm-hosted-builds.md](pnpm-hosted-builds.md), which links back here for the
general workspace rules instead of redefining them.
Canonical header and section order
When a repository publishes or consumes this standard, the top of itspnpm-workspace.yaml should contain this exact reference comment before the
first setting:
# Public standard: https://agents.meridianstack.dev/standards/pnpm-workspace
Keep the file in this order unless a pnpm feature requires otherwise:
- the public-standard reference and a short repository exception comment, if
packagesworkspace globs and exclusions;catalogand namedcatalogs;- resolution, catalogue and workspace behaviour;
- build-script and dependency trust policy;
- shell/script compatibility settings; and
- versioning or other less-common settings.
one exists;
The order is for reviewability, not pnpm semantics. Do not add settings merely
to mirror this list: an omitted default is preferable to cargo-culted YAML.
Catalogue taxonomy
Catalogues coordinate dependency versions, not dependency roles. The
owning package manifest already distinguishes dependencies,devDependencies, peerDependencies and optionalDependencies; repeating
those roles as catalogue names creates a second classification that pnpm does
not interpret semantically.
Use the default catalog for the ordinary coordinated dependency line:
catalog:
react: 19.2.7
typescript: 6.0.3
vitest: 4.1.10
A package keeps its role locally while consuming the same version authority:
{
"dependencies": {
"react": "catalog:"
},
"devDependencies": {
"typescript": "catalog:",
"vitest": "catalog:"
}
}
Named catalogs are reserved for deliberate alternate compatibility,
toolchain or version lanes such as typescript7, react18 or a bounded
application compatibility set. Names such as dev, prod, development,production, runtime or test must not be used merely to mirror the
manifest section that consumes the dependency.
A named lane should be self-explanatory. When it represents a deliberate hold,
compatibility divergence or temporary split, document the applicable deviation
class, evidence and retirement/review condition under the exception model below.
A repository with one package or no useful coordinated version set does not
need to invent a catalogue for conformity. Catalogue policy applies when the
repository actually uses catalogues.
Meridian baseline
The baseline applies to a repository using pnpm 12.4 or a later approved pnpm
12 patch. The exact version remains owned by the root package.jsonpackageManager field and its engines.pnpm range must admit the governed
pnpm 12 line without crossing into pnpm 13.
A representative multi-package workspace is:
packages:
- apps/*
- packages/*
- tools/*
catalog:
# Ordinary coordinated dependency versions live here.
catalogMode: prefer
catalogPrune: true
virtualStoreType: global
verifyDepsBeforeRun: error
shellEmulator: true
update:
githubActions: true
allowBuilds:
# Only reviewed packages that need lifecycle/build scripts appear here.
# The repository's actual allow/deny map is authoritative.
minimumReleaseAge: 1440
minimumReleaseAgeStrict: true
minimumReleaseAgeIgnoreMissingTime: false
minimumReleaseAgeExclude:
- '@meridian-stack/*'
trustPolicy: no-downgrade
trustPolicyIgnoreAfter: 10080
trustLockfile: false
Meridian retains apps/*/* as an explicit workspace-structure exception: the
repository structure contract requires second-level app roots, and the pattern
preserves membership for current and future app categories. Category patterns
such as apps/websites/* and apps/workers/* are omitted because they are
subsumed by this pattern. Current discovered application roots match the broad
pattern without selecting unrelated managed package roots.
The important rules are:
- workspace globs include only real package roots in governed repository
catalogMode: preferreuses a compatible default-catalogue version whilecatalogPrune: trueremoves unused catalogue entries; pnpm 12 workspaces usevirtualStoreType: globalis Meridian's normal local-development policy for- ordinary repository commands use
verifyDepsBeforeRun: errorso stale shellEmulator: trueis for simple portable package-script syntax only. It- managed repositories with GitHub Actions normally use
allowBuildsis the explicit dependency lifecycle-script review map. Do not- explicitly configure the one-day release-age delay so strict mode is enabled,
trustPolicy: no-downgradeprotects recent releases against weaker publishing- keep
trustLockfile: falseso a frozen lockfile does not bypass the
layouts and intentionally documented fixture roots; selecting an actual
package root outside those layouts is unexpectedly broad membership and must
fail or have explicit reviewed deviation metadata;
still allowing an explicit package-level compatibility exception;
this canonical spelling rather than deprecated cleanupUnusedCatalogs;
warm multi-repository machines. pnpm disables the global virtual store in CI;
dependencies fail clearly instead of causing an implicit install during
pnpm run or pnpm exec;
does not turn package.json into a general shell-program container;
update.githubActions: true so deliberate pnpm dependency maintenance also
sees workflow-action versions. It does not grant unattended update or merge
authority;
use removed legacy build-script lists or dangerouslyAllowAllBuilds;
fail closed when publish timestamps are missing, and exclude only narrowly
reviewed first-party scopes that must be consumable immediately;
evidence while trustPolicyIgnoreAfter: 10080 bounds that comparison to one
week; and
release-age/trust verification pass.
Some security-safe pnpm defaults are intentionally not cargo-culted into every
workspace. strictDepBuilds and blockExoticSubdeps currently default totrue; do not explicitly weaken either without a documented exception.
Likewise autoInstallPeers, strictPeerDependencies, recursiveInstall,engineStrict, hoisting and linker settings are repository-specific unless a
separate standard adopts them.
Do not adopt a setting merely because a newer pnpm exposes it. For example,autoDedupe arrived after the currently governed pnpm 12.4 baseline; it should
be evaluated only when the fleet deliberately advances to a supporting version.
The baseline records policy intent. It does not require every repository to
copy an irrelevant setting, create a catalogue it does not need, or introduce a
multi-project orchestrator into a genuinely single-project repository.
A retained legacy pnpm workspace uses the setting names supported by that
governed line rather than pretending newer spellings exist. For example, an
evidence-backed pnpm 11.21 compatibility workspace retainscleanupUnusedCatalogs and enableGlobalVirtualStore; it migrates tocatalogPrune and virtualStoreType only when the documented pnpm 12 exit
condition is satisfied. The compatibility metadata and bounded engine range are
what make that legacy lane deliberate rather than silent drift.
Global virtual store compatibility exception
The global virtual store is the normal policy, not a universal mandate. A
repository may use the project-local virtual store when an OpenNext/Next build
or another tool follows pnpm's private project-local layout.
Meridian has concrete evidence for this exception: Site Intel PR #174
recorded a Windows OpenNext build failure with the global virtual store, and
Meridian issue #1304
tracks the resolver fix that allows the compatibility bridge to be removed.
The current Meridian source therefore makes the exception explicit:
# Class: compatibility. OpenNext/Next Windows builds still require the
# project-local virtual tree until deployment resolution closes ISSUE #1304.
# Evidence: Site Intel PR #174. Exit condition: released resolver plus a
# Windows proving build that passes with the global virtual store.
virtualStoreType: project
Do not turn this exception into a new default for unrelated repositories. Once
the deployment resolver and proving build satisfy the exit condition, remove
the exception and return to virtualStoreType: global.
Deviation classes
Every intentional deviation from the baseline uses one of these classes in a
nearby comment or repository-owned exception record:
| Class | Required rationale | Required evidence | Exit-condition semantics |
|---|---|---|---|
permanent | Why the baseline is not suitable for this repository or package family. | A stable design decision, supported tool contract or repeatable measurement. | State none only when the deviation is part of the intended long-term design; otherwise define the condition that retires it. |
compatibility | Which upstream/tool/runtime incompatibility requires the deviation. | Reproduction, upstream issue/PR, and a proving test or build. | Name the upstream fix/release and the proving check required before removal. |
temporary | Why the repository needs a short-lived departure now. | Current failure or rollout evidence and an owning GitHub Issue/PR. | Set an owner and review date or a concrete migration condition; temporary exceptions must not become invisible defaults. |
An exception comment should identify the class, rationale, evidence and exit
condition without restating the literal YAML value. Ordinary current catalogue
or dependency versions need no prose. A deliberate hold, compatibility pin or
non-standard divergence does require that short rationale and its removal or
review condition.
Dependency-verification exception
verifyDepsBeforeRun: error is the ordinary baseline because pnpm otherwise
defaults to automatically installing when node_modules is stale. Repository
commands should fail with an actionable dependency error rather than mutating
the install as a side effect of running a script.
A custom authenticated hosted-build bootstrap is the main reviewed exception.
It may need verifyDepsBeforeRun: false so a dependency-free root bootstrap can
obtain bounded package authentication and perform the frozen deployable-scoped
install before pnpm attempts any verification. Record that departure beside the
setting as a permanent or compatibility deviation with the rationale/evidence
required below. The hosted-build standard owns the additional provider switch
and credential boundary.
Interactive warn, prompt or implicit install modes are not the
organisation baseline. If a repository genuinely needs one, treat it as a
documented deviation rather than another default.
Hosted-build boundary
When a provider build needs a repository-controlled install/authentication
boundary, the hosted-build standard may require verifyDepsBeforeRun: false
and a provider-level dependency-install switch. That is a hosted execution
decision, not a reason to duplicate the full pnpm baseline here or to put
credentials in workspace YAML.
The hosted standard owns the following additions:
- root build/deploy command roles and built-artifact reuse;
- provider dependency-install switches and bounded package authentication;
- deployable closure and watch-path evidence;
- provider preview/non-production state; and
- separation of repository validation from live provider acceptance.
See [pnpm-hosted-builds.md](pnpm-hosted-builds.md) for those rules.
Audit contract
Workspace audits should report these stable rule identifiers. fail means the
repository is outside the standard; review means an explicit exception may
be valid but must carry the evidence and exit-condition metadata defined above.
| ID | Severity | Check |
|---|---|---|
PNPM-WORKSPACE-001 | fail | Root packageManager and engines.pnpm identify the approved bounded pnpm 12 line. |
PNPM-WORKSPACE-002 | fail | Workspace, resolution and lifecycle settings are in pnpm-workspace.yaml; registry/auth settings remain in .npmrc. |
PNPM-WORKSPACE-003 | review | Global virtual-store policy is explicit, or the project-local exception carries compatibility evidence and an exit condition. |
PNPM-WORKSPACE-004 | fail | Build scripts use explicit allowBuilds approvals without removed legacy lists or blanket allow-all. |
PNPM-WORKSPACE-005 | review | Release-age and trust policy match the supply-chain baseline or a narrow documented exception. |
PNPM-WORKSPACE-006 | fail | Deliberate deviations identify permanent, compatibility or temporary class plus the required rationale/evidence/exit semantics. |
PNPM-WORKSPACE-007 | fail | Catalogue mode/pruning and named-catalogue taxonomy match the standard; dependency-role buckets such as dev / prod are rejected. |
PNPM-WORKSPACE-008 | fail | The governed pnpm line uses canonical setting names rather than deprecated compatibility spellings. |
PNPM-WORKSPACE-009 | fail | Dependency verification uses error normally, or another mode carries a supported documented exception. |
Validation
Review a change to pnpm-workspace.yaml against this standard and the current
pnpm 12 documentation. Verify the examples against the repository's current
package manager version and one representative workspace install/build path.
For a compatibility exception, run the named proving check before removing or
changing the exception. Do not claim that a hosted build or provider state is
validated from a local pnpm command alone.
This standard was established by ISSUE #1775 and clarified for the organisation-wide rollout by ISSUE #2357.
Standards authority and sources
The machine-readable policy is published at/standards/pnpm-workspace.policy.json.
Its sourceRevision is generated from the same source revision as/standards/index.json.
Consumers should resolve the pnpm-workspace entry in that index, fetch itsauthorityUrl, and require matching sourceRevision values. The sidecar is
the versioned machine authority; this document remains the explanatory source.
The selected pnpm settings and their current spellings are checked against the
pnpm 12.x workspace settings reference, including
dependency resolution and supply-chain settings,
virtual-store settings,
build settings, and
catalogue and shell settings. The
installation reference identifies pnpm 12 as
the current release line. Meridian's 12.4 requirement is the fleet's
governed patch pin, not a claim that 12.4 is the latest pnpm release.
Nx and provider boundary
Nx is the steady-state generic project and task graph for applicable
multi-project repositories. Use affected selection as the fast validation
lane, then run the repository's full required acceptance. Cache deterministic
build, typecheck, test and quality tasks when their inputs and outputs are
complete. Never treat a cache hit as success authority for deploy, publish,
migration or live-provider mutation. Turbo files are migration evidence only:
reproduce required dependencies, inputs and outputs in Nx, validate parity,
then remove Turbo in the same bounded migration. Providers invoke stable
repository-owned root commands; Meridian remains authoritative for deployable
closure, provider configuration and watch paths.