## Part 1: Why Next.js? If you already know React, you can build interactive user interfaces. But React alone is a **library** for rendering UI. It doesn't have opinions about routing, data fetching, server-side rendering, or how you deploy your app. You end up choosing and configuring a dozen tools yourself: a router, a bundler, a server framework, an SSR setup, a build pipeline. **Next.js** is a **framework built on top of React** that gives you all of those things out of the box. It takes React and adds: - **File-based routing** — create a file, get a route - **Server-side rendering** — pages render on the server for fast initial loads and SEO - **Server Components** — components that run only on the server (no JavaScript sent to the browser) - **Built-in API routes** — write backend endpoints in the same project - **Automatic code splitting** — only send the JavaScript the user needs - **Image and font optimization** — built-in performance tools - **TypeScript support** — first-class, zero-config Next.js is created and maintained by **Vercel** and is used by companies like Netflix, TikTok, Twitch, Hulu, Nike, and GitHub. > Think of React as the engine and Next.js as the car. React handles rendering; Next.js handles everything else — routing, server logic, optimization, and deployment. --- ### What You'll Learn By the end of this guide you will: - Set up a Next.js project with TypeScript from scratch - Understand the App Router and file-based routing - Build pages, layouts, and nested routes - Know when to use Server Components vs Client Components - Fetch data on the server and the client - Create Server Actions for form handling and mutations - Work with the Metadata API for SEO - Optimize images, fonts, and performance - Use middleware, API routes, and environment variables - Deploy your app to production Examples in this guide use **TypeScript**. The concepts are the same in JavaScript; the types make the API clearer and give you a reference for your own projects. Let's get started. --- ## Part 2: Project Setup ### Creating a New Next.js App The fastest way to start is with `create-next-app`: ```bash npx create-next-app@latest my-app --typescript --tailwind --app --eslint ``` This creates a project with: - **TypeScript** configured - **Tailwind CSS** for styling - **App Router** (the modern routing system) - **ESLint** for code quality The flags are optional — the CLI will ask you about each one if you omit them. ### Project Structure After creation, your project looks like this: ``` my-app/ ├── app/ │ ├── layout.tsx # Root layout (wraps every page) │ ├── page.tsx # Home page (/) │ ├── globals.css # Global styles │ └── favicon.ico ├── public/ # Static files (images, fonts) ├── next.config.js # Next.js configuration ├── tailwind.config.ts # Tailwind configuration ├── tsconfig.json # TypeScript configuration ├── package.json └── .env.local # Environment variables (git-ignored) ``` The `app/` directory is where your application lives. Everything inside it maps to a URL route. ### Running the Development Server ```bash cd my-app npm run dev ``` Open `http://localhost:3000` and you'll see the default Next.js page. The dev server has **Fast Refresh** — edit a file and the browser updates instantly without losing component state. ### Key Scripts | Command | What it does | |---------|-------------| | `npm run dev` | Start development server (port 3000) | | `npm run build` | Build for production | | `npm run start` | Start production server | | `npm run lint` | Run ESLint | --- ## Part 3: The App Router Next.js has two routing systems: the **Pages Router** (legacy) and the **App Router** (modern, recommended). This guide focuses entirely on the App Router, which was introduced in Next.js 13 and is the standard going forward. ### How Routing Works In the App Router, **folders define routes** and **special files define UI**: ``` app/ ├── page.tsx → / ├── about/ │ └── page.tsx → /about ├── blog/ │ ├── page.tsx → /blog │ └── [slug]/ │ └── page.tsx → /blog/my-first-post (dynamic) ├── dashboard/ │ ├── layout.tsx → Shared layout for /dashboard/* │ ├── page.tsx → /dashboard │ └── settings/ │ └── page.tsx → /dashboard/settings ``` The rules are simple: 1. A **folder** creates a route segment 2. A **`page.tsx`** file makes a route publicly accessible 3. A **`layout.tsx`** file wraps the pages in that folder and all subfolders 4. Folders without a `page.tsx` are not accessible (they're just for organization) ### Your First Page ```tsx // app/page.tsx — The home page (/) export default function HomePage() { return (

Welcome to my site

Built with Next.js and TypeScript.

); } ``` That's it. No router configuration. No `` components. Create the file, get the page. ### Adding More Pages ```tsx // app/about/page.tsx — The about page (/about) export default function AboutPage() { return (

About Me

I'm a developer who builds things with Next.js.

); } ``` ```tsx // app/contact/page.tsx — The contact page (/contact) export default function ContactPage() { return (

