Table of Contents
Chapter 1: Why Next.js
Next.js extends React with server-side rendering, static generation, file-based routing, API routes, and built-in optimizations. It is the most popular React framework for production applications.
When to use Next.js: SEO-critical websites, content-driven applications, e-commerce frontends, SaaS applications, and any project that benefits from server-side rendering or static generation.
When to use plain React (Vite): single-page applications behind authentication, internal tools, admin dashboards, and projects where SEO is irrelevant and client-side rendering is sufficient.
Next.js hosting: Vercel (built by the Next.js team, easiest), AWS Amplify, Netlify, Cloudflare, or self-hosted with Node.js. Vercel provides the best integration but is not required.
Chapter 2: App Router Architecture
The App Router (app/ directory) uses React Server Components by default. Every component is a Server Component unless marked with 'use client'. This fundamentally changes how you think about React.
File-based routing: each folder in app/ becomes a route segment. page.tsx renders the route. layout.tsx wraps routes with shared UI. loading.tsx provides loading states. error.tsx handles errors.
Parallel routes (@folder) render multiple pages simultaneously in the same layout. Intercepting routes (.) display routes in different contexts (modal overlays). These advanced patterns enable complex UIs.
Route groups ((folder)) organize routes without affecting the URL structure. Use them for applying different layouts to different sections or organizing code by feature rather than URL path.
Chapter 3: Server Components and Client Components
Server Components render on the server. They can access databases, read files, and call APIs with secrets. No JavaScript is sent to the browser for Server Components, reducing bundle size.
Client Components (marked 'use client') handle interactivity. They run in the browser and can use hooks (useState, useEffect), event handlers (onClick), and browser APIs (window, document).
The boundary between Server and Client Components is crucial. Client Components can import other Client Components but cannot import Server Components directly. Pass Server Components as children props.
Data fetching in Server Components: use async/await directly in the component. No useState/useEffect pattern needed. fetch() calls are automatically deduplicated and can be cached at the request, route, or indefinite level.
Chapter 4: Data Fetching Patterns
Server Components fetch data with native async/await. Each component fetches its own data independently. React automatically deduplicates identical fetch requests within a single render.
Caching: Next.js caches fetch responses by default. Use cache: 'no-store' for real-time data, next.revalidate for time-based revalidation, and on-demand revalidation (revalidatePath/revalidateTag) for event-triggered updates.
Server Actions: define server-side functions with 'use server' that can be called from Client Components. Use for form submissions, data mutations, and any operation requiring server-side execution.
Streaming with Suspense: wrap async components in Suspense boundaries to stream content progressively. Users see a loading skeleton that fills in as data loads, improving perceived performance.
Chapter 5: API Routes and Server Actions
Route handlers (route.ts) create API endpoints: export async function GET(request) for GET requests, POST for creates, PUT for updates, DELETE for deletes. They run on the server with full Node.js capabilities.
Server Actions replace many API route use cases. They are RPC-like functions that execute on the server when called from forms or Client Components. Simpler than managing separate API endpoints.
When to use Route Handlers: external API consumption (webhooks, third-party integrations), file uploads, streaming responses, and when you need standard HTTP API endpoints.
When to use Server Actions: form submissions, data mutations triggered by user interactions, and any server-side operation tightly coupled to a specific UI component.
Chapter 6: Authentication
Authentication in Next.js: NextAuth.js (Auth.js) is the most popular solution. It supports OAuth providers (Google, GitHub), credentials, magic links, and session management.
Middleware-based authentication: use Next.js middleware to protect routes at the edge. Check authentication status and redirect unauthenticated users to login before the page even starts rendering.
Session management: JWT sessions (stateless, no database needed) or database sessions (more secure, revocable). JWT is simpler; database sessions are better for security-sensitive applications.
Role-based access control: check user roles in Server Components, Server Actions, and middleware. Never rely on client-side role checks alone; they can be bypassed by manipulating JavaScript.
Chapter 7: Styling and UI
CSS Modules: scoped CSS with .module.css files. Zero runtime cost, great TypeScript support, and native to Next.js. Best choice for component-specific styles.
Tailwind CSS: utility-first framework that works excellently with Next.js. Purges unused styles at build time. Combined with shadcn/ui components, it provides a complete design system.
CSS-in-JS options: styled-components and Emotion work with the App Router when configured for Server Components. However, they add runtime overhead. CSS Modules or Tailwind are generally preferred.
shadcn/ui: copy-paste React components built on Radix UI primitives and Tailwind CSS. Not a dependency; components are added to your codebase for full customization. The standard choice for Next.js component libraries.
Chapter 8: Deployment and Production
Vercel deployment: push to GitHub and Vercel deploys automatically. Preview deployments for every PR, edge functions, analytics, and speed insights. The smoothest Next.js deployment experience.
Self-hosted deployment: build with 'next build', run with 'next start'. Requires a Node.js server. Use PM2 or Docker for process management. Place behind a reverse proxy (Nginx) for production traffic.
Environment variables: use .env.local for development, .env.production for production. Prefix client-side variables with NEXT_PUBLIC_. Server-side variables are available in Server Components and API routes.
Performance optimization: use next/image for automatic image optimization, next/font for font loading, and dynamic imports for code splitting. Monitor Core Web Vitals and address regressions promptly.