Common Bugs

Cannot read properties of null (reading 'useRef') on first page load

Symptom: First-ever page load on a new Vite dev server crashes. Second load always works.

Cause: Vite serves un-optimized deps on the first request while the optimizer runs. React and ReactDOM load as separate module instances (CJS to ESM interop), so ReactCurrentDispatcher.current is null. Tunnel latency widens the race window. After the first request, Vite caches optimized deps in node_modules/.vite/ and it never happens again.

Fix: Pre-warm Vite before opening the browser: curl -s <url> > /dev/null

MSW parameterized route shadows static route

Symptom: Dashboard crashes with Cannot read properties of undefined (reading 'map') when MSW is active. API returns wrong response shape for /api/usage/summary.

Root cause: MSW uses first-match routing. If a parameterized route like /api/usage/:id is registered before a static route like /api/usage/summary, MSW matches the static URL against the parameterized pattern (treating “summary” as the :id param) and returns the wrong mock data.

Fix: In storybook world definitions, ensure static routes come before parameterized routes in the entities object. JavaScript preserves insertion order, and buildHandlers() iterates Object.entries(world.entities) in that order.

Prevention: When adding parameterized routes to world entities, always put more-specific static routes first. Add a comment explaining the ordering requirement.