Contact

Get in touch.

); } ``` ### Dynamic Routes Use square brackets to create dynamic segments: ```tsx // app/blog/[slug]/page.tsx — Matches /blog/anything type Props = { params: { slug: string }; }; export default function BlogPost({ params }: Props) { return (

Post: {params.slug}

); } ``` `/blog/hello-world` → `params.slug` is `"hello-world"` `/blog/my-first-post` → `params.slug` is `"my-first-post"` ### Catch-All Routes Use `[...slug]` to match multiple segments: ```tsx // app/docs/[...slug]/page.tsx — Matches /docs/a, /docs/a/b, /docs/a/b/c, etc. type Props = { params: { slug: string[] }; }; export default function DocsPage({ params }: Props) { // /docs/react/hooks → params.slug = ['react', 'hooks'] return

Docs: {params.slug.join(' / ')}

; } ``` ### Optional Catch-All Routes Use `[[...slug]]` (double brackets) to also match the root: ```tsx // app/shop/[[...slug]]/page.tsx // Matches /shop, /shop/shirts, /shop/shirts/blue, etc. ``` ### Route Groups Use parentheses to organize routes without affecting the URL: ``` app/ ├── (marketing)/ │ ├── about/page.tsx → /about │ └── contact/page.tsx → /contact ├── (dashboard)/ │ ├── layout.tsx → Dashboard layout (doesn't affect URL) │ ├── analytics/page.tsx → /analytics │ └── settings/page.tsx → /settings ``` The `(marketing)` and `(dashboard)` folders don't appear in the URL. They're purely for organizing your code and applying different layouts. --- ## Part 4: Layouts and Templates ### Root Layout Every Next.js app has a root layout at `app/layout.tsx`. It wraps every page in your application and is the only place where you define the `` and `` tags: ```tsx // app/layout.tsx import type { Metadata } from 'next'; import { Inter } from 'next/font/google'; import './globals.css'; const inter = Inter({ subsets: ['latin'] }); export const metadata: Metadata = { title: 'My App', description: 'Built with Next.js', }; export default function RootLayout({ children }: { children: React.ReactNode }) { return (

{children}

); } ``` The `children` prop is the current page content. When you navigate between pages, the layout stays mounted — it doesn't unmount and remount. This means navigation is instant and state in the layout (like a sidebar toggle) is preserved. ### Nested Layouts Layouts nest automatically. A layout in a subfolder wraps all pages in that folder: ```tsx // app/dashboard/layout.tsx export default function DashboardLayout({ children }: { children: React.ReactNode }) { return (

