Coder Legion - Recent posts tagged app-router

Error Handling in Next.js 16: The Complete 2026 Guide

Wed, 19 Aug 2026 06:18:11 +0000

Ever shipped a Next.js app, then watched one bad API response take down the entire page — header, sidebar, footer, everything — just because one component threw an error? You're not alone. It's one of the most common "gotchas" for developers moving from pages/ to the App Router.

The good news: Next.js 16 gives you a proper, file-based system for handling errors at exactly the level you want — a single component, a whole route segment, or the entire app. No more wrapping every component in a manual try/catch and hoping for the best.

By the end of this guide, you'll know exactly which error file to use and when, how to handle errors in Server Actions and Route Handlers the right way, and how to avoid the mistakes that leave users staring at a blank white screen in production.

Situation	Use
Rendering error	error.tsx
Root layout crash	global-error.tsx
Missing resource	not-found.tsx
Unknown URL	global-not-found.tsx
Form submission	Server Action
API endpoint	Route Handler

Why This Is Tricky

In the old Pages Router, error handling meant a single _error.js file for your whole app — crude, but simple. The App Router splits rendering into Server Components, Client Components, Server Actions, and Route Handlers, and each one fails differently:

A Server Component can throw during data fetching
A Client Component can throw during rendering
A Server Action can fail during a form submission
A Route Handler (API route) can fail while processing a request

Each of these needs its own handling strategy — that's why Next.js gives you multiple tools instead of one. Let's go through them one by one.

💡 Prerequisites: This guide uses Next.js 16 (App Router), TypeScript in strict mode, React Compiler (enabled by default, so no manual useMemo/useCallback needed), and Tailwind CSS for styling. Node.js 20.9+ is required.

Step 1: Catch Rendering Errors with `error.tsx`

An error boundary is a component that catches errors happening below it in the tree and shows a fallback UI instead of crashing everything. Next.js builds this in automatically — you just add a file called error.tsx to any route segment (a folder inside app/).

// app/dashboard/error.tsx
"use client"; // error.tsx must always be a Client Component

import { useEffect } from "react";

interface ErrorPageProps {
  error: Error & { digest?: string };
  reset: () => void;
}

const DashboardError = ({ error, reset }: ErrorPageProps) => {
  useEffect(() => {
    // Send the error to your monitoring tool (Sentry, Datadog, etc.)
    console.error("Dashboard error:", error);
  }, [error]);

  return (
    <div className="flex flex-col items-center justify-center gap-4 p-10 text-center">
      <h2 className="text-xl font-bold">Something went wrong</h2>
      <p className="text-sm text-gray-500">
        We couldn&apos;t load your dashboard. This has been logged.
      </p>
      <button
        onClick={() => reset()}
        className="rounded-md bg-black px-4 py-2 text-white"
      >
        Try again
      </button>
    </div>
  );
};

export default DashboardError;

What just happened:

Next.js automatically wraps the route segment in a React error boundary and renders this file when a rendering error occurs
error is the thrown error object. In production, Next.js strips sensitive details and only sends a generic message plus a digest — a hash you can match against your server logs
reset() tells React to try rendering the segment again — useful for transient errors like a flaky network request
The useEffect is where you report the error to a monitoring service, since error.tsx won't automatically show up in your logging tool

⚠️ Common Mistake: Putting error.tsx at the root of app/ and expecting it to catch everything. It can't — see Step 2.

Scoping Errors to the Right Level

Place error.tsx inside the specific folder you want to protect. A crash in one section won't take down the rest of the app.
Think of error.tsx like nested try/catch blocks. Next.js always looks for the nearest boundary first, then continues bubbling upward until it finds one.

app/
  dashboard/
    layout.tsx        ← sidebar stays visible even if a child crashes
    page.tsx
    error.tsx          ← catches errors from all dashboard routes
    analytics/
      page.tsx
      error.tsx        ← catches errors only in /dashboard/analytics
    settings/
      page.tsx         ← no error.tsx here, so errors bubble up to dashboard/error.tsx

If /dashboard/analytics crashes, only that section shows the fallback — the sidebar in layout.tsx keeps working. If /dashboard/settings crashes, since it has no error.tsx of its own, the error bubbles up to dashboard/error.tsx.

Step 2: Handle Root Layout Errors with `global-error.tsx`

There's one blind spot error.tsx can't cover: errors thrown inside the root layout itself (app/layout.tsx). Since the root layout wraps your entire app — including every error.tsx boundary — it needs its own separate mechanism.

// app/global-error.tsx
"use client";

interface GlobalErrorProps {
  error: Error & { digest?: string };
  reset: () => void;
}

const GlobalError = ({ error, reset }: GlobalErrorProps) => {
  return (
    <html>
      <body>
        <div style={{ textAlign: "center", padding: "3rem" }}>
          <h2>Something went seriously wrong</h2>
          <p>We&apos;ve been notified and are looking into it.</p>
          <button onClick={() => reset()}>Try again</button>
        </div>
      </body>
    </html>
  );
};

export default GlobalError;

What just happened: Because global-error.tsx replaces the entire root layout when it triggers, it has to define its own <html> and <body> tags — your normal fonts, providers, and navigation won't be available. Keep this file as simple and dependency-free as possible, since if the root layout crashed, you can't assume anything else in your app still works.

💡 Tip: For most apps, you'll rarely see global-error.tsx fire — root layout crashes are uncommon. But always keep the file in place as a safety net so users never see a completely broken, unstyled page.

Step 3: Handle "Not Found" Cases

A 404 happens when a user hits a URL that doesn't exist, or when you explicitly know a resource is missing (like a product ID that doesn't exist in your database). Next.js 16 gives you two files for this.

`not-found.tsx` for a Specific Segment

// app/blog/[slug]/not-found.tsx
const PostNotFound = () => {
  return (
    <div className="p-10 text-center">
      <h2 className="text-2xl font-bold">Post not found</h2>
      <p className="text-gray-500">This blog post doesn&apos;t exist or was removed.</p>
    </div>
  );
};

export default PostNotFound;

Trigger it explicitly by calling the notFound() function anywhere in a Server Component:

// app/blog/[slug]/page.tsx
import { notFound } from "next/navigation";
import { getPostBySlug } from "@/lib/posts";

interface Props {
  params: Promise<{ slug: string }>; // params is always a Promise in Next.js 16
}

const BlogPostPage = async ({ params }: Props) => {
  const { slug } = await params; // must be awaited
  const post = await getPostBySlug(slug);

  if (!post) {
    notFound(); // renders the nearest not-found.tsx
  }

  return <article>{post.content}</article>;
};

export default BlogPostPage;

What just happened: notFound() throws a special signal that Next.js catches internally and renders the closest not-found.tsx up the tree — similar to how error.tsx catches thrown errors, but specifically for missing content. It also correctly returns a 404 HTTP status, which matters for SEO.

`global-not-found.tsx` for Unmatched URLs (New in Next.js 16)

If someone visits a URL that doesn't match any route at all — a typo, an old bookmarked link — Next.js needs a catch-all 404 page for your whole app. In most apps, a root-level app/not-found.tsx already handles this. But if your app has multiple root layouts (like separate (admin) and (shop) groups) or a root layout built on a dynamic segment like app/[country]/layout.tsx, there's no single layout to render a 404 through — which is exactly the gap global-not-found.tsx closes.

First, enable it in your config:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    globalNotFound: true,
  },
};

export default nextConfig;

Then create the file at the root of app/:

// app/global-not-found.tsx
const GlobalNotFound = () => {
  return (
    <html>
      <body>
        <div style={{ textAlign: "center", padding: "3rem" }}>
          <h1>404 — Page not found</h1>
          <p>The page you&apos;re looking for doesn&apos;t exist.</p>
        </div>
      </body>
    </html>
  );
};

export default GlobalNotFound;

⚠️ Common Mistake: Like global-error.tsx, this file renders outside your normal root layout, so it needs its own <html> and <body> tags too.

