[FIX-002] React 19 Dispatcher Clash
Resolving the critical 'White Screen of Death' caused by multiple React instances.
PRID: 1112
VERIFIED
1 min read
[FIX-002] React 19 Dispatcher Multi-Instance Clash
📝 Problem Background
The application boots to a white screen with a console error: Minified React error #525. This was the most severe system-level crash in the scaffold's history.
🧪 Effort Metrics
- Attempt Count: 8+ (multiple retries and logic rollbacks)
- Time Spent: 4 hours
- Complexity: ⭐⭐⭐⭐⭐ (Extreme)
🔍 Root Cause Analysis
- Dispatcher Conflict: React 19 strictly forbids multiple instances sharing a context. Due to automatic resolution by the
importmap, TanStack and i18next were pulling in their own versioned React, causing multiple React dispatchers to exist in memory. - ESM Isolation Failure:
esm.sh's default resolution could map the same package to different URLs (e.g.,reactandreact/), leading to inconsistent import paths.
🛠️ Fix Strategy
ERP (Environmental Runtime Protection) Protocol v4:
- Forced Externalization: In the
importmap, all third-party libraries must append?external=react,react-dom. - Version Anchoring: The use of
@latestis forbidden. All React-related imports must physically point to a specific hash address like19.2.3. - Initialization Protection: Root rendering is forcibly wrapped in
startTransitionto allow rendering to be deferred until mounting is complete.
Note: This forms the physical basis for Instant Ship's ability to run across different environments.