mgd34msu Next.js
Full-stack React framework with App Router, Server Components, Server Actions, and optimized deployment patterns.
Quick Start
Create new project:
npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir
cd my-app && npm run dev
Essential file structure:
src/
app/
layout.tsx # Root layout (required)
page.tsx # Home page
globals.css # Global styles
api/ # Route handlers
components/ # React components
lib/ # Utilities
App Router Fundamentals
File Conventions
| File | Purpose |
|---|---|
page.tsx |
Route UI |
layout.tsx |
Shared UI wrapper |
loading.tsx |
Loading UI (Suspense) |
error.tsx |
Error boundary |
not-found.tsx |
404 UI |
route.ts |
API endpoint |
Routing Patterns
app/
page.tsx # /
blog/
page.tsx # /blog
[slug]/
page.tsx # /blog/:slug
(marketing)/ # Route group (no URL segment)
about/page.tsx # /about
@modal/ # Parallel route (slot)
(.)photo/[id]/page.tsx # Intercepting route
Dynamic segments:
// app/blog/[slug]/page.tsx
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
return <Article slug={slug} />
}
Catch-all segments:
// app/docs/[...slug]/page.tsx - matches /docs/a, /docs/a/b, etc.
// app/docs/[[...slug]]/page.tsx - also matches /docs
Layouts
// app/layout.tsx - Root layout (required)
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
Nested layout:
// app/dashboard/layout.tsx
export default function DashboardLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<div className="flex">
<Sidebar />
<main className="flex-1">{children}</main>
</div>
)
}
Server Components
Default behavior - all components are Server Components unless marked with 'use client'.
// Server Component (default)
async function Posts() {
const posts = await db.posts.findMany() // Direct DB access
return (
<ul>
{posts.map(post => <li key={post.id}>{post.title}</li>)}
</ul>
)
}
When to use Client Components:
- Event handlers (onClick, onChange)
- State and lifecycle (useState, useEffect)
- Browser APIs
- Custom hooks with state
'use client'
import { useState } from 'react'
export function Counter() {
const [count, setCount] = useState(0)
return <button => setCount(c => c + 1)}>{count}</button>
}
Data Fetching
Server Components (Recommended)
// Direct fetch in Server Component
async function BlogPosts() {
const res = await fetch('https://api.example.com/posts')
const posts = await res.json()
return <PostList posts={posts} />
}
// With ORM
async function Users() {
const users = await prisma.user.findMany()
return <UserList users={users} />
}
Parallel Data Fetching
export default async function Page() {
// Start both requests simultaneously
const postsPromise = getPosts()
const usersPromise = getUsers()
// Await both
const [posts, users] = await Promise.all([postsPromise, usersPromise])
return (
<>
<PostList posts={posts} />
<UserList users={users} />
</>
)
}
Streaming with Suspense
import { Suspense } from 'react'
export default function Page() {
return (
<div>
<h1>Dashboard</h1>
<Suspense fallback={<Skeleton />}>
<SlowComponent />
</Suspense>
</div>
)
}
Server Actions
Basic Form
// app/actions.ts
'use server'
import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'
export async function createPost(formData: FormData) {
const title = formData.get('title') as string
const content = formData.get('content') as string
await db.posts.create({ data: { title, content } })
revalidatePath('/posts')
redirect('/posts')
}
// app/posts/new/page.tsx
import { createPost } from '@/app/actions'
export default function NewPostPage() {
return (
<form action={createPost}>
<input name="title" required />
<textarea name="content" required />
<button type="submit">Create Post</button>
</form>
)
}
With Validation
'use server'
import { z } from 'zod'
const PostSchema = z.object({
title: z.string().min(1).max(100),
content: z.string().min(1),
})
export async function createPost(formData: FormData) {
const validated = PostSchema.safeParse({
title: formData.get('title'),
content: formData.get('content'),
})
if (!validated.success) {
return { error: validated.error.flatten().fieldErrors }
}
await db.posts.create({ data: validated.data })
revalidatePath('/posts')
redirect('/posts')
}
With useActionState
'use client'
import { useActionState } from 'react'
import { createPost } from '@/app/actions'
export function CreatePostForm() {
const [state, action, pending] = useActionState(createPost, null)
return (
<form action={action}>
<input name="title" />
{state?.error?.title && <p>{state.error.title}</p>}
<button disabled={pending}>
{pending ? 'Creating...' : 'Create'}
</button>
</form>
)
}
Caching
Data Cache
// Cached by default (static)
const data = await fetch('https://api.example.com/data')
// Opt out of caching
const data = await fetch('https://api.example.com/data', {
cache: 'no-store'
})
// Time-based revalidation
const data = await fetch('https://api.example.com/data', {
next: { revalidate: 3600 } // 1 hour
})
// Tag-based revalidation
const data = await fetch('https://api.example.com/data', {
next: { tags: ['posts'] }
})
Revalidation
'use server'
import { revalidatePath, revalidateTag } from 'next/cache'
export async function updatePost() {
// Revalidate specific path
revalidatePath('/posts')
// Revalidate by tag
revalidateTag('posts')
// Revalidate layout
revalidatePath('/posts', 'layout')
}
Route Segment Config
// Force dynamic rendering
export const dynamic = 'force-dynamic'
// Revalidate every 60 seconds
export const revalidate = 60
// Generate static params
export async function generateStaticParams() {
const posts = await getPosts()
return posts.map((post) => ({ slug: post.slug }))
}
API Routes (Route Handlers)
// app/api/posts/route.ts
import { NextResponse } from 'next/server'
export async function GET() {
const posts = await db.posts.findMany()
return NextResponse.json(posts)
}
export async function POST(request: Request) {
const body = await request.json()
const post = await db.posts.create({ data: body })
return NextResponse.json(post, { status: 201 })
}
Dynamic route handler:
// app/api/posts/[id]/route.ts
export async function GET(
request: Request,
{ params }: { params: Promise<{ id: string }> }
) {
const { id } = await params
const post = await db.posts.findUnique({ where: { id } })
if (!post) {
return NextResponse.json({ error: 'Not found' }, { status: 404 })
}
return NextResponse.json(post)
}
Middleware
// middleware.ts (root level)
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
export function middleware(request: NextRequest) {
// Check auth
const token = request.cookies.get('token')
if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.redirect(new URL('/login', request.url))
}
// Add headers
const response = NextResponse.next()
response.headers.set('x-custom-header', 'value')
return response
}
export const config = {
matcher: ['/dashboard/:path*', '/api/:path*'],
}
Metadata & SEO
// Static metadata
export const metadata = {
title: 'My App',
description: 'App description',
openGraph: {
title: 'My App',
description: 'App description',
images: ['/og.png'],
},
}
// Dynamic metadata
export async function generateMetadata({ params }) {
const post = await getPost(params.slug)
return {
title: post.title,
description: post.excerpt,
}
}
Image Optimization
import Image from 'next/image'
export function Avatar() {
return (
<Image
src="/avatar.png"
alt="Avatar"
width={64}
height={64}
priority // Above the fold
/>
)
}
// Remote images (configure in next.config.js)
<Image
src="https://example.com/image.jpg"
alt="Remote image"
width={800}
height={600}
/>
Environment Variables
# .env.local (git ignored, local dev)
DATABASE_URL=postgresql://...
SECRET_KEY=abc123
# Public (exposed to browser)
NEXT_PUBLIC_API_URL=https://api.example.com
// Server only
const dbUrl = process.env.DATABASE_URL
// Client accessible
const apiUrl = process.env.NEXT_PUBLIC_API_URL
Common Patterns
Authentication Check
import { cookies } from 'next/headers'
import { redirect } from 'next/navigation'
export default async function ProtectedPage() {
const cookieStore = await cookies()
const session = cookieStore.get('session')
if (!session) {
redirect('/login')
}
return <Dashboard />
}
Error Handling
// app/error.tsx
'use client'
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
return (
<div>
<h2>Something went wrong!</h2>
<button => reset()}>Try again</button>
</div>
)
}
Loading States
// app/dashboard/loading.tsx
export default function Loading() {
return <DashboardSkeleton />
}
Best Practices
- Default to Server Components - Only use Client Components when needed
- Colocate data fetching - Fetch data in the component that needs it
- Use Server Actions for mutations - Not API routes
- Implement proper loading states - Use Suspense and loading.tsx
- Configure caching appropriately - Don't over-cache dynamic content
- Use
generateStaticParams- For static generation of dynamic routes
Common Mistakes
| Mistake | Fix |
|---|---|
Using 'use client' everywhere |
Only use for interactivity |
| Fetching in layout for child data | Fetch in the page/component that needs it |
Not awaiting params/searchParams |
These are now Promises in Next.js 15 |
| Using API routes for mutations | Use Server Actions instead |
| Forgetting to revalidate cache | Call revalidatePath/revalidateTag |
Reference Files
- references/app-router.md - Advanced routing patterns
- references/caching.md - Caching strategies deep dive
- references/server-actions.md - Server Actions patterns
- references/deployment.md - Vercel and self-hosting
Templates
- templates/page.tsx - Page component template
- templates/layout.tsx - Layout component template
- templates/server-action.ts - Server Action template