Step 4: Handle Errors in Server Actions

Server Actions are trickier than page rendering — a thrown error there doesn't show your error.tsx UI cleanly, it just rejects the promise. The production-safe pattern is to avoid throwing for expected failures such as validation errors, and instead return a typed result the client can check.

// actions/posts.ts
"use server";

import { z } from "zod";
import { db } from "@/lib/db";
import { updateTag } from "next/cache";

const CreatePostSchema = z.object({
  title: z.string().min(1, "Title is required"),
  body: z.string().min(1, "Body is required"),
});

export const createPost = async (_prev: unknown, formData: FormData) => {
  const parsed = CreatePostSchema.safeParse({
    title: formData.get("title"),
    body: formData.get("body"),
  });

  if (!parsed.success) {
    return { error: parsed.error.flatten().fieldErrors };
  }

  try {
    const post = await db.post.create({ data: parsed.data });
    updateTag("posts"); // instantly reflects the new post
    return { data: post };
  } catch (err) {
    console.error("Failed to create post:", err);
    return { error: { _form: ["Something went wrong. Please try again."] } };
  }
};

Then consume it on the client with useActionState:

// app/posts/_new-post-client.tsx
"use client";

import { useActionState } from "react";
import { createPost } from "@/actions/posts";

export const NewPostForm = () => {
  const [state, formAction, isPending] = useActionState(createPost, null);

  return (
    <form action={formAction} className="flex flex-col gap-3">
      <input name="title" placeholder="Title" className="border p-2" />
      {state?.error && "title" in state.error && (
        <p className="text-sm text-red-500">{state.error.title?.[0]}</p>
      )}

      <textarea name="body" placeholder="Body" className="border p-2" />

      <button disabled={isPending} className="rounded-md bg-black px-4 py-2 text-white">
        {isPending ? "Publishing..." : "Publish"}
      </button>
    </form>
  );
};

What just happened: safeParse validates the form data with Zod before it ever touches your database — this catches bad input early and cheaply. The try/catch around the database call handles unexpected failures (a dropped connection, a constraint violation) and turns them into a friendly { error } object instead of an unhandled crash. useActionState gives you state (the last returned value), formAction (to bind to the form), and isPending (to disable the button while submitting) — all without extra useState boilerplate.

💡 Tip: The rule of thumb: validation errors and expected failures → return { error }. Truly unexpected, unrecoverable errors → let them throw so Next.js's error boundary can catch them upstream.

Step 5: Handle Errors in Route Handlers (API Routes)

Route Handlers don't have an error boundary at all — if you don't catch an error yourself, the client just gets a generic 500 response with no useful detail.

// app/api/posts/route.ts
import { NextRequest, NextResponse } from "next/server";
import { z } from "zod";
import { db } from "@/lib/db";

const PostSchema = z.object({
  title: z.string().min(1),
  body: z.string().min(1),
});

export const POST = async (req: NextRequest) => {
  try {
    const body: unknown = await req.json();
    const parsed = PostSchema.safeParse(body);

    if (!parsed.success) {
      return NextResponse.json(
        { error: parsed.error.flatten() },
        { status: 400 },
      );
    }

    const post = await db.post.create({ data: parsed.data });
    return NextResponse.json(post, { status: 201 });
  } catch (err) {
    console.error("POST /api/posts failed:", err);
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 },
    );
  }
};

What just happened: Every branch returns a proper NextResponse with an accurate status code — 400 for bad input the client sent, 500 for something that broke on your end. Wrapping the whole handler body in try/catch means a database outage returns a clean JSON error instead of the request just hanging or crashing the server process.

💡 Tip: Reserve 4xx responses for problems caused by the client (validation, authentication, missing resources) and 5xx responses for unexpected server failures. This distinction makes your API easier to debug and integrates better with monitoring systems.

⚠️ Common Mistake: Returning err.message directly to the client in the 500 response. Internal error messages can leak details about your database or file structure — log the real error server-side, and send the client a generic message.

Frequently Asked Questions

Does `error.tsx` catch errors in event handlers, like an `onClick`?

No. Error boundaries only catch errors thrown during rendering — not inside event handlers, setTimeout callbacks, or async code running after the render finished. Wrap those in a regular try/catch inside the handler itself.

Can `error.tsx` be a Server Component?

No, it must always start with "use client". React error boundaries are a client-side concept, and Next.js enforces this at build time.

What's the actual difference between `error.tsx` and `not-found.tsx`?

error.tsx catches unexpected thrown errors — bugs, failed fetches, crashes. not-found.tsx is for the expected case of "this specific thing doesn't exist," triggered on purpose by calling notFound(). Different problem, different UI, different HTTP status code.

Do I need `global-error.tsx` if I already have `error.tsx` everywhere?

Yes, keep it. error.tsx files can't catch errors thrown in the root layout itself (things like a provider that crashes on init), since the root layout wraps every error.tsx boundary you have.

💡 Tip: Think of it like a fuse box — error.tsx protects individual circuits (routes), while global-error.tsx is the master breaker for the whole house.

Should I use Sentry or a similar tool instead of just `console.error`?

For production apps, yes. console.error inside error.tsx is a starting point, but without a monitoring service you won't know an error happened until a user complains. Most teams call Sentry.captureException(error) (or an equivalent) inside the useEffect in error.tsx, and wrap Server Actions with the framework's server-action instrumentation to link client and server error traces together.

Wrapping Up

You now know how to scope error boundaries with error.tsx, catch root-layout crashes with global-error.tsx, handle missing content with not-found.tsx and the new global-not-found.tsx, and return safe, typed errors from Server Actions and Route Handlers instead of letting them crash silently. Put these in place before you need them — retrofitting error handling after a production incident is a much worse day than setting it up now.

Next, it's worth pairing this with proper loading states — Next.js Rendering Strategies Explained covers Suspense streaming so your loading and error boundaries work together for a fully resilient UI.

Continue Learning