{children}

); } ``` Now every page under `/dashboard/*` gets the sidebar layout. The root layout wraps around this, so you get both the global nav/footer AND the dashboard sidebar. ### Templates Templates are like layouts but they **re-mount on every navigation**. Use them when you need fresh state or effects on each navigation (e.g. enter/exit animations): ```tsx // app/dashboard/template.tsx export default function DashboardTemplate({ children }: { children: React.ReactNode }) { return

{children}

; } ``` You'll use layouts 99% of the time. Templates are for special cases. --- ## Part 5: Special Files The App Router has several **special file names** that Next.js handles automatically: | File | Purpose | |------|---------| | `page.tsx` | The UI for a route (makes it publicly accessible) | | `layout.tsx` | Shared UI that wraps child pages (persists across navigation) | | `template.tsx` | Like layout but re-mounts on navigation | | `loading.tsx` | Loading UI (shown while the page is loading) | | `error.tsx` | Error UI (catches errors in the subtree) | | `not-found.tsx` | UI for 404 (shown when `notFound()` is called or route doesn't exist) | | `route.ts` | API endpoint (no UI) | | `default.tsx` | Fallback UI for parallel routes | ### loading.tsx Next.js automatically wraps your page in a `` boundary. The `loading.tsx` file is the fallback: ```tsx // app/dashboard/loading.tsx export default function Loading() { return (

); } ``` While `app/dashboard/page.tsx` is loading (e.g. fetching data), users see this spinner. When the data arrives, the page replaces the spinner. ### error.tsx Error boundaries catch runtime errors in your component tree: ```tsx // app/dashboard/error.tsx 'use client'; // Error boundaries must be client components interface ErrorProps { error: Error & { digest?: string }; reset: () => void; } export default function DashboardError({ error, reset }: ErrorProps) { return (

Something went wrong

{error.message}

); } ``` The `reset` function re-renders the subtree, giving it another chance to succeed. ### not-found.tsx Customize the 404 page: ```tsx // app/not-found.tsx import Link from 'next/link'; export default function NotFound() { return (

404

Page not found.

Go home

); } ``` You can also trigger a 404 programmatically: ```tsx import { notFound } from 'next/navigation'; export default async function PostPage({ params }: { params: { slug: string } }) { const post = await getPost(params.slug); if (!post) notFound(); // Shows the nearest not-found.tsx return

{post.title}

; } ``` --- ## Part 6: Server Components vs Client Components This is the most important concept in modern Next.js. Understanding this distinction is key to building performant applications. ### Server Components (Default) In the App Router, **every component is a Server Component by default**. Server Components: - Run **only on the server** — their code is never sent to the browser - Can directly access databases, file systems, and backend services - Can use `async/await` at the component level - Send **zero JavaScript** to the client for their own logic - Cannot use hooks (`useState`, `useEffect`, etc.) - Cannot use browser APIs (`window`, `document`, etc.) - Cannot use event handlers (`onClick`, `onChange`, etc.) ```tsx // This is a Server Component (default — no directive needed) import { db } from '@/lib/db'; export default async function UserList() { const users = await db.query.users.findMany(); // Direct DB access return (

{user.name} — {user.email}

); } ``` No `useEffect`. No `fetch` in a hook. No loading state. The data is fetched on the server, the HTML is rendered, and only the HTML is sent to the browser. ### Client Components When you need **interactivity** — state, effects, event handlers, browser APIs — you add the `'use client'` directive at the top of the file: ```tsx 'use client'; import { useState } from 'react'; export default function Counter() { const [count, setCount] = useState(0); return (

Count: {count}

); } ``` Client Components: - Are pre-rendered on the server (HTML), then **hydrated** on the client (JavaScript added) - Can use hooks, event handlers, browser APIs - Their JavaScript is sent to the browser - Cannot directly access databases or file systems (they run in the browser) ### The Decision Table | Need | Use | |------|-----| | Fetch data from a database or API | Server Component | | Read files from the file system | Server Component | | Access sensitive data (API keys, tokens) | Server Component | | Use `useState`, `useEffect`, or custom hooks | Client Component | | Handle user events (`onClick`, `onChange`) | Client Component | | Use browser APIs (`localStorage`, `window`) | Client Component | | Show interactive forms or controls | Client Component | | Display static content, markdown, blog posts | Server Component | ### The Composition Pattern The key insight: **Server Components can render Client Components, but not the other way around.** The best pattern is to keep Server Components at the top of the tree and push Client Components down to the leaves — only the interactive parts: ```tsx // app/dashboard/page.tsx — Server Component import { db } from '@/lib/db'; import SearchFilter from './search-filter'; // Client Component import UserTable from './user-table'; // Server Component export default async function DashboardPage() { const users = await db.query.users.findMany(); return (

Dashboard

{/* Interactive — Client Component */} {/* Static display — Server Component */}

); } ``` ```tsx // app/dashboard/search-filter.tsx — Client Component 'use client'; import { useState } from 'react'; export default function SearchFilter() { const [query, setQuery] = useState(''); return ( setQuery(e.target.value)} placeholder="Search users..." /> ); } ``` ### What Can Cross the Boundary? When a Server Component passes props to a Client Component, those props must be **serializable** — they cross a network boundary: ✅ **Can pass:** strings, numbers, booleans, arrays, plain objects, `Date`, `Map`, `Set`, `null`, `undefined` ❌ **Cannot pass:** functions, class instances, DOM nodes, React elements (with exceptions for `children`) ```tsx // ✅ This works — passing serializable data // ❌ This doesn't work — functions aren't serializable console.log('hi')} /> // ✅ This works — children is a special case {/* Server Component rendered as children */} ``` --- ## Part 7: Data Fetching Data fetching in the App Router is fundamentally different from traditional React. Instead of `useEffect` + `fetch` on the client, you fetch data **on the server** in your Server Components. ### Fetching in Server Components Server Components can be `async`, so you can `await` data directly: ```tsx // app/posts/page.tsx — Server Component interface Post { id: number; title: string; body: string; } export default async function PostsPage() { const res = await fetch('https://jsonplaceholder.typicode.com/posts'); const posts: Post[] = await res.json(); return (

{post.title}

