How do Route Handlers interact with Next.js caching? How do you make a Route Handler static vs dynamic?

Question

Accepted Answer

Route Handlers in Next.js have a sophisticated relationship with the framework's caching layers. Unlike Pages Router API routes, which were always dynamic by default, Route Handlers follow a more nuanced model: they can be statically generated at build time, dynamically executed on every request, or cached with ISR-style revalidation. The default behavior changed in Next.js 15—GET handlers are now dynamic by default [citation:4], but you have explicit control through route segment configuration options that determine how and when your handlers execute and cache responses [citation:1]. GET methods: As of Next.js 15, GET handlers are dynamic by default (they run on each request), though in earlier versions they were static by default [citation:4]. Other HTTP methods: POST, PUT, PATCH, DELETE, HEAD, and OPTIONS are never cached, regardless of configuration [citation:10]. Special handlers: sitemap.ts, opengraph-image.tsx, icon.tsx and other metadata files remain static by default unless they use dynamic APIs [citation:3]. Static detection: Next.js determines if a handler can be static based on whether it uses dynamic APIs like cookies(), headers(), or request-specific properties [citation:4]. ```tsx
// app/api/products/route.ts
// Static route handler - cached at build time

export const dynamic = 'force-static' // Forces static generation [citation:1]

export async function GET() {
  // This fetch will be evaluated at build time and cached
  const products = await fetch('https://api.example.com/products', {
    next: { revalidate: 3600 } // Optional ISR revalidation [citation:6]
  }).then(r => r.json())
  
  return Response.json(products)
}

// Build output shows: ○ /api/products (static) [citation:5]
``` ```tsx
// app/api/user/route.ts
// Dynamic route handler - runs on every request

export const dynamic = 'force-dynamic' // Forces per-request execution [citation:4]

// Alternative: Use dynamic APIs to automatically opt-in
import { cookies } from 'next/headers'

export async function GET() {
  const cookieStore = await cookies() // Automatically makes handler dynamic [citation:6]
  const token = cookieStore.get('token')
  
  const user = await fetch(`https://api.example.com/user`, {
    headers: { Authorization: `Bearer ${token?.value}` }
  }).then(r => r.json())
  
  return Response.json(user)
}

// Build output shows: λ /api/user (dynamic) [citation:5]
``` Route Handlers support ISR-style revalidation, giving you the performance of static generation with periodic updates. You can combine `export const dynamic = 'force-static'` with either the `revalidate` segment config or fetch-level `next.revalidate` options [citation:6]. The lowest revalidate value across the route determines the revalidation frequency [citation:1]. This is particularly useful for data that changes occasionally but doesn't need to be fresh on every request. ```tsx
// app/api/posts/route.ts
// ISR-style caching with time-based revalidation

// Option 1: Segment-level revalidate [citation:1]
export const dynamic = 'force-static'
export const revalidate = 3600 // Revalidate every hour

export async function GET() {
  const posts = await fetch('https://api.example.com/posts').then(r => r.json())
  return Response.json(posts)
}

// Option 2: Fetch-level revalidate (overrides segment) [citation:6]
export const dynamic = 'force-static'

export async function GET() {
  const posts = await fetch('https://api.example.com/posts', {
    next: { revalidate: 3600 } // More granular control
  }).then(r => r.json())
  
  return Response.json(posts)
}
``` For more sophisticated caching strategies, Route Handlers can participate in Next.js's tag-based revalidation system. By adding tags to fetch requests, you can programmatically invalidate cached responses using `revalidateTag()` from anywhere in your application [citation:1]. This is ideal for CMS-driven content where you want to update the cache immediately when content changes, rather than waiting for a time-based revalidation window. ```tsx
// app/api/posts/route.ts
// Cache with tags for on-demand invalidation

export const dynamic = 'force-static'

export async function GET() {
  const posts = await fetch('https://api.example.com/posts', {
    next: { 
      tags: ['posts'], // Tag for targeted invalidation [citation:1]
      revalidate: 3600 // Fallback revalidate
    }
  }).then(r => r.json())
  
  return Response.json(posts)
}

// In another route or server action:
// await revalidateTag('posts') // Invalidates all tagged routes
``` Check build output: Run `next build` and examine the route table. '○' indicates static routes, 'λ' indicates dynamic routes [citation:5]. Inspect response headers: Static routes return `x-nextjs-cache: HIT` or `STALE`; dynamic routes show `MISS` or no cache header [citation:7]. Use dynamic APIs intentionally: Adding `cookies()`, `headers()`, or accessing request properties automatically opts into dynamic rendering [citation:4]. Check your Next.js version: Versions p

How do Route Handlers interact with Next.js caching? How do you make a Route Handler static vs dynamic?

Route Handlers integrate with Next.js caching through segment config options: use 'force-static' to cache GET responses at build time (like SSG) and 'force-dynamic' for request-time execution (like SSR), with granular controls via revalidate and fetch options

Scenario Questions

Follow-up Questions