Route Handlers Explained in Next.js 16 (Beginner's Guide) — goes deeper into building typed API endpoints, the same ones you're wrapping in try/catch in Step 5.
Next.js Rendering Strategies Explained: SSR, SSG, CSR, ISR & Cache Components (2026) — pairs naturally with error boundaries since Suspense streaming and error handling are designed to work together.
Next.js 16 Routing Explained: A Complete Beginner's Guide (2026) — covers how error.tsx, not-found.tsx, and other special files fit into the App Router's file-system conventions.
Zod vs Yup in 2026: Which Validation Library Should You Use? — if you want a deeper look at the safeParse validation pattern used in the Server Actions example above.

Route Handlers Explained in Next.js 16 (Beginner's Guide)

Thu, 13 Aug 2026 05:30:25 +0000

You've built pages, you've built layouts, and now you need something that isn't a page at all — a webhook endpoint for Stripe, a JSON API for a mobile app, or a route that generates a CSV file on demand. None of that fits inside a page.tsx. That's exactly the gap Route Handlers fill in the Next.js App Router.

If you've used the old Pages Router, Route Handlers are the direct replacement for pages/api. If you're coming from Express or another Node framework, think of them as your app.get() and app.post() — just organized by folder structure instead of a router file.

By the end of this guide, you'll know exactly how Route Handlers work in Next.js 16, how they're different from Server Actions, how caching behaves with the new Cache Components model, and how to build a real, typed API endpoint — including handling dynamic routes and webhooks.

Here's the whole picture at a glance before we dive in step by step:

What Are Route Handlers, Exactly?

A Route Handler is a function that runs on the server and responds to an HTTP request — no HTML, no React, just data. You define one inside a special file named route.ts, and it can live anywhere inside your app directory.

// app/api/hello/route.ts
export async function GET() {
  return Response.json({ message: "Hello from Next.js 16!" })
}

Visit /api/hello in your browser, and you'll get back that JSON — no page rendered, just a raw HTTP response.

💡 Tip: Route Handlers use the standard Web Request and Response APIs — the same ones built into browsers and modern JavaScript runtimes — not the old Express-style req/res objects. That means the skills you learn here also apply outside Next.js.

Why This Is Tricky (For Beginners)

New Next.js developers usually hit two points of confusion:

"Isn't this just an API Route?" — Sort of, but Route Handlers live in app/ and use a completely different file convention (route.ts instead of pulling from pages/api).
"Should I use a Route Handler or a Server Action?" — Both let you run server-side code, but they solve different problems, and picking the wrong one leads to unnecessary complexity later.

Let's clear both of those up before touching any code.

Route Handlers vs. Pages Router API Routes

If you're migrating from the Pages Router, pages/api/hello.ts becomes app/api/hello/route.ts. The concept is identical — a folder-based endpoint — but the syntax changes from a single default export to named exports per HTTP method.

Good to know: You never need to mix API Routes and Route Handlers in the same project. If your project uses the app directory, Route Handlers are your only option for API-style endpoints — the Pages Router pattern doesn't apply anymore.

Route Handlers vs. Server Actions

This is the question that trips up almost everyone, so here's the short version:

	Route Handlers	Server Actions
Called from	Anywhere (browser, mobile app, another server, `curl`)	Only from inside your own React components
Best for	Public APIs, webhooks, third-party integrations	Form submissions, internal data mutations
HTTP control	Full — you choose methods, headers, status codes	Handled for you automatically
URL	Has a real, callable URL	No public URL of its own

Rule of thumb: if something outside your Next.js app (a webhook from Stripe, a mobile client, a public API consumer) needs to call this code, use a Route Handler. If it's a form or button inside your own app calling a server function, a Server Action is simpler and does less boilerplate for you.

Prerequisites

This guide uses:

Next.js 16 with the App Router
TypeScript in strict mode
React Compiler enabled (not directly relevant to Route Handlers, but assumed as the project default)

You don't need any extra packages — everything here ships with Next.js out of the box.

Step 1: The `route.ts` File Convention

A Route Handler is created by adding a route.ts (or route.js) file inside any folder in app/. The folder path becomes the URL.

app/
└── api/
    └── hello/
        └── route.ts       → /api/hello

// app/api/hello/route.ts
export async function GET(request: Request) {
  return Response.json({ message: "Hello, world!" })
}

What's happening here: exporting a function named GET tells Next.js "handle GET requests to this route with this function." The function receives the standard Web Request object and must return a Response (or NextResponse, which extends it).

⚠️ Common Mistake: A route.ts file cannot live in the same folder as a page.tsx at the same segment. app/page.tsx and app/route.ts together will throw a build error — Next.js doesn't know whether that URL should render a page or run an API handler. Nest your Route Handler under a different segment, like app/api/..., instead.

Step 2: Supported HTTP Methods

Route Handlers support the standard HTTP verbs as named exports in the same file: GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS.

// app/api/todos/route.ts
export async function GET() {
  const todos = await getTodosFromDb()
  return Response.json(todos)
}

export async function POST(request: Request) {
  const body = await request.json()
  const newTodo = await createTodo(body)
  return Response.json(newTodo, { status: 201 })
}

What's happening here: one file now handles two different behaviors depending on the incoming HTTP method — a GET request lists todos, a POST request creates one. If a client sends a method you haven't exported (like DELETE on a file with only GET/POST), Next.js automatically responds with a 405 Method Not Allowed — you don't need to handle that yourself.

💡 Tip: Next.js also auto-implements a sensible OPTIONS response for you if you don't define one, which is useful for CORS preflight requests (more on that below).

Response vs. NextResponse, Request vs. NextRequest

Before going further, it's worth clearing up which object to reach for — they show up interchangeably in examples online, which confuses a lot of beginners.

Request / Response — the plain Web APIs, built into the JavaScript runtime itself, not Next.js-specific. Use these when you don't need anything extra — a simple JSON response, or reading a body with request.json().
NextRequest (from next/server) — extends Request with Next.js-only conveniences, most notably request.nextUrl (an already-parsed URL object) and request.cookies. Reach for this the moment you need query params or cookies without manually parsing the URL string.
NextResponse (from next/server) — extends Response with helpers like NextResponse.redirect(), NextResponse.rewrite(), and easier cookie-setting via response.cookies.set(). Use this when you need to redirect, rewrite, or set cookies on the way out.

💡 Tip: A good default: start with plain Request/Response.json() for simple handlers, and upgrade to NextRequest/NextResponse only when you actually need one of their extra features. Both pairs are fully interoperable — a function typed to accept NextRequest still works fine if you never end up using the extra methods.

Step 3: Reading Data From the Request

Most real endpoints need to read something — a JSON body, a query parameter, or a header.

// app/api/search/route.ts
import { NextRequest } from "next/server"

export async function GET(request: NextRequest) {
  // Reading a query param: /api/search?q=nextjs
  const query = request.nextUrl.searchParams.get("q")

  if (!query) {
    return Response.json({ error: "Missing 'q' parameter" }, { status: 400 })
  }

  const results = await searchDatabase(query)
  return Response.json(results)
}

What's happening here: NextRequest (imported from next/server) extends the standard Request with convenience helpers — request.nextUrl gives you an already-parsed URL object, so searchParams.get("q") is easier than manually parsing request.url with the native URL class.

For a JSON body on a POST or PUT request, use request.json():

// app/api/contact/route.ts
export async function POST(request: Request) {
  const { email, message } = await request.json()

  if (!email || !message) {
    return Response.json(
      { error: "Email and message are required" },
      { status: 400 }
    )
  }

  await sendContactEmail({ email, message })
  return Response.json({ success: true })
}

⚠️ Common Mistake: Never trust that email and message exist just because your frontend form requires them. Anyone can send a raw POST request straight to /api/contact with curl, skipping your form entirely — always validate on the server, ideally with a schema library like Zod.

Step 4: Dynamic Route Segments

Just like pages, Route Handlers support dynamic segments using square brackets.

app/
└── users/
    └── [id]/
        └── route.ts        → /users/123, /users/456, etc.

In Next.js 16, the recommended way to type the dynamic segment is the built-in RouteContext helper — it's generated automatically for you based on your actual route structure.

// app/users/[id]/route.ts
import type { NextRequest } from "next/server"

export async function GET(
  request: NextRequest,
  ctx: RouteContext<"/users/[id]">
) {
  const { id } = await ctx.params
  const user = await getUserById(id)

  if (!user) {
    return Response.json({ error: "User not found" }, { status: 404 })
  }

  return Response.json(user)
}

What's happening here: ctx.params is a Promise — this matches the same async params convention used in page.tsx files throughout Next.js 16, so you must await it before reading id. RouteContext<"/users/[id]"> gives you full type-safety without manually writing an interface for every dynamic route.

Good to know: These types are generated when you run next dev, next build, or next typegen — if your editor shows a type error right after creating a new dynamic route, running one of those commands usually fixes it.

Step 5: Caching Behavior

This trips up a lot of people coming from the Pages Router, where API Routes were never cached. In the App Router, it's a little more nuanced.

The short version: Route Handlers are not cached by default. Only GET handlers can opt into caching — every other method (POST, PUT, DELETE, etc.) is always dynamic, even if you configure caching in the same file.

To force a GET handler to be cached as static:

// app/items/route.ts
export const dynamic = "force-static"

export async function GET() {
  const res = await fetch("https://data.example.com/items")
  const data = await res.json()
  return Response.json({ data })
}

If You're Using Cache Components (`"use cache"`)

If your project has Cache Components enabled, GET Route Handlers behave exactly like a normal page: they run dynamically by default, but can be pre-rendered at build time if they don't touch anything request-specific.

// app/api/project-info/route.ts
// No dynamic data — this gets pre-rendered at build time
export async function GET() {
  return Response.json({ projectName: "DevStacked" })
}

// app/api/user-agent/route.ts
import { headers } from "next/headers"

// Reads a request-specific header — this forces the route to run per-request
export async function GET() {
  const headersList = await headers()
  const userAgent = headersList.get("user-agent")
  return Response.json({ userAgent })
}

If you need to mix cached data with per-request logic, pull the cached part into its own function using "use cache" — you can't put "use cache" directly inside the Route Handler body itself.

// app/api/products/route.ts
import { cacheLife } from "next/cache"

export async function GET() {
  const products = await getProducts()
  return Response.json(products)
}

async function getProducts() {
  "use cache"
  cacheLife("hours")

  return await db.query("SELECT * FROM products")
}

💡 Tip: Prerendering for a GET handler stops the moment it touches anything non-deterministic — a database call without "use cache", Math.random(), or runtime APIs like cookies() and headers(). If a route you expected to be static is showing up dynamic in your build output, one of these is almost always why.

A Quick Word on the Edge Runtime

By default, Route Handlers run on the Node.js runtime — the full Node environment, with access to everything you'd expect (the fs module, native npm packages, longer execution limits). You can opt a specific route into the lighter-weight Edge Runtime instead:

// app/api/geo/route.ts
export const runtime = "edge"

export async function GET() {
  return Response.json({ message: "Running on the Edge" })
}

The Edge Runtime starts faster and runs closer to the user geographically, but it's a stripped-down environment — no fs, no full Node API surface, and not every npm package supports it. Reach for it for small, latency-sensitive handlers (geolocation checks, lightweight redirects); stick with the Node.js default for anything doing real database work, file access, or using Node-only packages like the Stripe or AWS SDKs.

Step 6: Handling Webhooks (Raw Body Access)

Webhooks — like Stripe payment confirmations — are one of the most common real-world uses for Route Handlers. The key detail: webhook signature verification needs the raw, unparsed request body, not JSON.

// app/api/webhook/route.ts
import { NextResponse } from "next/server"
import { headers } from "next/headers"
import Stripe from "stripe"
import { stripe } from "@/lib/stripe"

const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET!

export async function POST(req: Request) {
  const payload = await req.text() // raw text, NOT req.json()
  const signature = (await headers()).get("stripe-signature")

  if (!signature) {
    return NextResponse.json({ error: "Missing signature" }, { status: 400 })
  }

  let event: Stripe.Event

  try {
    event = stripe.webhooks.constructEvent(payload, signature, endpointSecret)
  } catch (err) {
    const message = err instanceof Error ? err.message : "Unknown error"
    return NextResponse.json({ error: `Webhook Error: ${message}` }, { status: 400 })
  }

  // event is now verified — safe to trust
  return NextResponse.json({ received: true })
}

What's happening here: req.text() reads the body exactly as Stripe sent it. If you call req.json() first, the body gets re-serialized slightly differently, and the cryptographic signature check fails — a classic gotcha that has nothing to do with your actual secret key.

Step 7: Adding CORS Support

If your Route Handler needs to be called from a different domain (a separate frontend, a browser extension, another app), you need to explicitly allow it with CORS headers.

// app/api/public-data/route.ts
export async function GET() {
  return Response.json(
    { data: "available to any origin" },
    {
      headers: {
        "Access-Control-Allow-Origin": "*",
      },
    }
  )
}

export async function OPTIONS() {
  return new Response(null, {
    status: 204,
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
      "Access-Control-Allow-Headers": "Content-Type, Authorization",
    },
  })
}

⚠️ Common Mistake: Setting CORS headers on GET/POST but forgetting OPTIONS. Browsers send a "preflight" OPTIONS request before certain cross-origin requests, and if that preflight doesn't return the right headers, the browser blocks the real request before it's ever sent — even if your GET handler would have worked fine.

If you need CORS applied consistently across many routes at once, handling it in proxy.ts (formerly middleware.ts) instead of repeating this in every file is usually cleaner.

Route Resolution Rules to Know

A few quick rules worth keeping in mind as your API grows:

A route.ts file cannot exist at the same segment as a page.tsx — pick one per route.
Route Handlers do not participate in layouts or client-side navigation the way pages do. They're the lowest-level routing primitive — pure request in, response out.
Each route.ts takes over every HTTP verb for that exact segment. A nested dynamic segment like app/[user]/page.tsx next to app/api/route.ts is perfectly valid, since they're different paths.

Page	Route	Result
`app/page.tsx`	`app/route.ts`	✗ Conflict
`app/page.tsx`	`app/api/route.ts`	✓ Valid
`app/[user]/page.tsx`	`app/api/route.ts`	✓ Valid

Frequently Asked Questions

Can I use Route Handlers with the Pages Router?

No — Route Handlers only work inside the app directory. If your project still uses pages/, you'd build API endpoints with the older pages/api convention instead, which behaves differently (Express-style req/res rather than Web Request/Response).

Do I need Route Handlers if I'm already using Server Actions?

Not necessarily — plenty of apps only use Server Actions for internal mutations. Reach for a Route Handler specifically when something outside your React component tree needs a callable URL: a webhook, a public API, or a request from a non-Next.js client like a mobile app.

Why isn't my GET Route Handler getting cached?

Route Handlers are dynamic by default. You need to explicitly opt in with export const dynamic = "force-static", or — if you're on Cache Components — make sure the handler doesn't touch runtime APIs like cookies(), headers(), or an uncached database call.

Can I return something other than JSON?

Yes. Response and NextResponse can return any body type — plain text, HTML, a file buffer, even a streamed response. Just set the appropriate Content-Type header so the client knows how to interpret it.

How do I protect a Route Handler so only logged-in users can call it?

Check the session inside the handler itself, the same way you would inside a Server Action — never rely on proxy.ts/middleware alone as your only line of defense. Most auth libraries (Clerk, Auth.js) expose a server-side helper you can call at the top of your GET/POST function to verify the request before doing any real work.

💡 If you haven't set up auth yet, see our guides on Clerk or Auth.js (NextAuth) for the full setup.

Wrapping Up

Route Handlers are the App Router's answer to "I need a real, callable HTTP endpoint" — whether that's a public API, a Stripe webhook, or a small internal utility route. The mental model is simple once it clicks: a route.ts file, named exports per HTTP method, and the standard Request/Response APIs doing the actual work. Layer in dynamic segments, caching with "use cache", and CORS headers as your API grows, and you've got everything you need to build a production-ready backend without leaving your Next.js project.

From here, a natural next step is pairing your Route Handlers with Zod validation for safer request parsing, or wiring one up as a real webhook receiver following the Stripe pattern above.

Next.js 16 Routing Explained: A Complete Beginner's Guide (2026)

Wed, 29 Jul 2026 19:00:00 +0000

If you've ever opened a Next.js project and wondered why a folder named (marketing) doesn't show up in the URL, or what on earth @modal means in a file path — you're not alone. Routing is one of the first things you touch in Next.js, and it's also one of the most misunderstood parts of the App Router.

The good news? Once you understand the core idea — folders are routes — everything else is just variations on that one theme.

By the end of this guide, you'll understand every major routing pattern in Next.js 16: static routes, dynamic routes, nested layouts, route groups, parallel routes, intercepting routes, and catch-all segments. We'll build real examples for each one, not just theory.

Pattern	Example	URL
Static	`about/page.tsx`	`/about`
Dynamic	`[slug]/page.tsx`	`/post/hello`
Catch-all	`[...slug]/page.tsx`	`/docs/a/b`
Optional Catch-all	`[[...slug]]/page.tsx`	`/docs` or `/docs/a`
Route Group	`(marketing)/pricing/page.tsx`	`/pricing`
Parallel Route	`@analytics/page.tsx`	Slot
Intercepting Route	`(.)photo/[id]/page.tsx`	Modal

Why Next.js Routing Feels Confusing at First

Unlike React Router or other client-side routers, Next.js doesn't use a config file or a <Routes> component to define your pages. Instead, it uses your file system as the source of truth. The folder structure inside app/ directly maps to the URLs your site responds to.

This is powerful once it clicks, but it also means special folder names (like [slug], (group), or @slot) carry real meaning. Misreading one of these conventions is usually where beginners get stuck.

Let's go through them one at a time.

The Basics: How Folders Become URLs

In the App Router, every route lives inside the app/ directory, and a folder only becomes a visible page when it contains a page.tsx file.

// app/about/page.tsx
export default function AboutPage() {
  return <h1>About Us</h1>;
}

This single file creates the route /about. No router config, no manual registration — Next.js scans the folder tree and wires it up automatically.

💡 Tip: A folder without a page.tsx inside it does not create a route. It might just be there to hold layouts, components, or nested routes.

Special Files You'll See in a Route Folder

File	Purpose
`page.tsx`	Makes the route publicly accessible (the actual UI)
`layout.tsx`	Wraps the page (and its children) with shared UI
`loading.tsx`	Shown automatically while the page is loading
`error.tsx`	Catches errors thrown inside that route segment
`not-found.tsx`	Shown when `notFound()` is called or no route matches

We'll use most of these as we go.

Nested Routes

Want /blog/getting-started to be a real page? Just nest folders:

app/
└── blog/
    ├── page.tsx              → /blog
    └── getting-started/
        └── page.tsx          → /blog/getting-started

// app/blog/getting-started/page.tsx
export default function GettingStartedPage() {
  return <h1>Getting Started With Next.js</h1>;
}

Each folder level adds a segment to the URL path. There's no limit to how deep you can nest — Next.js just keeps following the folders.

Dynamic Routes

Static folders are great until you need a page per blog post, per product, or per user. That's where dynamic routes come in, using square brackets in the folder name.

app/
└── blog/
    └── [slug]/
        └── page.tsx          → /blog/anything-here

// app/blog/[slug]/page.tsx
interface BlogPostPageProps {
  params: Promise<{ slug: string }>;
}

export default async function BlogPostPage({ params }: BlogPostPageProps) {
  const { slug } = await params;

  return <h1>Reading post: {slug}</h1>;
}

Visiting /blog/nextjs-routing-guide renders this page with slug equal to "nextjs-routing-guide".

⚠️ Common Mistake: In Next.js 16, params is a Promise, not a plain object. You must await it before reading values — forgetting this is one of the most common upgrade bugs when migrating from older Next.js versions.

Generating Pages at Build Time

If you know all possible slugs ahead of time (e.g. you're reading blog posts from the file system or a CMS), you can pre-render them at build time with generateStaticParams:

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await getAllPosts();

  return posts.map((post) => ({
    slug: post.slug,
  }));
}

This tells Next.js "here are all the dynamic values that exist — build a static page for each one" instead of rendering them on-demand at request time.

Catch-All and Optional Catch-All Routes

Sometimes one dynamic segment isn't enough. Maybe you want /docs/a, /docs/a/b, and /docs/a/b/c to all hit the same page, with the rest of the path available as an array. That's a catch-all route, written with three dots inside the brackets.

app/
└── docs/
    └── [...slug]/
        └── page.tsx

// app/docs/[...slug]/page.tsx
interface DocsPageProps {
  params: Promise<{ slug: string[] }>;
}

export default async function DocsPage({ params }: DocsPageProps) {
  const { slug } = await params;

  // For /docs/a/b/c, slug = ["a", "b", "c"]
  return <h1>Docs path: {slug.join(" / ")}</h1>;
}

There's also an optional catch-all, which uses double brackets [[...slug]]. The difference: with optional catch-all, /docs itself (with no extra segments) also matches the same page, instead of returning a 404.

app/
└── docs/
    └── [[...slug]]/
        └── page.tsx          → matches /docs, /docs/a, /docs/a/b, etc.

💡 Tip: Catch-all routes are exactly how Clerk's [[...sign-in]] pattern works under the hood — one page handles every sub-step of the auth flow.

Layouts: Shared UI Across Routes

A layout.tsx wraps every page inside its folder (and all nested folders below it) without losing state on navigation — things like a sidebar won't re-render or flicker when you click between pages.

// app/blog/layout.tsx
export default function BlogLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="flex gap-6">
      <aside className="w-48">Blog Sidebar</aside>
      <main className="flex-1">{children}</main>
    </div>
  );
}

