fix(clarity): dual React instance crash in SSR — sonner resolves wrong react

[janprasil]

Problem

Running tools clarity ui crashes during SSR with:

TypeError: null is not an object (evaluating 'resolveDispatcher().useState')
    at Toaster (node_modules/sonner/dist/index.mjs:1065:21)

Root Cause

Dual React instance during server-side rendering:

• sonner was only declared in the root package.json → installed in root node_modules/ → imports root react (v19.2.0)
• The clarity UI app has its own node_modules/react (v19.2.4) and react-dom (v19.2.4)
• During SSR, react-dom-server sets up its internal dispatcher on the local react instance
• When sonner's <Toaster> calls useState, it goes through the root react instance which has no dispatcher → resolveDispatcher() returns null → crash

Fix

Add sonner to src/clarity/ui/package.json dependencies so it resolves through the local node_modules/ and uses the same react instance as the rest of the app.

# src/clarity/ui/package.json
  "lucide-react": "^0.544.0",
  "react": "^19.2.1",
+ "sonner": "^2.0.7",
  "react-dom": "^19.2.1",

Then bun install in src/clarity/ui/.

Verification

After the fix, both the app and sonner resolve to the same react:

sonner → src/clarity/ui/node_modules/react/index.js
app    → src/clarity/ui/node_modules/react/index.js

Note

Any package that uses React hooks and is only in the root node_modules/ (not the dashboard's local node_modules/) will hit the same issue during SSR. Dashboard apps with their own node_modules/react must declare all React-dependent packages locally.

[janprasil]

Additional Client-Side Errors

After the SSR fix (sonner dual-react), there's a second issue when the /import route lazy-loads:

node:child_process externalized for browser

Error: Module "node:child_process" has been externalized for browser compatibility.
Cannot access "node:child_process.execSync" in client code.
    at date.ts:5:26

Import chain:

1. src/clarity/ui/src/routes/import.tsx → imports FillWeekCard
2. src/clarity/ui/src/components/FillWeekCard.tsx → import { getDaysInPeriod, subtractDay } from "@app/utils/date"
3. src/utils/date.ts line 5: import { execSync } from "node:child_process"

The client component only needs pure date math functions (getDaysInPeriod, subtractDay), but because they live in src/utils/date.ts which has a top-level import { execSync } (used only by getSystemLocale()), the entire module including the Node.js import gets bundled into the client.

Fix options (pick one):

1. Split the file: Move getSystemLocale() + execSync import into src/utils/date-locale.ts, keep pure date math in src/utils/date.ts
2. Lazy import: Replace the top-level import { execSync } with a dynamic await import("node:child_process") inside getSystemLocale()
3. Conditional import guard: Wrap execSync usage behind typeof window === "undefined" check (fragile, not recommended)

Option 1 is cleanest — zero runtime cost, no conditional logic, and date.ts becomes universally safe for client/server.

API 404/500 Errors

These are separate from the React crash — they're expected failures when Azure DevOps / Clarity configs aren't set up:

• api/workitem-type-colors → 404: loadConfig() returns null (no .claude/azure/config.json)
• api/export → 500: requireAdoConfig() throws "not configured"
• api/clarity-weeks → 500: getConfig() returns null → "Clarity not configured"

These should probably return 4xx with helpful error messages instead of 500s, but that's a separate concern.

[janprasil]

Fix Applied

Approach: Lazy require() — zero import churn, fully browser-safe date.ts.

Changes:

1. src/utils/date-locale.ts (new) — Extracted getSystemLocale() + execSync import into its own module

2. src/utils/date.ts (modified) — Removed all static imports. formatDateTime uses a lazy require("./date-locale") that only executes at call time (server/CLI only). No static import means Vite won't follow the dependency into client bundles.

3. src/clarity/ui/package.json — Added sonner as local dependency (original SSR fix)

Why lazy require() over file split + import updates:

formatDateTime is imported by ~13 CLI tool files. Moving it to date-locale.ts would require updating all of them. The lazy require approach keeps the public API identical — all existing import { formatDateTime } from "@app/utils/date" continue to work unchanged, and date.ts has zero static Node.js dependencies.