{post.body}

); } ``` No loading state to manage. No `useEffect`. No race conditions. The page renders on the server with the data already available. ### Caching and Revalidation Next.js extends the native `fetch` API with caching options: ```tsx // Cached forever (default in production — static) const res = await fetch('https://api.example.com/data'); // Revalidate every 60 seconds (ISR — Incremental Static Regeneration) const res = await fetch('https://api.example.com/data', { next: { revalidate: 60 }, }); // Never cache (always fresh — dynamic) const res = await fetch('https://api.example.com/data', { cache: 'no-store', }); ``` | Strategy | Option | When to use | |----------|--------|-------------| | Static (cached) | Default | Data that rarely changes (blog posts, docs) | | ISR (timed) | `next: { revalidate: N }` | Data that changes periodically (product listings) | | Dynamic (no cache) | `cache: 'no-store'` | Data that changes per request (user-specific data) | ### Database Access in Server Components Since Server Components run on the server, you can query your database directly — no API layer needed: ```tsx // app/users/page.tsx import { db } from '@/lib/db'; export default async function UsersPage() { const users = await db.query.users.findMany({ orderBy: (users, { desc }) => [desc(users.createdAt)], limit: 50, }); return (

Users

{users.map(user => (

{user.name} — {user.email}

))}

); } ``` This is one of the biggest advantages of Server Components: your database query runs on the server, the result is rendered to HTML, and only the HTML goes to the browser. No API endpoint. No client-side fetching. No exposed database credentials. ### Client-Side Fetching (When Needed) Sometimes you still need client-side fetching — for interactive features like search-as-you-type, infinite scroll, or real-time updates: ```tsx 'use client'; import { useState, useEffect } from 'react'; interface SearchResult { id: string; title: string; } export default function SearchComponent() { const [query, setQuery] = useState(''); const [results, setResults] = useState([]); const [loading, setLoading] = useState(false); useEffect(() => { if (!query.trim()) { setResults([]); return; } const controller = new AbortController(); setLoading(true); fetch(`/api/search?q=${encodeURIComponent(query)}`, { signal: controller.signal, }) .then(res => res.json()) .then(data => { setResults(data); setLoading(false); }) .catch(err => { if (err.name !== 'AbortError') setLoading(false); }); return () => controller.abort(); }, [query]); return (

setQuery(e.target.value)} placeholder="Search..." /> {loading &&

}

{r.title}

); } ``` Rule of thumb: **fetch on the server by default. Only fetch on the client when you need interactivity.** --- ## Part 8: Server Actions Server Actions let you write server-side functions that can be called directly from your components — no API routes needed. They're Next.js's way of handling form submissions, data mutations, and any server-side logic triggered by user interaction. ### Defining a Server Action Add `'use server'` at the top of a file or inside a function: ```tsx // app/actions/user-actions.ts 'use server'; import { db } from '@/lib/db'; import { users } from '@/lib/db/schema'; import { revalidatePath } from 'next/cache'; import { z } from 'zod'; const createUserSchema = z.object({ name: z.string().min(2).max(100), email: z.string().email(), }); export async function createUser(formData: FormData) { const parsed = createUserSchema.safeParse({ name: formData.get('name'), email: formData.get('email'), }); if (!parsed.success) { return { error: parsed.error.flatten() }; } await db.insert(users).values(parsed.data); revalidatePath('/users'); // Refresh the users page cache } ``` ### Using Server Actions in Forms Server Actions integrate seamlessly with HTML forms: ```tsx // app/users/new/page.tsx — Server Component import { createUser } from '@/app/actions/user-actions'; export default function NewUserPage() { return ( ); } ``` The form works **without JavaScript** (progressive enhancement). If JS is available, the form submits without a full page reload. If JS is disabled, it still works as a regular form submission. ### Server Actions in Client Components You can also call Server Actions from Client Components: ```tsx 'use client'; import { useState } from 'react'; import { createUser } from '@/app/actions/user-actions'; export default function CreateUserForm() { const [message, setMessage] = useState(''); async function handleSubmit(formData: FormData) { const result = await createUser(formData); if (result?.error) { setMessage('Error creating user'); } else { setMessage('User created successfully!'); } } return ( ); } ``` ### useFormStatus Show a pending state while the action is processing: ```tsx 'use client'; import { useFormStatus } from 'react-dom'; function SubmitButton() { const { pending } = useFormStatus(); return ( ); } ``` `useFormStatus` must be used inside a component that's a child of the `