Every page under app/blog/ — including [slug]/page.tsx — now renders inside this layout automatically. Layouts nest too: the root app/layout.tsx wraps everything, and a deeper layout wraps just its own subtree.

⚠️ Common Mistake: Layouts don't re-render when you navigate between sibling pages that share them. If you need something to reset per-page (like scroll position or a key-based remount), you'll need to handle that explicitly — layouts are persistent by design.

Route Groups: Organizing Without Affecting the URL

Sometimes you want to organize routes into logical folders — like separating marketing pages from authenticated dashboard pages — without those folder names showing up in the URL. Wrapping a folder name in parentheses does exactly that.

app/
├── (marketing)/
│   ├── layout.tsx        → navbar + footer
│   ├── page.tsx          → /
│   └── pricing/
│       └── page.tsx      → /pricing
│
└── (dashboard)/
    ├── layout.tsx        → sidebar + topbar
    └── settings/
        └── page.tsx      → /settings

Notice that /pricing doesn't become /marketing/pricing — the parentheses tell Next.js "this folder is for organization only, ignore it in the URL." This is exactly how you'd separate a public marketing layout from a private dashboard layout, each with completely different navigation chrome.

💡 Tip: Route groups are also useful for giving the same URL segment multiple layout options during development, or for splitting large apps into logical sections for your team without touching the live URL structure.

