fix(docs): cap vite below 7 (rolldown-vite) and pin mermaid transitives
CI / scan (pull_request) Successful in 2m58s
CI / commits (pull_request) Successful in 2m58s
CI / check (pull_request) Successful in 4m56s
CI / a11y (pull_request) Successful in 2m17s
Docs site / build (pull_request) Successful in 2m7s
CI / perf (pull_request) Successful in 5m54s

`pnpm docs:dev` failed with two distinct symptoms after #159 forced
vite past its vulnerable 5.x line:

1. VitePress refused to boot with `VitePress v1 is not compatible
   with rolldown-vite. Use VitePress v2 instead.` The previous
   override `vite@<6.4.2 → >=6.4.2` had no upper bound; pnpm
   resolved vitepress's `vite ^5.0.0` constraint up to vite 7.3.2,
   which uses the new rolldown bundler and is explicitly rejected
   by VitePress 1.x.

2. Even when the server eventually booted on a different port, the
   console was flooded with `Failed to resolve dependency: dayjs,
   debug, @braintree/sanitize-url, cytoscape, cytoscape-cose-bilkent`
   — the vitepress-plugin-mermaid wrapper injects those into
   `optimizeDeps.include` but they aren't reachable from the
   workspace root under pnpm's strict isolation (transitives of
   mermaid, never hoisted).

Three changes:

* `pnpm.overrides.vite` is now an **unconditional** `>=6.4.2 <7`
  range (not the previous `<6.4.2 → >=6.4.2` selector). The
  selector form was a no-op once vite had already resolved into
  7.x; the unconditional form forces a downgrade to 6.4.2 across
  every consumer (vitepress, @nx/vite, @analogjs, Vitest). All
  six top-level projects still lint, test, and build.

* `optimizeDeps.include` simplified to `['mermaid']`. Vite 6's
  dep optimizer walks Mermaid's transitives automatically once
  Mermaid itself is included, so the explicit list of children
  the previous fix carried (#157) becomes redundant.

* `dayjs`, `debug`, `@braintree/sanitize-url`, `cytoscape`,
  `cytoscape-cose-bilkent` are pinned as **top-level devDeps**.
  The vitepress-plugin-mermaid wrapper expects them at the
  workspace root; under pnpm's strict isolation a transitive of
  mermaid isn't reachable from a `optimizeDeps.include` lookup
  unless the workspace declares it. Pinning silences the
  resolution warnings without changing the resolved tree (these
  packages were already present via mermaid).

Verification: `pnpm docs:dev` boots clean on :5173, home + ADR
pages return 200, no warnings. `pnpm docs:build` succeeds in ~9 s.
`pnpm audit --audit-level=moderate` reports zero vulnerabilities.
`pnpm exec nx run-many -t lint test build` for the 6 main projects
all pass.
This commit is contained in:
Julien Gautier
2026-05-15 23:52:33 +02:00
parent e3a495ab46
commit 003dc35f71
3 changed files with 502 additions and 439 deletions
+11 -10
View File
@@ -161,18 +161,19 @@ export default withMermaid(
securityLevel: 'strict',
},
// Mermaid 11 ships its `dayjs` / `cytoscape` dependencies with a
// CommonJS `main` field but no `default` ESM export. Vite's dev
// server resolves those modules eagerly as ESM and the browser
// throws `does not provide an export named 'default'` on the
// first navigation. Telling `optimizeDeps` to pre-bundle the
// Mermaid dependency tree forces the CJS→ESM interop wrapper
// that Vite's Rollup-based build already applies in prod. The
// production build (`docs:build`) was unaffected even before
// this; this fix is exclusively for the `docs:dev` happy path.
// Pre-bundle Mermaid through Vite's dep optimizer. When this was
// first added (#157) Vite 5's dev server resolved Mermaid's CJS
// transitives (`dayjs`, `cytoscape`, `debug`, `@braintree/sanitize-url`)
// eagerly as ESM and the browser threw `does not provide an export
// named 'default'` on the first navigation. With Vite 6 — to which
// we're now pinned per ADR-0022's "stable, recognized" bar (#160
// capped vite below 7 because VitePress 1.x rejects the new
// rolldown-vite) — the pre-bundler walks Mermaid's transitives
// automatically once Mermaid itself is in `include`, so the
// explicit list of children has been collapsed.
vite: {
optimizeDeps: {
include: ['mermaid', 'dayjs', 'debug', '@braintree/sanitize-url'],
include: ['mermaid'],
},
},
}),