`. It reads the form's submission state automatically. ### When to Use Server Actions vs API Routes | Use case | Approach | |----------|----------| | Form submissions, data mutations | Server Actions | | Revalidating cached data | Server Actions with `revalidatePath` | | Webhooks from external services | API routes (`route.ts`) | | Third-party integrations that POST to your app | API routes | | Public API consumed by other clients | API routes | --- ## Part 9: Static vs Dynamic Rendering Next.js decides at build time whether a route is **static** (pre-rendered) or **dynamic** (rendered per request). Understanding this helps you optimize performance. ### Static Rendering (Default) By default, Next.js pre-renders routes at **build time**. The HTML is generated once and served from a CDN. This is the fastest option: ```tsx // This page is static — rendered at build time export default async function AboutPage() { return (

About Us

We build great software.

); } ``` ### Dynamic Rendering A route becomes dynamic when it uses: - `cookies()` or `headers()` (request-specific data) - `searchParams` (query parameters) - `fetch` with `cache: 'no-store'` - `export const dynamic = 'force-dynamic'` ```tsx import { cookies } from 'next/headers'; // This page is dynamic — rendered per request export default async function DashboardPage() { const cookieStore = cookies(); const token = cookieStore.get('session')?.value; // ... fetch user-specific data return

Dashboard for authenticated user

; } ``` ### Static Generation with Dynamic Data (ISR) Incremental Static Regeneration gives you the best of both worlds — static pages that update periodically: ```tsx // This page is static but revalidates every 60 seconds export const revalidate = 60; export default async function ProductsPage() { const res = await fetch('https://api.example.com/products'); const products = await res.json(); return ; } ``` ### generateStaticParams For dynamic routes, tell Next.js which paths to pre-render at build time: ```tsx // app/blog/[slug]/page.tsx export async function generateStaticParams() { const posts = await getAllPosts(); return posts.map(post => ({ slug: post.slug })); } export default async function BlogPost({ params }: { params: { slug: string } }) { const post = await getPost(params.slug); return

{post.content}