Parallel Routes: Rendering Multiple Pages at Once

This is where things get genuinely interesting. Parallel routes let you render two or more independent pages in the same layout, side by side — each with its own loading and error state. You define them with a @ prefix, called a "slot."

Imagine a dashboard that shows an analytics chart and a notifications feed at the same time, but each one loads independently:

app/
└── dashboard/
    ├── layout.tsx
    ├── page.tsx
    ├── @analytics/
    │   └── page.tsx
    └── @notifications/
        └── page.tsx

// app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
  analytics,
  notifications,
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  notifications: React.ReactNode;
}) {
  return (
    <div className="grid grid-cols-2 gap-4">
      <div className="col-span-2">{children}</div>
      <div>{analytics}</div>
      <div>{notifications}</div>
    </div>
  );
}

Each slot (@analytics, @notifications) is passed into the layout as a prop, matching its folder name. Next.js renders them all in parallel — if @notifications is still loading, it won't block @analytics from showing up.

⚠️ Common Mistake: Slot folders need their own page.tsx (or a default.tsx as a fallback) — if a slot has no matching route for the current URL and no default.tsx, Next.js will throw a 404 for the entire layout, not just that slot.

// app/dashboard/@notifications/default.tsx
export default function Default() {
  return null; // fallback when no route matches this slot
}

Intercepting Routes: Modals That Feel Like Pages

Ever clicked a photo on Instagram and seen it open in a modal — but if you refresh that same URL, it loads as a full standalone page instead? That's an intercepting route, and Next.js supports this pattern natively using (.)-style folder prefixes.

app/
├── feed/
│   ├── page.tsx
│   └── @modal/
│       ├── default.tsx
│       └── (.)photo/
│           └── [id]/
│               └── page.tsx     → intercepted modal view
└── photo/
    └── [id]/
        └── page.tsx              → full page (direct visit / refresh)

The convention:

(.) intercepts a route at the same level
(..) intercepts one level above
(..)(..) intercepts two levels above
(...) intercepts from the root

