const [board, setBoard] = useState<Board | null>(initialBoard ?? null);

if (initialBoard?.columns) {
  // TypeScript confidently narrows to Board type
  setBoard(initialBoard);
}

2. UI/DB Synchronization Architecture

Server actions persist data to MongoDB, but UI updates require explicit client-side state management. Replace callback chains with a centralized state store (Zustand/React Query) or implement optimistic updates:

// Optimistic update pattern
const handleDrop = async (result: DropResult) => {
  const previousState = board;
  setBoard(applyDrag(result, board)); // Instant UI update
  
  try {
    await moveJobAction(result); // Server action
  } catch (error) {
    setBoard(previousState); // Rollback on failure
  }
};

3. Cache & Revalidation Strategy

revalidatePath invalidates server components but strips client-side callbacks and triggers full re-renders. Replace with granular cache control:

• Remove use cache from dynamic routes requiring real-time updates.
• Use fetch with { cache: 'no-store' } or revalidate: 0 for API calls.
• Rely on client-side state for immediate feedback, letting background revalidation handle consistency.

4. Hydration-Safe DnD Implementation

DnD Kit generates unique IDs during SSR that mismatch client-side hydration. Guard DnD rendering until client mount:

const [isMounted, setIsMounted] = useState(false);

useEffect(() => {  
  setIsMounted(true);  
}, []);

if (!isMounted) return null;

Pitfall Guide

1. useEffect setState Anti-Pattern: Initializing state inside useEffect triggers unnecessary render cycles and cascading updates. useState accepts initial values directly; reserve useEffect for side effects, subscriptions, or post-mount logic.
2. TypeScript Type Narrowing Friction: Nullable server responses (Board | null | undefined) conflict with strict state setters. Use optional chaining (?.), type predicates, or explicit null checks to guide TS inference without compromising type safety.
3. UI/DB State Desynchronization: Server actions confirm persistence but do not automatically update client state. Implement optimistic updates or integrate a state management library to bridge the gap between DB mutations and UI re-renders.
4. revalidatePath Callback Invalidation: revalidatePath forces server component re-rendering, which unmounts client components and destroys active callback references. Use it sparingly for static data; prefer client-side state updates for interactive UIs.
5. Aggressive Caching (use cache): Next.js App Router caches route segments by default. Applying use cache to dynamic, user-specific routes serves stale data across refreshes. Opt out with export const dynamic = 'force-dynamic' or route-level cache headers.
6. DnD Kit Hydration Mismatch: DnD Kit generates deterministic IDs during SSR that differ from client-side generation, causing hydration warnings. The isMounted guard defers DnD rendering to CSR, eliminating mismatches while preserving full interactivity.

Deliverables

• 📘 Next.js Kanban Implementation Blueprint: Architecture decision matrix covering state flow (Server → Client → DB), cache control rules, and DnD hydration boundaries. Includes recommended folder structure for App Router + Server Actions + Client Components.
• ✅ Production Readiness Checklist:
  • Verify useState initialization matches server payload shape
  • Confirm TypeScript strict mode passes without any/@ts-ignore
  • Validate optimistic update rollback logic on server action failure
  • Audit route cache directives (use cache, dynamic, revalidate)
  • Test DnD Kit hydration across SSR/CSR boundary
  • Measure re-render count with React DevTools Profiler
  • Simulate network failure to verify state consistency & rollback