; } ``` This pre-renders a page for every blog post at build time. New posts added after the build are rendered on-demand and then cached. ### How to Know if a Route is Static or Dynamic Run `npm run build` and check the output: ``` Route (app) Size First Load JS ┌ ○ / 5.2 kB 89 kB ├ ○ /about 1.1 kB 85 kB ├ λ /dashboard 3.4 kB 87 kB ├ ● /blog/[slug] 2.8 kB 87 kB ``` - `○` = Static (pre-rendered) - `λ` = Dynamic (rendered per request) - `●` = Static with ISR (pre-rendered, revalidates) --- ## Part 10: Metadata and SEO Next.js has a built-in Metadata API for managing ``, `<meta>` tags, Open Graph, Twitter cards, and more. ### Static Metadata Export a `metadata` object from a layout or page: ```tsx // app/layout.tsx import type { Metadata } from 'next'; export const metadata: Metadata = { metadataBase: new URL('https://mysite.com'), title: { default: 'My Site', template: '%s | My Site', // Pages can override the title }, description: 'A great website built with Next.js', openGraph: { title: 'My Site', description: 'A great website built with Next.js', url: 'https://mysite.com', siteName: 'My Site', locale: 'en_US', type: 'website', }, twitter: { card: 'summary_large_image', title: 'My Site', description: 'A great website built with Next.js', }, }; ``` ### Dynamic Metadata Use `generateMetadata` for pages where the metadata depends on data: ```tsx // app/blog/[slug]/page.tsx import type { Metadata } from 'next'; type Props = { params: { slug: string }; }; export async function generateMetadata({ params }: Props): Promise<Metadata> { const post = await getPost(params.slug); return { title: post.title, description: post.excerpt, openGraph: { title: post.title, description: post.excerpt, images: [{ url: post.coverImage }], }, }; } export default async function BlogPost({ params }: Props) { const post = await getPost(params.slug); return <article>{post.content}</article>; } ``` ### Key Metadata Fields | Field | Purpose | |-------|---------| | `metadataBase` | Base URL for resolving relative URLs in metadata | | `title` | Page title (can be a string or `{ default, template }`) | | `description` | Meta description for search engines | | `openGraph` | Open Graph tags for social sharing (Facebook, LinkedIn) | | `twitter` | Twitter card tags | | `robots` | Search engine crawling directives | | `icons` | Favicon and app icons | | `manifest` | Web app manifest | --- ## Part 11: Navigation and Linking ### The Link Component Use Next.js's `<Link>` component for client-side navigation: ```tsx import Link from 'next/link'; export default function Navigation() { return ( <nav> <Link href="/">Home</Link> <Link href="/about">About</Link> <Link href="/blog">Blog</Link> <Link href={`/blog/${post.slug}`}>Read More</Link> </nav> ); } ``` `<Link>` prefetches pages in the background when they appear in the viewport. By the time the user clicks, the page is already loaded. ### Prefetching Behavior | Scenario | Behavior | |----------|----------| | Static route | Fully prefetched (entire page data) | | Dynamic route | Partially prefetched (up to the nearest `loading.tsx`) | | `prefetch={false}` | No prefetching | ### Programmatic Navigation Use the `useRouter` hook for navigation in Client Components: ```tsx 'use client'; import { useRouter } from 'next/navigation'; export default function LoginForm() { const router = useRouter(); async function handleLogin() { const success = await login(); if (success) { router.push('/dashboard'); // Navigate to dashboard router.refresh(); // Refresh server data } } return <button onClick={handleLogin}>Log In</button>; } ``` ### Active Link Styling Use `usePathname` to highlight the current page: ```tsx 'use client'; import Link from 'next/link'; import { usePathname } from 'next/navigation'; export default function NavLink({ href, label }: { href: string; label: string }) { const pathname = usePathname(); const isActive = pathname === href; return ( <Link href={href} className={isActive ? 'text-blue-600 font-bold' : 'text-gray-600'} > {label} </Link> ); } ``` --- ## Part 12: Styling Next.js supports multiple styling approaches out of the box. ### Tailwind CSS (Recommended) If you selected Tailwind during setup, it's already configured: ```tsx export default function Card({ title, description }: { title: string; description: string }) { return ( <div className="rounded-lg border border-gray-200 p-6 shadow-sm hover:shadow-md transition-shadow"> <h2 className="text-xl font-semibold text-gray-900">{title}</h2> <p className="mt-2 text-gray-600">{description}</p> </div> ); } ``` ### CSS Modules CSS Modules scope styles to a single component. Create a file with `.module.css`: ```css /* app/components/card.module.css */ .card { border-radius: 8px; border: 1px solid #e5e7eb; padding: 1.5rem; } .card:hover { box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1); } .title { font-size: 1.25rem; font-weight: 600; } ``` ```tsx import styles from './card.module.css'; export default function Card({ title }: { title: string }) { return ( <div className={styles.card}> <h2 className={styles.title}>{title}</h2> </div> ); } ``` ### Global CSS Import global CSS in your root layout: ```tsx // app/layout.tsx import './globals.css'; ``` Only import global CSS in the root layout or in CSS Modules. Importing global CSS in other components can cause conflicts. --- ## Part 13: Image and Font Optimization ### next/image The `<Image>` component optimizes images automatically — lazy loading, responsive sizing, WebP/AVIF conversion: ```tsx import Image from 'next/image'; export default function Avatar() { return ( <Image src="/avatar.jpg" alt="Profile photo" width={128} height={128} className="rounded-full" /> ); } ``` For remote images, configure allowed domains in `next.config.js`: ```js // next.config.js const nextConfig = { images: { remotePatterns: [ { protocol: 'https', hostname: 'cdn.example.com', }, ], }, }; module.exports = nextConfig; ``` ### next/font Load fonts with zero layout shift using `next/font`: ```tsx // app/layout.tsx import { Inter, Fira_Code } from 'next/font/google'; const inter = Inter({ subsets: ['latin'], display: 'swap', variable: '--font-inter', }); const firaCode = Fira_Code({ subsets: ['latin'], display: 'swap', variable: '--font-mono', }); export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en" className={`${inter.variable} ${firaCode.variable}`}> <body className="font-sans">{children}</body> </html> ); } ``` Fonts are downloaded at build time and self-hosted. No requests to Google Fonts at runtime. --- ## Part 14: Environment Variables ### Defining Variables Create a `.env.local` file (git-ignored by default): ``` # Server-only (default) DATABASE_URL=postgresql://user:password@localhost:5432/mydb API_SECRET=my-secret-key # Client-accessible (must start with NEXT_PUBLIC_) NEXT_PUBLIC_SITE_URL=https://mysite.com NEXT_PUBLIC_GA_ID=G-XXXXXXX ``` ### Access Rules | Variable | Where it's available | |----------|---------------------| | `DATABASE_URL` | Server only (Server Components, API routes, Server Actions) | | `NEXT_PUBLIC_SITE_URL` | Server and Client (bundled into the JavaScript) | ```tsx // Server Component — can access both const dbUrl = process.env.DATABASE_URL; // ✅ const siteUrl = process.env.NEXT_PUBLIC_SITE_URL; // ✅ // Client Component — can only access NEXT_PUBLIC_* const siteUrl = process.env.NEXT_PUBLIC_SITE_URL; // ✅ const dbUrl = process.env.DATABASE_URL; // ❌ undefined ``` Never put secrets in `NEXT_PUBLIC_` variables. They're embedded in the client-side JavaScript and visible to anyone. ### Environment Files | File | Purpose | Git-tracked? | |------|---------|-------------| | `.env` | Default for all environments | Optional | | `.env.local` | Local overrides (secrets) | No | | `.env.development` | Development defaults | Optional | | `.env.production` | Production defaults | Optional | --- ## Part 15: Middleware Middleware runs **before** every request, letting you modify the response, redirect, rewrite, or add headers. ### Basic Middleware Create a `middleware.ts` file at the root of your project (not inside `app/`): ```tsx // middleware.ts import { NextResponse } from 'next/server'; import type { NextRequest } from 'next/server'; export function middleware(request: NextRequest) { // Example: redirect /old-page to /new-page if (request.nextUrl.pathname === '/old-page') { return NextResponse.redirect(new URL('/new-page', request.url)); } // Example: add a custom header const response = NextResponse.next(); response.headers.set('x-custom-header', 'hello'); return response; } // Only run middleware on specific paths export const config = { matcher: ['/dashboard/:path*', '/api/:path*'], }; ``` ### Common Middleware Patterns **Authentication guard:** ```tsx export function middleware(request: NextRequest) { const token = request.cookies.get('session')?.value; if (!token && request.nextUrl.pathname.startsWith('/dashboard')) { return NextResponse.redirect(new URL('/login', request.url)); } return NextResponse.next(); } ``` **Geo-based redirects:** ```tsx export function middleware(request: NextRequest) { const country = request.geo?.country; if (country === 'GB' && !request.nextUrl.pathname.startsWith('/uk')) { return NextResponse.redirect(new URL('/uk', request.url)); } return NextResponse.next(); } ``` --- ## Part 16: API Routes API routes let you build backend endpoints inside your Next.js app. They live alongside your pages in the `app/` directory. ### Creating an API Route Create a `route.ts` file (not `page.tsx`) in any folder: ```tsx // app/api/users/route.ts import { NextRequest, NextResponse } from 'next/server'; import { db } from '@/lib/db'; import { users } from '@/lib/db/schema'; export async function GET() { const allUsers = await db.select().from(users); return NextResponse.json(allUsers); } export async function POST(request: NextRequest) { const body = await request.json(); const newUser = await db.insert(users).values(body).returning(); return NextResponse.json(newUser, { status: 201 }); } ``` ### Supported HTTP Methods Export functions named after HTTP methods: ```tsx export async function GET(request: NextRequest) { /* ... */ } export async function POST(request: NextRequest) { /* ... */ } export async function PUT(request: NextRequest) { /* ... */ } export async function PATCH(request: NextRequest) { /* ... */ } export async function DELETE(request: NextRequest) { /* ... */ } ``` ### Dynamic API Routes ```tsx // app/api/users/[id]/route.ts import { NextRequest, NextResponse } from 'next/server'; export async function GET( request: NextRequest, { params }: { params: { id: string } } ) { const user = await getUser(params.id); if (!user) { return NextResponse.json({ error: 'Not found' }, { status: 404 }); } return NextResponse.json(user); } ``` ### When to Use API Routes vs Server Actions | API Routes | Server Actions | |-----------|----------------| | Public APIs consumed by external clients | Internal mutations (form submissions, data updates) | | Webhook endpoints | Revalidating cached data | | Integrations that POST to your server | Any server function called from your own components | If the only consumer is your own Next.js app, prefer Server Actions. They're simpler and type-safe. --- ## Part 17: next.config.js The configuration file controls build behavior, image optimization, redirects, and more: ```js // next.config.js /** @type {import('next').NextConfig} */ const nextConfig = { // Image optimization images: { remotePatterns: [ { protocol: 'https', hostname: 'cdn.example.com' }, ], }, // Permanent redirects (301) async redirects() { return [ { source: '/old-blog/:slug', destination: '/blog/:slug', permanent: true }, ]; }, // Rewrites (URL stays the same, content from different path) async rewrites() { return [ { source: '/api/proxy/:path*', destination: 'https://api.external.com/:path*' }, ]; }, // Custom headers async headers() { return [ { source: '/(.*)', headers: [ { key: 'X-Frame-Options', value: 'DENY' }, { key: 'X-Content-Type-Options', value: 'nosniff' }, ], }, ]; }, reactStrictMode: true, }; module.exports = nextConfig; ``` --- ## Part 18: Deployment ### Vercel (Simplest) Vercel is built by the Next.js team and offers the smoothest deployment experience: 1. Push your code to GitHub/GitLab/Bitbucket 2. Import the repository on [vercel.com](https://vercel.com) 3. Set environment variables 4. Deploy Every push to `main` triggers a production deployment. Pull requests get preview deployments. ### Self-Hosting (DigitalOcean, AWS, etc.) Build and run your app on any Node.js server: ```bash # Build npm run build # Start production server npm run start ``` The production server runs on port 3000 by default. Use a reverse proxy (Nginx) and process manager (PM2) in production. For **DigitalOcean App Platform**, you can connect your GitHub repo directly and it auto-detects Next.js. ### Docker ```dockerfile FROM node:20-alpine AS base FROM base AS deps WORKDIR /app COPY package*.json ./ RUN npm ci FROM base AS builder WORKDIR /app COPY --from=deps /app/node_modules ./node_modules COPY . . RUN npm run build FROM base AS runner WORKDIR /app ENV NODE_ENV=production COPY --from=builder /app/.next/standalone ./ COPY --from=builder /app/.next/static ./.next/static COPY --from=builder /app/public ./public EXPOSE 3000 CMD ["node", "server.js"] ``` Add `output: 'standalone'` to `next.config.js` for Docker deployments: ```js const nextConfig = { output: 'standalone', }; ``` ### Static Export For fully static sites (no server needed): ```js const nextConfig = { output: 'export', }; ``` This generates a `out/` directory with static HTML files you can deploy anywhere (Netlify, GitHub Pages, S3, etc.). --- ## Part 19: Project Ideas Now that you know the fundamentals, here are projects that'll solidify your understanding: ### 1. Personal Blog - Markdown-based posts with `gray-matter` - Dynamic `[slug]` routes - Metadata API for SEO - Table of contents generation - RSS feed via API route ### 2. Task Manager - CRUD with Server Actions - Database with Drizzle ORM - Optimistic updates with `useOptimistic` - Auth with Auth.js - Dashboard layout with sidebar ### 3. E-Commerce Storefront - Product listing with ISR - Search with query parameters - Shopping cart (client state + Server Actions) - Stripe checkout integration - Image optimization for product photos ### 4. Link Shortener - Form to create short links (Server Action) - Dynamic `[code]` route that redirects - Analytics dashboard (click counts) - Rate limiting via middleware - API routes for external integrations ### 5. Real-Time Chat - Socket.io integration - Auth with sessions - Message history with database - Typing indicators (client component) - Server-rendered initial messages --- ## Part 20: Resources and Next Steps ### Official Resources - [Next.js Documentation](https://nextjs.org/docs) — the official docs are excellent - [Next.js Learn Course](https://nextjs.org/learn) — free interactive tutorial - [Vercel Templates](https://vercel.com/templates/next.js) — starter templates and examples ### What to Learn Next Once you're comfortable with these basics, explore: - **React Server Components** in depth (the RSC mental model) - **Caching architecture** (the 4 caching layers in Next.js) - **Parallel and Intercepting Routes** (modals, complex layouts) - **Streaming and Suspense** (progressive rendering) - **Edge Runtime** (running at the edge for lower latency) - **Testing** with Playwright and Jest - **Auth.js** (formerly NextAuth) for authentication - **Drizzle ORM** or **Prisma** for type-safe database access --- ## Final Thoughts Next.js takes React and gives it structure. Instead of deciding how to route, how to fetch data, how to render on the server, and how to optimize for production — Next.js makes those decisions for you, based on years of real-world patterns. The App Router and Server Components represent a fundamental shift in how we build web apps. The server does more. The client does less. The result is faster pages, better SEO, and simpler code. You don't need to learn everything at once. Start with pages and layouts. Add data fetching. Try Server Actions. Build something real. Then come back and explore the deeper features when you need them. The best way to learn a framework is to build something with it. --- Now go build something with Next.js. </article></body></html>

Next.js 101: The Ultimate Beginner's Guide