// app/feed/@modal/(.)photo/[id]/page.tsx
export default async function PhotoModal({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;

  return (
    <div className="fixed inset-0 flex items-center justify-center bg-black/50">
      <div className="bg-white p-6 rounded-xl">Photo {id} (modal view)</div>
    </div>
  );
}

So when a user clicks a photo while browsing the feed, Next.js intercepts the navigation and shows the modal. But if they paste that same /photo/123 URL directly into a new tab, Next.js skips the interception and renders the real app/photo/[id]/page.tsx as a normal full page.

💡 Tip: Intercepting routes are almost always paired with parallel routes (the @modal slot) — the slot is what lets the modal render on top of the feed instead of replacing it.

Linking Between Routes

All of this routing is useless without navigation. Always use Next.js's Link component instead of a plain <a> tag — it enables client-side transitions and automatic prefetching.

import Link from "next/link";

export default function Nav() {
  return (
    <nav>
      <Link href="/blog">Blog</Link>
      <Link href="/blog/nextjs-routing-guide">A Specific Post</Link>
    </nav>
  );
}

For programmatic navigation (e.g. redirecting after a form submits), use the useRouter hook in a Client Component:

"use client";

import { useRouter } from "next/navigation";

export default function SubmitButton() {
  const router = useRouter();

  return (
    <button onClick={() => router.push("/dashboard")}>
      Go to Dashboard
    </button>
  );
}

Frequently Asked Questions

Do route groups affect performance?

No. Route groups are purely an organizational tool at build time — they don't add extra network requests, extra DOM nodes, or any runtime cost. They simply change how your files are organized without changing the URL.

Can I combine dynamic routes with route groups?

Yes, and it's common. For example, app/(dashboard)/projects/[id]/page.tsx gives you /projects/123 while keeping the dashboard layout grouping intact.

What's the difference between `loading.tsx` and a parallel route's own loading state?

loading.tsx shows a fallback for an entire route segment while its data loads. Inside parallel routes, each slot (@analytics, @notifications, etc.) can have its own loading.tsx, so one slot can show a spinner while another already displays its content — they load independently.

Why did my page 404 after adding a parallel route slot?

This usually means a slot (like @modal) has no page.tsx matching the current URL and no default.tsx fallback. Add a default.tsx that returns null (or some neutral fallback UI) to fix it.

Can intercepting routes work without parallel routes?

Technically you can intercept into the main children slot, but in practice almost every real-world use case (modals, lightboxes, previews) pairs intercepting routes with a parallel @slot so the intercepted content renders alongside the existing page instead of replacing it.

Wrapping Up

Next.js 16's App Router routing system might look intimidating with all its special folder syntax, but it really boils down to a handful of conventions: brackets for dynamic segments, dots for catch-alls, parentheses for invisible grouping, and @ for parallel slots. Once you've built each pattern once with your own hands, reading someone else's project structure stops feeling like decoding a puzzle.

From here, a natural next step is wiring up authentication-protected routes using these same patterns — check out the Clerk guide below to see route groups and catch-all routes used together in a real auth flow.

Useful Resources

Continue Learning

How to Integrate Sanity CMS with Next.js 16 App Router

Sun, 26 Jul 2026 11:37:52 +0000

Managing content as a developer used to mean one of two things: hardcoding everything into your codebase or wrestling with a clunky WordPress dashboard. Neither feels great when your client wants to update a blog post at 10pm on a Friday without touching a single line of code.

That's exactly where Sanity CMS shines. It's a headless CMS with a fully customizable studio, a powerful query language called GROQ, and first-class support for Next.js. And in 2026, with Next.js 16's App Router fully matured, the two work together beautifully.

In this guide, you'll set up Sanity CMS inside a Next.js 16 App Router project from scratch: creating a project, defining a schema, writing GROQ queries, typing everything with TypeScript, and rendering rich text content with live updates. By the end, you'll have a working blog listing page and a dynamic post page, both powered entirely by Sanity.

Why Sanity Over Other Headless CMS Options?

There are plenty of headless CMS choices out there — Contentful, Strapi, Payload — so why Sanity?

Sanity Studio runs inside your Next.js app at /studio, so there's no separate admin URL to manage.
GROQ (Graph-Relational Object Queries) is more flexible and readable than GraphQL for content queries.
Real-time collaboration — multiple editors can work on content simultaneously.
Free tier is genuinely generous for most personal projects and small clients.

What We're Building

An embedded Sanity Studio running at /studio inside your Next.js app
A post schema with title, slug, excerpt, cover image, and rich text body
GROQ queries to fetch all posts and a single post by slug
Fully typed Sanity responses with TypeScript
A blog listing page and a dynamic post page using generateStaticParams
Real-time content updates using Sanity Live

What Is Sanity, Exactly?

Sanity is a headless CMS — meaning the content editor (Studio) is completely decoupled from how your content gets displayed. You configure Studio with code, content gets stored remotely in what Sanity calls the Content Lake, and your Next.js app queries that content using GROQ (Sanity's own query language).

💡 Tip: Think of Sanity Studio as a "window" into your remote content. The Studio configuration lives in your repo, but the actual blog posts, images, and data live on Sanity's servers — not in your codebase.

Prerequisites

Before we start, make sure you have:

Node.js 20+ installed
A Next.js 16 project with the App Router (TypeScript + Tailwind)
A free account at sanity.io
Basic familiarity with Next.js file-based routing

Step 1: Create a Sanity Project

First, let's create a new Sanity project from the CLI. If you don't have the Sanity CLI installed yet, run:

npm install -g @sanity/cli

Then inside your Next.js project root, initialize Sanity:

npx sanity@latest init

The CLI will walk you through a series of prompts. Here's exactly what to choose:

✔ Create a new project or select an existing one → Create new project
✔ Project name → whatever you like (e.g. my-blog)
✔ Select organization or create new
✔ Use the default dataset configuration? → Yes
✔ Configure Sanity MCP and agent skills for these editors? → Claude Code, GitHub Copilot CLI, VS Code
✔ Would you like to add configuration files for a Sanity project in this Next.js folder? → Yes
✔ Do you want to use TypeScript? → Yes
✔ Would you like an embedded Sanity Studio? → Yes
✔ What route do you want to use for the Studio? → /studio
✔ Select project template to use → Clean project with no predefined schema types
✔ Would you like to add the project ID and dataset to your .env.local file? → Yes

⚠️ Common Mistake: Picking the "blog" template instead of "Clean project" gives you pre-built schema types (post, author, category). That's fine if you want a head start, but this guide builds the post schema manually so you understand exactly what each field does — so we go with the clean template.

Once it finishes, your project folder should look like this:

.
├── .env.local
├── sanity.cli.ts
├── sanity.config.ts
├── (...and all your Next.js files)
└── src
    ├── app
    │   └── studio
    │       └── [[...tool]]
    │           └── page.tsx
    └── sanity
        ├── lib
        │   ├── client.ts
        │   ├── image.ts
        │   └── live.ts
        ├── schemaTypes
        │   └── index.ts
        ├── env.ts
        └── schema.ts

What Just Got Created?

A few of these files matter more than others:

src/sanity/lib/client.ts — a configured Sanity Client instance used to query content
src/sanity/lib/live.ts — exports sanityFetch and SanityLive, which power real-time content updates
src/sanity/env.ts — reads your project ID and dataset from .env.local
sanity.config.ts — configures Studio itself: schema types, plugins, and the studio route
app/studio/[[...tool]]/page.tsx — the catch-all route that renders the entire Studio UI at /studio

Your .env.local should now contain:

NEXT_PUBLIC_SANITY_PROJECT_ID="your-project-id"
NEXT_PUBLIC_SANITY_DATASET="production"

These are prefixed with NEXT_PUBLIC_ because a project ID and dataset name aren't sensitive — they're needed by the browser to talk to Sanity's API directly when previewing content.

Step 2: Install next-sanity

The CLI usually installs this for you, but if it's missing, add it manually:

npm install next-sanity

next-sanity is a toolkit of utilities built specifically for Next.js — it wraps Sanity Client with conventions for data fetching, caching, and live content updates so you're not wiring all of that together yourself.

Step 3: Create a Post Schema

Schemas in Sanity define what content editors are allowed to create in Studio — think of them as the shape of your content, similar to a database model.

Create a new schema file:

// src/sanity/schemaTypes/post.ts
import { defineField, defineType } from "sanity";

export const postSchema = defineType({
  name: "post",
  title: "Blog Post",
  type: "document",
  fields: [
    defineField({
      name: "title",
      title: "Title",
      type: "string",
      validation: (Rule) => Rule.required(),
    }),
    defineField({
      name: "slug",
      title: "Slug",
      type: "slug",
      options: { source: "title" }, // auto-generates slug from title
      validation: (Rule) => Rule.required(),
    }),
    defineField({
      name: "excerpt",
      title: "Excerpt",
      type: "text",
      rows: 3,
    }),
    defineField({
      name: "coverImage",
      title: "Cover Image",
      type: "image",
      options: { hotspot: true }, // lets editors set a focal point
    }),
    defineField({
      name: "publishedAt",
      title: "Published At",
      type: "datetime",
    }),
    defineField({
      name: "body",
      title: "Body",
      type: "array",
      of: [{ type: "block" }, { type: "image" }], // rich text + inline images
    }),
  ],
  orderings: [
    {
      title: "Published Date, New",
      name: "publishedAtDesc",
      by: [{ field: "publishedAt", direction: "desc" }],
    },
  ],
});

A quick breakdown of what's happening:

defineType registers a new document type — editors will see "Blog Post" as a creatable content type in Studio
defineField describes each individual field and its validation rules
The slug field with options: { source: "title" } auto-generates a URL-friendly slug from the title as the editor types
body uses type: "array" with block and image — this is Sanity's Portable Text format, a structured way of representing rich text that isn't tied to HTML

💡 Tip: Rule.required() enforces validation inside Studio itself. Editors literally cannot publish a post without a title or slug — no backend validation needed.

Step 4: Register the Schema

Defining a schema isn't enough — Studio needs to know it exists. Register it in the schema index:

// src/sanity/schemaTypes/index.ts
import { type SchemaTypeDefinition } from "sanity";
import { postSchema } from "./post";

export const schema: { types: SchemaTypeDefinition[] } = {
  types: [postSchema],
};

⚠️ Common Mistake: Forgetting this step is the #1 reason a new schema "doesn't show up" in Studio. Defining the type isn't enough — it has to be added to this types array.

Now start your dev server and visit http://localhost:3000/studio. You should see "Blog Post" listed as a content type, ready to create your first post.

Step 5: Write GROQ Queries

GROQ (Graph-Relational Object Queries) is Sanity's query language, purpose-built for querying structured, nested JSON-like content.

💡 Tip: If you've used SQL or MongoDB queries before, GROQ will feel different at first, but it's actually closer to JavaScript object/array syntax than SQL.

Create a queries file:

// src/sanity/queries.ts
import { groq } from "next-sanity";

// Fetch all posts for the blog listing page
export const allPostsQuery = groq`
  *[_type == "post"] | order(publishedAt desc) {
    _id,
    title,
    slug,
    excerpt,
    publishedAt,
    coverImage {
      asset-> { _id, url }
    }
  }
`;

// Fetch a single post by slug
export const postBySlugQuery = groq`
  *[_type == "post" && slug.current == $slug][0] {
    _id,
    title,
    slug,
    excerpt,
    publishedAt,
    coverImage {
      asset-> { _id, url }
    },
    body
  }
`;

// Fetch all slugs for generateStaticParams
export const allPostSlugsQuery = groq`
  *[_type == "post"] { "slug": slug.current }
`;

Here's what each part of the first query means:

*[_type == "post"] — selects every document where the type equals "post"
| order(publishedAt desc) — sorts results by publish date, newest first
{ ... } — a projection, meaning "only return these fields," similar to selecting specific columns in SQL
coverImage { asset-> { _id, url } } — the -> is a dereference, following the image asset reference to pull its actual URL

The second query uses $slug as a parameter and [0] to grab just the first matching result, since slugs are unique.

Step 6: Add TypeScript Types

Since GROQ queries return plain JSON, TypeScript has no way to infer their shape automatically. Define the types yourself so the rest of your app stays type-safe:

// src/sanity/types.ts
export interface SanitySlug {
  current: string;
}

export interface SanityImageAsset {
  _id: string;
  url: string;
}

export interface SanityImage {
  asset: SanityImageAsset;
}

export interface Post {
  _id: string;
  title: string;
  slug: SanitySlug;
  excerpt?: string;
  publishedAt: string;
  coverImage?: SanityImage;
  body?: unknown[]; // Portable Text blocks
}

💡 Tip: Sanity also offers a code generation tool (sanity typegen) that can generate these types automatically from your schema and queries. Writing them by hand works fine for smaller schemas, but it's worth exploring once your content model grows.

Step 7: Build the Blog Listing Page

With queries and types ready, fetching content becomes straightforward:

// app/blog/page.tsx
import { sanityFetch } from "@/sanity/lib/live";
import { allPostsQuery } from "@/sanity/queries";
import { Post } from "@/sanity/types";
import Link from "next/link";

export default async function BlogPage() {
  const { data: posts } = await sanityFetch({ query: allPostsQuery });

  return (
    <main className="max-w-3xl mx-auto px-4 py-12">
      <h1 className="text-4xl font-bold mb-8">Blog</h1>
      <ul className="space-y-8">
        {(posts as Post[]).map((post) => (
          <li key={post._id} className="border-b pb-8">
            <Link href={`/blog/${post.slug.current}`}>
              <h2 className="text-2xl font-semibold hover:underline">
                {post.title}
              </h2>
            </Link>
            {post.excerpt && (
              <p className="mt-2 text-gray-600">{post.excerpt}</p>
            )}
            {post.publishedAt && (
              <time className="text-sm text-gray-400">
                {new Date(post.publishedAt).toLocaleDateString("en-US", {
                  year: "numeric",
                  month: "long",
                  day: "numeric",
                })}
              </time>
            )}
          </li>
        ))}
      </ul>
    </main>
  );
}

Notice we're using sanityFetch from @/sanity/lib/live instead of calling the Sanity client directly. That's intentional — sanityFetch is a wrapper that ties into Next.js's caching and revalidation system, and it's also what enables the live-update behavior in the next step.

Step 8: Enable Sanity Live in the Root Layout

SanityLive is a component that subscribes to Sanity's Live Content API, so changes you publish in Studio show up on your site without a manual rebuild or redeploy.

// app/layout.tsx
import { SanityLive } from "@/sanity/lib/live";

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html
      lang="en"
      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
    >
      <body className="min-h-full flex flex-col">
        {children}
        <SanityLive />
      </body>
    </html>
  );
}

