1# nextjs-app-router-patterns — detailed patterns and worked examples
2 
3## Patterns
4 
5### Pattern 1: Server Components with Data Fetching
6 
7```typescript
8// app/products/page.tsx
9import { Suspense } from 'react'
10import { ProductList, ProductListSkeleton } from '@/components/products'
11import { FilterSidebar } from '@/components/filters'
12 
13interface SearchParams {
14  category?: string
15  sort?: 'price' | 'name' | 'date'
16  page?: string
17}
18 
19export default async function ProductsPage({
20  searchParams,
21}: {
22  searchParams: Promise<SearchParams>
23}) {
24  const params = await searchParams
25 
26  return (
27    <div className="flex gap-8">
28      <FilterSidebar />
29      <Suspense
30        key={JSON.stringify(params)}
31        fallback={<ProductListSkeleton />}
32      >
33        <ProductList
34          category={params.category}
35          sort={params.sort}
36          page={Number(params.page) || 1}
37        />
38      </Suspense>
39    </div>
40  )
41}
42 
43// components/products/ProductList.tsx - Server Component
44async function getProducts(filters: ProductFilters) {
45  const res = await fetch(
46    `${process.env.API_URL}/products?${new URLSearchParams(filters)}`,
47    { next: { tags: ['products'] } }
48  )
49  if (!res.ok) throw new Error('Failed to fetch products')
50  return res.json()
51}
52 
53export async function ProductList({ category, sort, page }: ProductFilters) {
54  const { products, totalPages } = await getProducts({ category, sort, page })
55 
56  return (
57    <div>
58      <div className="grid grid-cols-3 gap-4">
59        {products.map((product) => (
60          <ProductCard key={product.id} product={product} />
61        ))}
62      </div>
63      <Pagination currentPage={page} totalPages={totalPages} />
64    </div>
65  )
66}
67```
68 
69### Pattern 2: Client Components with 'use client'
70 
71```typescript
72// components/products/AddToCartButton.tsx
73'use client'
74 
75import { useState, useTransition } from 'react'
76import { addToCart } from '@/app/actions/cart'
77 
78export function AddToCartButton({ productId }: { productId: string }) {
79  const [isPending, startTransition] = useTransition()
80  const [error, setError] = useState<string | null>(null)
81 
82  const handleClick = () => {
83    setError(null)
84    startTransition(async () => {
85      const result = await addToCart(productId)
86      if (result.error) {
87        setError(result.error)
88      }
89    })
90  }
91 
92  return (
93    <div>
94      <button
95        onClick={handleClick}
96        disabled={isPending}
97        className="btn-primary"
98      >
99        {isPending ? 'Adding...' : 'Add to Cart'}
100      </button>
101      {error && <p className="text-red-500 text-sm">{error}</p>}
102    </div>
103  )
104}
105```
106 
107### Pattern 3: Server Actions
108 
109```typescript
110// app/actions/cart.ts
111"use server";
112 
113import { revalidateTag } from "next/cache";
114import { cookies } from "next/headers";
115import { redirect } from "next/navigation";
116 
117export async function addToCart(productId: string) {
118  const cookieStore = await cookies();
119  const sessionId = cookieStore.get("session")?.value;
120 
121  if (!sessionId) {
122    redirect("/login");
123  }
124 
125  try {
126    await db.cart.upsert({
127      where: { sessionId_productId: { sessionId, productId } },
128      update: { quantity: { increment: 1 } },
129      create: { sessionId, productId, quantity: 1 },
130    });
131 
132    revalidateTag("cart");
133    return { success: true };
134  } catch (error) {
135    return { error: "Failed to add item to cart" };
136  }
137}
138 
139export async function checkout(formData: FormData) {
140  const address = formData.get("address") as string;
141  const payment = formData.get("payment") as string;
142 
143  // Validate
144  if (!address || !payment) {
145    return { error: "Missing required fields" };
146  }
147 
148  // Process order
149  const order = await processOrder({ address, payment });
150 
151  // Redirect to confirmation
152  redirect(`/orders/${order.id}/confirmation`);
153}
154```
155 
156### Pattern 4: Parallel Routes
157 
158```typescript
159// app/dashboard/layout.tsx
160export default function DashboardLayout({
161  children,
162  analytics,
163  team,
164}: {
165  children: React.ReactNode
166  analytics: React.ReactNode
167  team: React.ReactNode
168}) {
169  return (
170    <div className="dashboard-grid">
171      <main>{children}</main>
172      <aside className="analytics-panel">{analytics}</aside>
173      <aside className="team-panel">{team}</aside>
174    </div>
175  )
176}
177 
178// app/dashboard/@analytics/page.tsx
179export default async function AnalyticsSlot() {
180  const stats = await getAnalytics()
181  return <AnalyticsChart data={stats} />
182}
183 
184// app/dashboard/@analytics/loading.tsx
185export default function AnalyticsLoading() {
186  return <ChartSkeleton />
187}
188 
189// app/dashboard/@team/page.tsx
190export default async function TeamSlot() {
191  const members = await getTeamMembers()
192  return <TeamList members={members} />
193}
194```
195 
196### Pattern 5: Intercepting Routes (Modal Pattern)
197 
198```typescript
199// File structure for photo modal
200// app/
201// ├── @modal/
202// │   ├── (.)photos/[id]/page.tsx  # Intercept
203// │   └── default.tsx
204// ├── photos/
205// │   └── [id]/page.tsx            # Full page
206// └── layout.tsx
207 
208// app/@modal/(.)photos/[id]/page.tsx
209import { Modal } from '@/components/Modal'
210import { PhotoDetail } from '@/components/PhotoDetail'
211 
212export default async function PhotoModal({
213  params,
214}: {
215  params: Promise<{ id: string }>
216}) {
217  const { id } = await params
218  const photo = await getPhoto(id)
219 
220  return (
221    <Modal>
222      <PhotoDetail photo={photo} />
223    </Modal>
224  )
225}
226 
227// app/photos/[id]/page.tsx - Full page version
228export default async function PhotoPage({
229  params,
230}: {
231  params: Promise<{ id: string }>
232}) {
233  const { id } = await params
234  const photo = await getPhoto(id)
235 
236  return (
237    <div className="photo-page">
238      <PhotoDetail photo={photo} />
239      <RelatedPhotos photoId={id} />
240    </div>
241  )
242}
243 
244// app/layout.tsx
245export default function RootLayout({
246  children,
247  modal,
248}: {
249  children: React.ReactNode
250  modal: React.ReactNode
251}) {
252  return (
253    <html>
254      <body>
255        {children}
256        {modal}
257      </body>
258    </html>
259  )
260}
261```
262 
263### Pattern 6: Streaming with Suspense
264 
265```typescript
266// app/product/[id]/page.tsx
267import { Suspense } from 'react'
268 
269export default async function ProductPage({
270  params,
271}: {
272  params: Promise<{ id: string }>
273}) {
274  const { id } = await params
275 
276  // This data loads first (blocking)
277  const product = await getProduct(id)
278 
279  return (
280    <div>
281      {/* Immediate render */}
282      <ProductHeader product={product} />
283 
284      {/* Stream in reviews */}
285      <Suspense fallback={<ReviewsSkeleton />}>
286        <Reviews productId={id} />
287      </Suspense>
288 
289      {/* Stream in recommendations */}
290      <Suspense fallback={<RecommendationsSkeleton />}>
291        <Recommendations productId={id} />
292      </Suspense>
293    </div>
294  )
295}
296 
297// These components fetch their own data
298async function Reviews({ productId }: { productId: string }) {
299  const reviews = await getReviews(productId) // Slow API
300  return <ReviewList reviews={reviews} />
301}
302 
303async function Recommendations({ productId }: { productId: string }) {
304  const products = await getRecommendations(productId) // ML-based, slow
305  return <ProductCarousel products={products} />
306}
307```
308 
309### Pattern 7: Route Handlers (API Routes)
310 
311```typescript
312// app/api/products/route.ts
313import { NextRequest, NextResponse } from "next/server";
314 
315export async function GET(request: NextRequest) {
316  const searchParams = request.nextUrl.searchParams;
317  const category = searchParams.get("category");
318 
319  const products = await db.product.findMany({
320    where: category ? { category } : undefined,
321    take: 20,
322  });
323 
324  return NextResponse.json(products);
325}
326 
327export async function POST(request: NextRequest) {
328  const body = await request.json();
329 
330  const product = await db.product.create({
331    data: body,
332  });
333 
334  return NextResponse.json(product, { status: 201 });
335}
336 
337// app/api/products/[id]/route.ts
338export async function GET(
339  request: NextRequest,
340  { params }: { params: Promise<{ id: string }> },
341) {
342  const { id } = await params;
343  const product = await db.product.findUnique({ where: { id } });
344 
345  if (!product) {
346    return NextResponse.json({ error: "Product not found" }, { status: 404 });
347  }
348 
349  return NextResponse.json(product);
350}
351```
352 
353### Pattern 8: Metadata and SEO
354 
355```typescript
356// app/products/[slug]/page.tsx
357import { Metadata } from 'next'
358import { notFound } from 'next/navigation'
359 
360type Props = {
361  params: Promise<{ slug: string }>
362}
363 
364export async function generateMetadata({ params }: Props): Promise<Metadata> {
365  const { slug } = await params
366  const product = await getProduct(slug)
367 
368  if (!product) return {}
369 
370  return {
371    title: product.name,
372    description: product.description,
373    openGraph: {
374      title: product.name,
375      description: product.description,
376      images: [{ url: product.image, width: 1200, height: 630 }],
377    },
378    twitter: {
379      card: 'summary_large_image',
380      title: product.name,
381      description: product.description,
382      images: [product.image],
383    },
384  }
385}
386 
387export async function generateStaticParams() {
388  const products = await db.product.findMany({ select: { slug: true } })
389  return products.map((p) => ({ slug: p.slug }))
390}
391 
392export default async function ProductPage({ params }: Props) {
393  const { slug } = await params
394  const product = await getProduct(slug)
395 
396  if (!product) notFound()
397 
398  return <ProductDetail product={product} />
399}
400```
401 
402## Caching Strategies
403 
404### Data Cache
405 
406```typescript
407// No cache (always fresh)
408fetch(url, { cache: "no-store" });
409 
410// Cache forever (static)
411fetch(url, { cache: "force-cache" });
412 
413// ISR - revalidate after 60 seconds
414fetch(url, { next: { revalidate: 60 } });
415 
416// Tag-based invalidation
417fetch(url, { next: { tags: ["products"] } });
418 
419// Invalidate via Server Action
420("use server");
421import { revalidateTag, revalidatePath } from "next/cache";
422 
423export async function updateProduct(id: string, data: ProductData) {
424  await db.product.update({ where: { id }, data });
425  revalidateTag("products");
426  revalidatePath("/products");
427}
428```
429