---
public-agent: true
id: pnpm-workspace
title: Meridian pnpm Workspace Standard
status: current
classification: public-agent-standard
safety: reviewed-public
---

# 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:

```text
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](https://pnpm.io/settings) and the
[pnpm workspace documentation](https://pnpm.io/workspaces).

## 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 its
`pnpm-workspace.yaml` should contain this exact reference comment before the
first setting:

```yaml
# Public standard: https://agents.meridianstack.dev/standards/pnpm-workspace
```

Keep the file in this order unless a pnpm feature requires otherwise:

1. the public-standard reference and a short repository exception comment, if
   one exists;
2. `packages` workspace globs and exclusions;
3. `catalog` and named `catalogs`;
4. resolution, catalogue and workspace behaviour;
5. build-script and dependency trust policy;
6. shell/script compatibility settings; and
7. versioning or other less-common settings.

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.

## 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.json`
`packageManager` field and must be compatible with its `engines.pnpm` range.

The normal workspace policy is:

```yaml
packages:
  - apps/*
  - packages/*
  - tools/*

catalogMode: prefer
catalogPrune: true
virtualStoreType: global
verifyDepsBeforeRun: false
shellEmulator: true

allowBuilds:
  # Only reviewed packages that need lifecycle/build scripts appear here.
  # The repository's actual allowlist is authoritative.

minimumReleaseAge: 1440
minimumReleaseAgeStrict: true
```

The important rules are:

- workspace globs include only real package roots and intentionally documented
  fixture roots; exclusions must explain why a matching directory is not a
  workspace package;
- `catalogMode: prefer` and `catalogPrune: true` keep compatible third-party
  versions convergent without forcing incompatible packages into one range;
- `virtualStoreType: global` is the current canonical spelling of
  `enableGlobalVirtualStore: true` on pnpm 11.23 and later. It improves warm
  multi-project installs, while pnpm automatically disables it in CI;
- `verifyDepsBeforeRun: false` is appropriate when a repository-owned bootstrap
  deliberately controls frozen dependency preparation before a root script;
- `shellEmulator: true` is for simple portable package-script syntax only. It
  does not turn `package.json` into a general shell-program container;
- `allowBuilds` is an explicit package map. Do not use the removed legacy
  build-script lists or `dangerouslyAllowAllBuilds` as a convenience;
- keep pnpm's one-day `minimumReleaseAge` supply-chain delay unless there is a
  reviewed reason to change it. Narrow first-party exclusions are preferable
  to a global opt-out; and
- the committed lockfile remains authoritative. Hosted installs use frozen
  dependency preparation and must not silently resolve a new graph.

The baseline records policy intent. It does not require every repository to
copy every setting when pnpm's default already supplies the same behaviour.

## 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](https://github.com/meridian-stack/site-intel/pull/174)
recorded a Windows OpenNext build failure with the global virtual store, and
Meridian issue [#1304](https://github.com/meridian-stack/meridian/issues/1304)
tracks the resolver fix that allows the compatibility bridge to be removed.

The current Meridian source therefore makes the exception explicit:

```yaml
# 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.

## 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 an approved compatible 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 do not weaken pnpm's supply-chain baseline without a narrow, documented reason. |
| `PNPM-WORKSPACE-006` | fail | Deliberate deviations identify `permanent`, `compatibility` or `temporary` class plus rationale, evidence and exit-condition semantics. |

## 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 is the implementation record for ISSUE #1775.