SanityLive doesn't render any visible UI — it just sits in the background and triggers revalidation whenever content changes in the Content Lake.

⚠️ Common Mistake: Placing SanityLive only on specific pages instead of the root layout. Since it needs to listen for changes globally, the root layout is the correct place for it.

Step 9: Style Rich Text with Tailwind Typography

Portable Text renders as plain HTML elements with no default styling, so headings, paragraphs, and lists will look unstyled out of the box. The Tailwind Typography plugin fixes this in one line.

Install it:

npm install @tailwindcss/typography

Add the plugin to your global CSS:

/* app/globals.css */
@import "tailwindcss";

@plugin "@tailwindcss/typography";

You'll use the prose class on any container wrapping Portable Text content in the next step.

Step 10: Build the Dynamic Post Page

This is where everything comes together — fetching a single post by slug, pre-rendering it at build time, and rendering its rich text body with PortableText.

// app/blog/[slug]/page.tsx
import { sanityFetch } from "@/sanity/lib/live";
import { allPostSlugsQuery, postBySlugQuery } from "@/sanity/queries";
import { Post } from "@/sanity/types";
import { PortableText } from "next-sanity";
import Image from "next/image";
import { notFound } from "next/navigation";

// Tell Next.js which slugs to pre-render at build time
export async function generateStaticParams() {
  const { data: slugs } = await sanityFetch({ query: allPostSlugsQuery });
  return (slugs as { slug: string }[]).map(({ slug }) => ({ slug }));
}

