Step 1 • Before You Start
Prerequisites — React, TypeScript, and HTTP beginner Next.js is a React framework — React fundamentals are required first. Know: JSX, components, props, state, useState/useEffect/useCallback/useMemo hooks, context, and component composition. TypeScript is the default in Next.js projects — know interfaces, generics, and utility types (Partial, Pick, Omit). HTTP basics: GET/POST, status codes, what a server renders vs what a browser renders. Understanding what SSR (Server-Side Rendering), SSG (Static Site Generation), and CSR (Client-Side Rendering) mean at a high level before starting. The App Router (default since Next.js 13) is fundamentally different from the old Pages Router — this roadmap covers App Router throughout.
5h Step 2 • Setup
Project Setup — App Router Structure and Config beginner npx create-next-app@latest with TypeScript, Tailwind CSS, App Router, and src/ directory. Understand the App Router directory structure: app/ is the root, app/layout.tsx is the root layout, app/page.tsx is the homepage (/), app/about/page.tsx is /about, app/api/users/route.ts is the /api/users API route. Special files: layout.tsx, page.tsx, loading.tsx, error.tsx, not-found.tsx, route.ts. next.config.ts for configuration (image domains, redirects, rewrites, env vars). Environment variables: .env.local for secrets (not committed), .env for defaults — prefix with NEXT_PUBLIC_ to expose to the browser. Run dev, build, start, lint.
3h Step 3 • Routing
App Router — File-Based Routing and Route Groups beginner The App Router uses the file system as the router. Every folder creates a URL segment. Dynamic segments: [id] (single — /posts/123), [...slug] (catch-all — /docs/a/b/c), [[...slug]] (optional catch-all — also matches /docs). Route groups: (group-name) folders that don't affect the URL but allow separate layouts — (marketing) and (app) can each have their own layout.tsx without adding a URL segment. Parallel routes (@slot folder — render multiple pages in the same layout simultaneously), Intercepting routes ((.) prefix — show a modal for /photo/1 while keeping the underlying page). Private folders (_folder) opt out of routing. colocation of components next to the route that uses them.
5h Step 4 • Foundations
Layouts, Templates, and Special Files beginner layout.tsx wraps child routes and persists across navigations (doesn't re-render — state is preserved). template.tsx re-creates a fresh instance on every navigation (useful for per-page animations or resetting state). loading.tsx is shown automatically using React Suspense while a page is loading — allows instant navigation with streamed content. error.tsx catches rendering errors in the route subtree — must be a Client Component ('use client') — has reset() prop to retry. not-found.tsx for 404s. global-error.tsx wraps the root layout errors. Nested layouts compose naturally — each layout.tsx wraps its child segments. The root layout (app/layout.tsx) must contain <html> and <body> tags.
5h Step 5 • Rendering
React Server Components — Server-First Rendering intermediate In the App Router, all components are Server Components by default — they run on the server and send HTML to the client (no JavaScript bundle). Server Components can be async — await fetch() or a database query directly in the component. They access server-only resources: databases, file system, environment variables, secrets. They cannot: use browser APIs (window, localStorage), use React hooks (useState, useEffect), handle user events. Server Components reduce client JavaScript to near zero for content-heavy pages. Use server-only package to prevent accidental client-side imports of server code. The component tree is split at 'use client' boundaries — Server Components can pass serializable props to Client Components.
7h Step 6 • Rendering
Client Components — Interactivity and Browser APIs intermediate 'use client' marks a component and all its imports as client-side — they ship as JavaScript to the browser. Use Client Components for: event handlers (onClick, onChange), React hooks (useState, useEffect, useRef), browser APIs (localStorage, window, geolocation), and third-party libraries that require browser globals. Keep Client Components as leaf nodes (at the bottom of the tree) to minimize the client bundle. Pattern: the Server Component fetches data and passes it as props to a Client Component that handles interaction. Use the useRouter() hook for programmatic navigation, usePathname() for the current path, and useSearchParams() for query string reading. Hydration — server-rendered HTML is reused, not replaced.
5h Step 7 • intermediate
Styling Approaches beginner Style Next.js apps with CSS Modules (locally scoped classnames, built-in), Tailwind CSS (utility-first with JIT, install via PostCSS), and CSS-in-JS solutions (Styled Components, Emotion — with Server Components caveats). Import global CSS in the root layout. Use next/font for zero-layout-shift web font loading (Google Fonts, local fonts). Understand Server Component styling constraints.
4h Step 8 • Data
Data Fetching, Caching, and Revalidation intermediate Next.js extends the native fetch API with caching semantics. fetch(url, { cache: 'force-cache' }) — static, cached indefinitely (SSG equivalent). fetch(url, { next: { revalidate: 60 } }) — ISR equivalent, revalidate after 60 seconds. fetch(url, { cache: 'no-store' }) — never cache (SSR equivalent). unstable_cache() wraps non-fetch data sources (database queries, third-party SDKs) with the same caching API. Revalidation: revalidatePath('/blog') or revalidateTag('posts') for on-demand revalidation (call from a Server Action or API route). Parallel data fetching: await Promise.all([...]) — don't use sequential awaits when data is independent. Request memoization — the same fetch URL called multiple times in one render is deduplicated.
7h Step 9 • advanced
Caching & Revalidation advanced Master Next.js multi-layer caching: Request Memoization (deduplicates fetch() calls within one render pass), Data Cache (persistent cross-request, stored on server), Full Route Cache (static HTML + RSC payload), and Router Cache (client-side segment cache). Use revalidatePath() and revalidateTag() for on-demand revalidation from Server Actions. Opt out with cache: 'no-store' or unstable_noStore().
6h Step 10 • Data
Server Actions — Forms and Mutations intermediate Server Actions are async functions that run on the server — call them directly from Client Components without an API route. Mark with 'use server' at the top of an async function (in-file or in a separate file — all exports become Server Actions). Use in HTML forms: <form action={createPost}> — works without JavaScript (progressive enhancement). In Client Components: call as a regular async function or use with useFormStatus (loading state) and useFormState (error/success state from the action's return value). Validate input server-side (zod). Return errors as objects (not throw — to allow the client to display them). Revalidate after mutation: revalidatePath('/posts'). Replace most API routes for form submissions and mutations.
6h Step 11 • API
API Route Handlers intermediate Route handlers (app/api/.../route.ts) create API endpoints — export named functions for each HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. Access: request.json() for body, request.nextUrl.searchParams for query, cookies() and headers() from next/headers. Return a Response object or NextResponse (from next/server). Use API routes for: webhooks (Stripe, GitHub), public APIs consumed by mobile apps or third parties, and endpoints that don't fit the Server Action model. Dynamic route handlers: app/api/posts/[id]/route.ts. Middleware can intercept route handlers. Cache GET handlers with the same fetch caching options. Avoid API routes when Server Actions work — they're simpler and more secure.
5h Step 12 • Authentication
Authentication with Auth.js (NextAuth v5) intermediate Auth.js (formerly NextAuth.js) is the standard auth solution for Next.js. Config: auth.ts exports auth, signIn, signOut, handlers. API route at app/api/auth/[...nextauth]/route.ts re-exports handlers. Providers: OAuth (Google, GitHub, Apple — add in minutes), Credentials (email/password — you handle verification), Email (magic link). Session management: JWT (default — session stored in cookie) or Database sessions (stored in DB — requires adapter). Protect pages: auth() in Server Components returns the session. Middleware.ts for route-level protection — redirect unauthenticated users to login. Role-based access: custom session callback adds role to token. next-auth/react useSession for Client Components.
6h Step 13 • Performance
Optimization — Images, Fonts, and Lazy Loading intermediate next/image automatically optimizes images — WebP/AVIF conversion, responsive srcset, lazy loading by default, prevents CLS with width/height. Required props: src, alt, width, height (or fill for CSS-positioned containers). Disable optimization for remote domains in next.config.ts (images.remotePatterns). priority prop for above-the-fold LCP images. next/font loads fonts with zero layout shift — fonts are self-hosted (no Google Fonts network request), variable fonts supported. Import in layout.tsx and apply the className. next/link prefetches pages on hover (in production). React.lazy + Suspense for dynamic Client Component imports (next/dynamic is the Next.js wrapper — supports SSR: false for client-only libraries).
5h Step 14 • Advanced
Middleware — Edge Functions and Request Interception intermediate middleware.ts (at the project root) runs before every request — on the edge (Vercel Edge Network, extremely low latency). Use for: authentication checks (redirect to login without hitting the origin), A/B testing (set a cookie and rewrite the URL), geolocation-based routing (redirect to localized content), rate limiting at the edge, bot detection. The matcher config limits which routes run middleware (avoid running on static assets). NextResponse.redirect(), NextResponse.rewrite() (serve different content at the same URL), NextResponse.next() (continue). Access cookies and headers. middleware runs in the Edge Runtime — no Node.js APIs, no file system, limited library support.
4h Step 15 • Advanced
Streaming and Partial Pre-rendering advanced Streaming sends HTML to the browser progressively — the shell (layout, static content) loads first, while dynamic content streams in. React Suspense boundaries define what streams separately — wrap slow data components in <Suspense fallback={<Skeleton />}>. Multiple Suspense boundaries allow different parts of the page to appear as they're ready. Partial Pre-rendering (PPR — experimental in Next.js 14, stable in 15) is the next evolution: the static shell is pre-rendered at build time, and dynamic 'holes' (Suspense boundaries) are streamed from the server on each request. This combines the best of SSG (fast initial HTML) and SSR (dynamic content). Use PPR: experimental: { ppr: true } in next.config.
5h Step 16 • Quality
Testing with Vitest and Playwright intermediate Testing a Next.js App Router app spans unit, component, and end-to-end layers. Unit/component tests with Vitest and @testing-library/react — test utility functions and React components, mock next/navigation and next/headers. Use MSW (Mock Service Worker) to intercept fetch calls without mocking the module itself. End-to-end tests with Playwright: real browser, navigate routes, fill forms, assert on the DOM — playwright.config.ts sets baseURL and parallel workers. Test the full auth flow E2E: sign in, protected redirect, session-aware navigation. Run Playwright in GitHub Actions with browser binary caching. Coverage thresholds with @vitest/coverage-v8.
5h Step 17 • Production
Production — Deployment, Monitoring, and Analytics advanced Deployment options: Vercel (first-class Next.js support — zero config, preview deployments on PRs, Edge Network, Analytics), Docker (next build + next start — full Node.js server, self-hostable), static export (next export — works only without dynamic features — deploy to S3/Cloudflare Pages). Vercel Analytics for Core Web Vitals, Speed Insights for synthetic monitoring. Error tracking: Sentry for Next.js (@sentry/nextjs — App Router support, captures both server and client errors). Bundle analysis: @next/bundle-analyzer. next.config.ts optimizations: compiler.removeConsole in production, modularizeImports for large UI libraries (reduce bundle size). Test with Playwright for E2E. Lighthouse CI in GitHub Actions.
6h 