nexus-debug-frontend

name	nexus-debug-frontend
description	Troubleshooting steps and debugging protocols for Next.js (App Router), React state, and React Flow visualization in Project Nexus. Use this when fixing UI bugs, routing errors, or hydration mismatches.

Next.js & React Debugging Protocol

1. Server vs. Client Boundary Errors

• Symptom: "Event handlers cannot be passed to Client Component props" or "useState is not defined".
• Action: Ensure any component using hooks (useState, useEffect), onClick handlers, or browser APIs has "use client" at the very top of the file.
• Action: If passing data from a Server Component to a Client Component, ensure all props are serializable (no functions, dates must be strings).

2. Next.js Caching & Stale Data

• Symptom: New data is saved to Supabase, but the /dashboard still shows old data.
• Action: Next.js aggressively caches route segments. Use revalidatePath('/dashboard') after a mutation, or explicitly opt out of caching in the page using export const dynamic = 'force-dynamic';.

3. React Flow Rendering Issues

• Symptom: Nodes overlap completely, or the canvas is blank/invisible.
• Action: Ensure the parent container of the <ReactFlow /> component has strict dimensions (e.g., h-full w-full with a fixed height wrapper).
• Action: If using auto-layout (dagre), ensure the layout function runs after the nodes are fetched and mapped.

4. Hydration Mismatches

• Symptom: "Text content does not match server-rendered HTML."
• Action: Check for browser-only APIs (window, localStorage) being executed during the initial server render. Wrap them in a useEffect or check typeof window !== 'undefined'.