Next.js Development Skill
This skill provides comprehensive guidance for building modern Next.js applications using the App Router, Server Components, data fetching patterns, routing, API routes, middleware, and full-stack development techniques based on official Next.js documentation.
When to Use This Skill
Use this skill when:
- Building full-stack React applications with server-side rendering (SSR)
- Creating static sites with incremental static regeneration (ISR)
- Developing modern web applications with React Server Components
- Building API backends with serverless route handlers
- Implementing SEO-optimized applications with metadata and Open Graph
- Creating production-ready web applications with built-in optimization
- Building e-commerce, blogs, dashboards, or content-driven sites
- Implementing authentication, data fetching, and complex routing patterns
- Optimizing images, fonts, and performance automatically
- Deploying serverless applications with edge computing capabilities
Core Concepts
App Router
The App Router is Next.js's modern routing system built on React Server Components. It uses the app directory for file-based routing with enhanced features.
Basic App Structure:
app/
├── layout.tsx # Root layout (required)
├── page.tsx # Home page
├── loading.tsx # Loading UI
├── error.tsx # Error UI
├── not-found.tsx # 404 page
├── about/
│ └── page.tsx # /about route
└── blog/
├── page.tsx # /blog route
├── [slug]/
│ └── page.tsx # /blog/[slug] dynamic route
└── layout.tsx # Blog layout
Root Layout (Required):
tsx
// app/layout.tsx
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
Page Component:
tsx
// app/page.tsx
export default function HomePage() {
return (
<main>
<h1>Welcome to Next.js</h1>
<p>Building modern web applications</p>
</main>
)
}
Server Components
Server Components are React components that render on the server. They are the default in the App Router and provide better performance.
Server Component (Default):
tsx
// app/posts/page.tsx
async function getPosts() {
const res = await fetch('https://api.example.com/posts', {
cache: 'force-cache' // Static generation
})
return res.json()
}
export default async function PostsPage() {
const posts = await getPosts()
return (
<div>
<h1>Blog Posts</h1>
{posts.map((post) => (
<article key={post.id}>
<h2>{post.title}</h2>
<p>{post.excerpt}</p>
</article>
))}
</div>
)
}
Client Component (When Needed):
tsx
'use client'
import { useState } from 'react'
export default function Counter() {
const [count, setCount] = useState(0)
return (
<div>
<p>Count: {count}</p>
<button onClick={() => setCount(count + 1)}>
Increment
</button>
</div>
)
}
Mixing Server and Client Components:
tsx
// app/dashboard/page.tsx (Server Component)
import ClientCounter from './ClientCounter'
async function getData() {
const res = await fetch('https://api.example.com/data')
return res.json()
}
export default async function DashboardPage() {
const data = await getData()
return (
<div>
<h1>Dashboard</h1>
<p>Server data: {data.value}</p>
{/* Client component for interactivity */}
<ClientCounter />
</div>
)
}
Data Fetching
Next.js extends the native fetch() API with automatic caching and revalidation.
Static Data Fetching (Default):
tsx
async function getStaticData() {
const res = await fetch('https://api.example.com/data', {
cache: 'force-cache' // Default, equivalent to getStaticProps
})
return res.json()
}
export default async function Page() {
const data = await getStaticData()
return <div>{data.title}</div>
}
Dynamic Data Fetching:
tsx
async function getDynamicData() {
const res = await fetch('https://api.example.com/data', {
cache: 'no-store' // Equivalent to getServerSideProps
})
return res.json()
}
export default async function Page() {
const data = await getDynamicData()
return <div>{data.title}</div>
}
Revalidation (ISR):
tsx
async function getRevalidatedData() {
const res = await fetch('https://api.example.com/data', {
next: { revalidate: 60 } // Revalidate every 60 seconds
})
return res.json()
}
export default async function Page() {
const data = await getRevalidatedData()
return <div>{data.title}</div>
}
Parallel Data Fetching:
tsx
async function getUser(id: string) {
const res = await fetch(`https://api.example.com/users/${id}`)
return res.json()
}
async function getUserPosts(id: string) {
const res = await fetch(`https://api.example.com/users/${id}/posts`)
return res.json()
}
export default async function UserPage({ params }: { params: { id: string } }) {
// Fetch in parallel
const [user, posts] = await Promise.all([
getUser(params.id),
getUserPosts(params.id)
])
return (
<div>
<h1>{user.name}</h1>
<ul>
{posts.map((post) => (
<li key={post.id}>{post.title}</li>
))}
</ul>
</div>
)
}
Sequential Data Fetching:
tsx
async function getUser(id: string) {
const res = await fetch(`https://api.example.com/users/${id}`)
return res.json()
}
async function getRecommendations(preferences: string[]) {
const res = await fetch('https://api.example.com/recommendations', {
method: 'POST',
body: JSON.stringify({ preferences })
})
return res.json()
}
export default async function UserPage({ params }: { params: { id: string } }) {
// First fetch user
const user = await getUser(params.id)
// Then fetch recommendations based on user data
const recommendations = await getRecommendations(user.preferences)
return (
<div>
<h1>{user.name}</h1>
<h2>Recommendations</h2>
<ul>
{recommendations.map((item) => (
<li key={item.id}>{item.title}</li>
))}
</ul>
</div>
)
}
Routing
Next.js uses file-system based routing in the app directory.
Dynamic Routes:
tsx
// app/blog/[slug]/page.tsx
export default function BlogPost({ params }: { params: { slug: string } }) {
return <h1>Post: {params.slug}</h1>
}
// Generates static pages for these slugs at build time
export async function generateStaticParams() {
const posts = await fetch('https://api.example.com/posts').then(r => r.json())
return posts.map((post) => ({
slug: post.slug,
}))
}
Catch-All Routes:
tsx
// app/docs/[...slug]/page.tsx
export default function DocsPage({ params }: { params: { slug: string[] } }) {
// /docs/a/b/c -> params.slug = ['a', 'b', 'c']
return <h1>Docs: {params.slug.join('/')}</h1>
}
Optional Catch-All Routes:
tsx
// app/shop/[[...slug]]/page.tsx
export default function ShopPage({ params }: { params: { slug?: string[] } }) {
// /shop -> params.slug = undefined
// /shop/clothes -> params.slug = ['clothes']
// /shop/clothes/tops -> params.slug = ['clothes', 'tops']
return <h1>Shop: {params.slug?.join('/') || 'All'}</h1>
}
Route Groups:
app/
├── (marketing)/ # Route group (not in URL)
│ ├── about/
│ │ └── page.tsx # /about
│ └── contact/
│ └── page.tsx # /contact
└── (shop)/
├── products/
│ └── page.tsx # /products
└── cart/
└── page.tsx # /cart
Parallel Routes:
app/
├── @analytics/
│ └── page.tsx
├── @team/
│ └── page.tsx
└── layout.tsx
// app/layout.tsx
export default function Layout({
children,
analytics,
team,
}: {
children: React.ReactNode
analytics: React.ReactNode
team: React.ReactNode
}) {
return (
<>
{children}
{analytics}
{team}
</>
)
}
Intercepting Routes:
app/
├── feed/
│ └── page.tsx
├── photo/
│ └── [id]/
│ └── page.tsx
└── @modal/
└── (.)photo/
└── [id]/
└── page.tsx # Intercepts /photo/[id] when navigating from /feed
Layouts
Layouts wrap pages and preserve state across navigation.
Nested Layouts:
tsx
// app/layout.tsx (Root Layout)
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<header>
<nav>Global Navigation</nav>
</header>
{children}
<footer>Global Footer</footer>
</body>
</html>
)
}
// app/dashboard/layout.tsx (Dashboard Layout)
export default function DashboardLayout({ children }: { children: React.ReactNode }) {
return (
<div className="dashboard">
<aside>Dashboard Sidebar</aside>
<main>{children}</main>
</div>
)
}
// app/dashboard/page.tsx
export default function DashboardPage() {
return <h1>Dashboard</h1>
}
Templates (Re-render on Navigation):
tsx
// app/template.tsx
export default function Template({ children }: { children: React.ReactNode }) {
return (
<div>
{/* This creates a new instance on each navigation */}
{children}
</div>
)
}
Loading UI
Special loading.tsx files create loading states with React Suspense.
Loading State:
tsx
// app/dashboard/loading.tsx
export default function Loading() {
return (
<div className="spinner">
<p>Loading dashboard...</p>
</div>
)
}
// app/dashboard/page.tsx
async function getData() {
const res = await fetch('https://api.example.com/data')
return res.json()
}
export default async function DashboardPage() {
const data = await getData()
return <div>{data.content}</div>
}
Streaming with Suspense:
tsx
// app/page.tsx
import { Suspense } from 'react'
async function SlowComponent() {
await new Promise(resolve => setTimeout(resolve, 3000))
return <div>Slow data loaded</div>
}
export default function Page() {
return (
<div>
<h1>Page</h1>
<Suspense fallback={<div>Loading slow component...</div>}>
<SlowComponent />
</Suspense>
</div>
)
}
Error Handling
Special error.tsx files handle errors with error boundaries.
Error Boundary:
tsx
// app/error.tsx
'use client' // Error components must be Client Components
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
return (
<div>
<h2>Something went wrong!</h2>
<p>{error.message}</p>
<button onClick={() => reset()}>Try again</button>
</div>
)
}
Global Error:
tsx
// app/global-error.tsx
'use client'
export default function GlobalError({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
return (
<html>
<body>
<h2>Application Error</h2>
<button onClick={() => reset()}>Try again</button>
</body>
</html>
)
}
Not Found:
tsx
// app/not-found.tsx
import Link from 'next/link'
export default function NotFound() {
return (
<div>
<h2>Page Not Found</h2>
<p>Could not find the requested resource</p>
<Link href="/">Return Home</Link>
</div>
)
}
API Routes
Route Handlers allow you to create API endpoints using Web Request and Response APIs.
Basic API Route:
tsx
// app/api/hello/route.ts
export async function GET(request: Request) {
return Response.json({ message: 'Hello from Next.js!' })
}
Dynamic Route Handler:
tsx
// app/api/posts/[id]/route.ts
export async function GET(
request: Request,
{ params }: { params: { id: string } }
) {
const id = params.id
const post = await db.post.findUnique({ where: { id } })
if (!post) {
return new Response('Post not found', { status: 404 })
}
return Response.json(post)
}