Preparation & Audit

Audit your codebase before writing a single line of Next.js

Week 13–5 daysEstimated: 12h totalDon't skip this

Why this phase matters

3 days of audit prevents 3 weeks of debugging. Discovering that you missed all window references mid-migration causes SSR crashes in production. Catch them now.

Codebase Audit — Run These Searches

Find all react-router-dom imports — every file using it needs a route created in app/

Run: grep -r "react-router-dom" src/ --include="*.jsx" -l

2 hrs

Find all useNavigate calls — replace with useRouter from next/navigation

2 hrs

Find all localStorage / sessionStorage references — causes SSR crash

1 hr

List all VITE_ env variables — rename each to NEXT_PUBLIC_ everywhere

30 min

Document every protected route path — these go in middleware.js matcher array

30 min

Identify all <img> tags using S3 URLs — these become next/image (needs domain config)

30 min

Document all custom React hooks — useAuth, useSocket, etc. — all need 'use client'

1 hr

List all Context Providers — replace with Zustand or keep as client components

1 hr

Run npm run build on Vite project — note all warnings — they become SSR errors in Next.js

30 min

Project Scaffolding

Create a new git branch — never migrate on main

2 min

Keep old Frontend/ folder untouched — create a new Frontend-Next/ alongside it

1 min

Scaffold Next.js — with the exact flags below — all configured for your stack

15 min

Performance Baseline

Record baseline Lighthouse scores — run on your current Vite app — Performance, SEO, Accessibility, Best Practices

30 min

Measure current bundle size — run npm run build and note total JS/CSS sizes

15 min

terminal — run from project root

# Run from your project root (same level as Backend/)
npx create-next-app@latest Frontend-Next \
  --tailwind \
  --eslint \
  --app \
  --no-typescript \
  --no-src-dir \
  --import-alias "@/*"

# Install your stack
cd Frontend-Next
npm install axios zustand socket.io-client
npm install react-hook-form @hookform/resolvers zod
npm install next-sitemap @tanstack/react-table
npm install sonner lucide-react

# Initialize shadcn/ui
npx shadcn@latest init

# Verify it runs
npm run dev  # should open http://localhost:3000

Common Gotcha: Port conflict — Your Vite dev server runs on :5173. Next.js defaults to :3000. Run both simultaneously during migration.

Phase 01 — Project Configuration