nextjs-to-nuxt-migration

Next.js to Nuxt Migration

Overview

Work module by module. For each module handed to you: analyse the full flow first, verify the backend, create a task plan, then build. Never translate blindly — understand what the module does end-to-end before writing a single line of Vue code.

Core principle: Understand → Map → Plan → Build. In that order. Every time.

The Iron Law

NEVER WRITE CODE BEFORE YOU HAVE:
  1. A submodule analysis (what it does, full data flow, all UI actions)
  2. A backend verification (which endpoints exist, which are missing)
  3. A written task plan (ordered list of what to build/fix)

NEVER DECLARE A MODULE DONE WITHOUT RUNNING THE FEATURE CHECKLIST AGAINST THE SOURCE.

The Root Cause of Incomplete Ports

Claude translates what is visible in JSX — the template structure. It routinely misses:

• Business logic buried inside custom hooks (useRecipients, useChatContext)
• Keyboard shortcuts and onKeyDown handlers
• Conditional rendering paths for empty state, error state, loading state
• useEffect side effects (scroll restoration, focus management, analytics)
• Permission/role-based branches (if (user.role === 'admin'))
• Responsive behavior (useMediaQuery, mobile-specific logic)
• Optimistic UI updates and rollback logic
• Debounced/throttled handlers
• Form validation rules (especially cross-field rules)
• URL query param sync (?page=2&search=foo)
• Clipboard, drag-drop, file upload behaviors
• WebSocket/real-time subscriptions inside hooks
• ref forwarding and imperative handles
• Context value shape (partial consumption — only reading 2 of 10 context values)

These are invisible in the template. You MUST read every hook and every handler — not just the JSX.

When to Use

• Porting a Next.js/React app to Nuxt/Vue 3
• Converting PM-built React prototypes (mock/JSON-backed) to production Vue apps
• Building NestJS backend endpoints to replace Next.js API routes
• Converting React Context state to Pinia stores