interface PageProps {
  params: Promise<{ slug: string }>;
}

export default async function PostPage({ params }: PageProps) {
  const { slug } = await params;
  const { data } = await sanityFetch({ query: postBySlugQuery, params: { slug } });

  if (!data) notFound(); // renders your app/not-found.tsx

  const post = data as Post;

  return (
    <article className="max-w-3xl mx-auto px-4 py-12">
      <h1 className="text-4xl font-bold mb-4">{post.title}</h1>

      {post.publishedAt && (
        <time className="text-sm text-gray-400 block mb-8">
          {new Date(post.publishedAt).toLocaleDateString("en-US", {
            year: "numeric",
            month: "long",
            day: "numeric",
          })}
        </time>
      )}

      {post.coverImage?.asset?.url && (
        <div className="relative mb-8 rounded-xl overflow-hidden">
          <Image
            src={post.coverImage.asset.url}
            alt={post.title}
            className="rounded-xl"
            priority
            width={1200}
            height={630}
          />
        </div>
      )}

      {Array.isArray(post.body) && (
        <div className="prose prose-lg max-w-none">
          <PortableText value={post.body} />
        </div>
      )}
    </article>
  );
}

A couple of things worth calling out:

generateStaticParams runs at build time and tells Next.js exactly which /blog/[slug] pages to statically generate, rather than rendering every post on demand
params is passed as a Promise — this matches Next.js 16's async params convention, which is why postBySlugQuery accepts it directly inside sanityFetch
notFound() triggers your custom not-found.tsx page if no post matches the slug, instead of crashing with an unhandled error

⚠️ Common Mistake: Forgetting Array.isArray(post.body) before rendering PortableText. If body is ever undefined (e.g. an editor saved a post without adding body content), PortableText will throw instead of failing gracefully.

Frequently Asked Questions

Why GROQ instead of a REST or GraphQL API?

GROQ is built specifically for querying deeply nested, structured content in a single request — including resolving references like images — without the boilerplate of a separate GraphQL schema or multiple REST calls.

Do I need to deploy Sanity Studio separately?

No. Since Studio is embedded inside your Next.js app at /studio, it deploys automatically whenever your Next.js app deploys — no separate hosting or build step required.

How do I render images from Sanity with Next.js Image optimization?

Use @sanity/image-url to build the image URL, then pass it to Next.js <Image>. Add cdn.sanity.io to the images.remotePatterns array in next.config.ts so Next.js is allowed to optimize it:

// next.config.ts
images: {
  remotePatterns: [{ protocol: "https", hostname: "cdn.sanity.io" }],
}

Is SanityLive safe to use in production?

Yes. It's designed for production use and is the recommended way to get real-time content updates without manually managing webhooks or polling.

Is the Sanity Studio accessible to the public?

By default, yes — anyone who visits /studio can see it (though they can't edit without a Sanity account with the right permissions). To fully restrict it, wrap the studio route in a middleware auth check or only run it in dev using an environment variable guard.

How is this different from my current MDX-based blog?

With MDX, content lives as files in your repo — every edit means a commit and redeploy. With Sanity, content lives in the cloud and can be edited through a UI, published instantly, and even handed off to non-technical writers without giving them repo access.

Can I add more content types later, like authors or categories?

Yes. Create a new schema file the same way you created post.ts, then register it in the types array inside schemaTypes/index.ts. Studio will pick it up immediately.

Conclusion

You now have a fully working Sanity CMS integration inside a Next.js 16 application — complete with an embedded Studio, a typed content model, GROQ-powered queries, and live content updates. From here, you can expand your schema with authors, categories, or custom block content, add Visual Editing for inline previews, or wire up on-demand revalidation through Sanity's webhooks.

This setup scales well beyond a simple blog — the same pattern works for landing pages, product catalogs, or any structured content your app needs to manage outside the codebase.

Useful Resources

Continue Learning

If you'd like to keep building on this foundation, check out these related guides:

📦 Source Code: View on GitHub

Coder Legion - Recent posts tagged app-router

Error Handling in Next.js 16: The Complete 2026 Guide

Why This Is Tricky

Step 1: Catch Rendering Errors with error.tsx

Scoping Errors to the Right Level

Step 2: Handle Root Layout Errors with global-error.tsx

Step 3: Handle "Not Found" Cases

not-found.tsx for a Specific Segment

global-not-found.tsx for Unmatched URLs (New in Next.js 16)

Step 4: Handle Errors in Server Actions

Step 5: Handle Errors in Route Handlers (API Routes)

Frequently Asked Questions

Does error.tsx catch errors in event handlers, like an onClick?

Can error.tsx be a Server Component?

What's the actual difference between error.tsx and not-found.tsx?

Do I need global-error.tsx if I already have error.tsx everywhere?

Should I use Sentry or a similar tool instead of just console.error?

Wrapping Up

Continue Learning

Route Handlers Explained in Next.js 16 (Beginner's Guide)

What Are Route Handlers, Exactly?

Why This Is Tricky (For Beginners)

Route Handlers vs. Pages Router API Routes

Route Handlers vs. Server Actions

Prerequisites

Step 1: The route.ts File Convention

Step 2: Supported HTTP Methods

Response vs. NextResponse, Request vs. NextRequest

Step 3: Reading Data From the Request

Step 4: Dynamic Route Segments

Step 5: Caching Behavior

If You're Using Cache Components ("use cache")

A Quick Word on the Edge Runtime

Step 6: Handling Webhooks (Raw Body Access)

Step 7: Adding CORS Support

Route Resolution Rules to Know

Frequently Asked Questions

Can I use Route Handlers with the Pages Router?

Do I need Route Handlers if I'm already using Server Actions?

Why isn't my GET Route Handler getting cached?

Can I return something other than JSON?

How do I protect a Route Handler so only logged-in users can call it?

Wrapping Up

Next.js 16 Routing Explained: A Complete Beginner's Guide (2026)

Why Next.js Routing Feels Confusing at First

The Basics: How Folders Become URLs

Special Files You'll See in a Route Folder

Nested Routes

Dynamic Routes

Generating Pages at Build Time

Catch-All and Optional Catch-All Routes

Layouts: Shared UI Across Routes

Route Groups: Organizing Without Affecting the URL

Parallel Routes: Rendering Multiple Pages at Once

Intercepting Routes: Modals That Feel Like Pages

Linking Between Routes

Frequently Asked Questions

Do route groups affect performance?

Can I combine dynamic routes with route groups?

What's the difference between loading.tsx and a parallel route's own loading state?

Why did my page 404 after adding a parallel route slot?

Can intercepting routes work without parallel routes?

Wrapping Up

Useful Resources

Continue Learning

How to Integrate Sanity CMS with Next.js 16 App Router

Why Sanity Over Other Headless CMS Options?

What We're Building

What Is Sanity, Exactly?

Prerequisites

Basic familiarity with Next.js file-based routing

Step 1: Create a Sanity Project

What Just Got Created?

Step 2: Install next-sanity

Step 3: Create a Post Schema

Step 4: Register the Schema

Step 5: Write GROQ Queries

Step 6: Add TypeScript Types

Step 7: Build the Blog Listing Page

Step 8: Enable Sanity Live in the Root Layout

Step 1: Catch Rendering Errors with `error.tsx`

Step 2: Handle Root Layout Errors with `global-error.tsx`

`not-found.tsx` for a Specific Segment

`global-not-found.tsx` for Unmatched URLs (New in Next.js 16)

Does `error.tsx` catch errors in event handlers, like an `onClick`?

Can `error.tsx` be a Server Component?

What's the actual difference between `error.tsx` and `not-found.tsx`?

Do I need `global-error.tsx` if I already have `error.tsx` everywhere?

Should I use Sentry or a similar tool instead of just `console.error`?

Step 1: The `route.ts` File Convention

If You're Using Cache Components (`"use cache"`)

What's the difference between `loading.tsx` and a parallel route's own loading state?