From 44f8faca5d0d4705d539671c745aa7d630cfd2ee Mon Sep 17 00:00:00 2001
From: Julien Gautier <julien.gautier@apf.asso.fr>
Date: Fri, 15 May 2026 20:01:28 +0200
Subject: [PATCH] fix(docs): pre-bundle mermaid deps so the dev server resolves
 dayjs/cytoscape
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`pnpm docs:dev` rendered a blank page with `does not provide an
export named 'default'` thrown from dayjs.min.js. Mermaid 11 ships
its `dayjs`, `cytoscape`, `debug` and `@braintree/sanitize-url`
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 on the first navigation.

The production build (`docs:build`) was unaffected — Rollup's
plugin pipeline already applies the CJS→ESM interop wrapper. This
fix is exclusively for the dev happy path: `optimizeDeps.include`
forces Vite to pre-bundle the Mermaid dependency tree, which
applies the same interop shim at dev-server boot.

Caught by manual smoke of the merged docs-site chantier — the
build-time Mermaid-rendering fence in `.gitea/workflows/docs-site.yml`
didn't catch this because it only inspects production HTML.
---
 docs/.vitepress/config.mts | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 7d315ea..acb7268 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -160,5 +160,20 @@ export default withMermaid(
     mermaid: {
       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.
+    vite: {
+      optimizeDeps: {
+        include: ['mermaid', 'dayjs', 'debug', '@braintree/sanitize-url'],
+      },
+    },
   }),
 );