DEV Community: Syed Muhammad Ali

Complete MDX Blog Setup with next-mdx-remote and Next.js 16 (2026 Beginner Guide)

Syed Muhammad Ali — Tue, 07 Jul 2026 09:44:01 +0000

If you've ever tried writing blog posts in plain Markdown inside a Next.js app, you've probably hit a wall pretty fast. Plain Markdown can't render React components, can't handle custom styled code blocks, and definitely can't drop in an interactive widget in the middle of a paragraph.

That's exactly the gap MDX fills — and next-mdx-remote is the easiest way to load MDX content that lives outside your app folder (like a content/blogs directory) and render it as real React.

In this guide, you'll build a complete, production-ready blog setup using next-mdx-remote in Next.js 16 — the same setup powering this very blog. By the end, you'll have:

MDX files stored in a content/blogs folder
A reusable getAllPosts() / getPostBySlug() data layer
Custom-styled MDX components (headings, code blocks, links, tables)
Syntax highlighting with sugar-high
remark-gfm for GitHub-flavored Markdown (tables, strikethrough, task lists)
Dynamic SEO metadata and JSON-LD structured data per post

Why MDXRemote Instead of @next/mdx?

Next.js offers two different ways to work with MDX, and beginners often mix them up.

@next/mdx treats .mdx files as actual pages/routes. You'd create a file like app/blog/my-post/page.mdx and Next.js compiles it into a route at build time. This works, but it means every blog post is a route file living inside app/ — awkward if you want a content/ folder, dynamic [slug] routes, or to pull posts from a CMS/database later.

next-mdx-remote lets you store MDX content anywhere — a content/blogs folder, a database, a CMS — and render it through a single dynamic route like app/blog/[slug]/page.tsx. You read the raw MDX string yourself (usually with the filesystem), then hand it to the <MDXRemote /> component to compile and render.

💡 Tip: If you want a handful of static pages (like a docs page), @next/mdx is simpler. If you're building a blog with many posts and dynamic routing, next-mdx-remote is the better fit — it's what we'll use here.

What We're Building

content/
  blogs/
    hello-world.mdx
    another-post.mdx

lib/
  posts.ts        → reads MDX files, parses frontmatter, sorts posts

app/
  blog/
    [slug]/
      page.tsx              → dynamic route rendering MDXRemote
      opengraph-image.tsx    → auto-generated OG image per post

mdx-components.tsx  → custom styled components used inside MDX

Prerequisites: Next.js 16 (App Router), TypeScript in strict mode, and Tailwind CSS for styling. If your project doesn't already have these, scaffold one with npx create-next-app@latest.

Step 1: Install Dependencies

Run the following command to install everything this setup needs:

npm install next-mdx-remote gray-matter remark-gfm reading-time sugar-high

Here's what each package actually does:

Package	Purpose
`next-mdx-remote`	Compiles and renders MDX strings as React on the server
`gray-matter`	Parses frontmatter (the `---` block at the top of your `.mdx` files)
`remark-gfm`	Adds GitHub-flavored Markdown — tables, strikethrough, task lists
`reading-time`	Calculates estimated reading time from post content
`sugar-high`	Lightweight syntax highlighter for code blocks (no client JS needed)

⚠️ Common Mistake: Don't confuse next-mdx-remote with next-mdx-remote/rsc. The base package is for the Pages Router / client components. For the App Router with Server Components (which is what we want in Next.js 16), you import from next-mdx-remote/rsc instead. We'll use that import throughout this guide.

Step 2: Configure next.config.mjs (Optional)

// next.config.mjs

/** @type {import('next').NextConfig} */
const nextConfig = {
    pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
    transpilePackages: ['next-mdx-remote'],
}

export default nextConfig

What's happening here:

pageExtensions tells Next.js that .md and .mdx files can also be treated as pages, alongside the usual .ts/.tsx.
transpilePackages: ['next-mdx-remote'] makes sure Next.js properly transpiles the package rather than trying to treat it as pre-built.

Step 3: Create the Content Folder

This is where your actual blog posts will live as plain .mdx files.

content/blogs/hello-world.mdx

---
title: "Hello World: My First MDX Post"
description: "A short example post to test out the MDXRemote setup in Next.js 16."
publishedAt: "2026-07-01"
tags: ["MDX", "Next.js"]
featured: false
---

## Hello World

This is my **first** MDX post rendered with `next-mdx-remote`.

- It supports Markdown
- It supports *React components*
- It even supports tables (thanks to remark-gfm)

| Feature            | Supported |
| ------------------ | --------- |
| Tables             | ✅       |
| Code blocks        | ✅       |
| Custom components  | ✅       |

const greeting: string = "Hello from MDX!";
console.log(greeting);

Understanding the frontmatter block:

The section between the --- lines at the top is called frontmatter. It's plain YAML metadata that describes the post — title, description, publish date, tags — without being part of the rendered content itself. gray-matter (installed earlier) is the library that separates this metadata from the actual MDX body.

⚠️ Common Mistake: Keep your frontmatter field names consistent across every post (title, description, publishedAt, tags, featured). If one file has date and another has publishedAt, your sorting and metadata logic will silently break for that post.

Step 4: Build the Data Layer (lib/posts.ts)

This file is the heart of the whole setup — it reads every .mdx file from disk, parses the frontmatter, and returns clean, typed post objects your pages can use.

// lib/posts.ts
import fs from "fs";
import path from "path";
import matter from "gray-matter";
import readingTime from "reading-time";

const POSTS_PATH = path.join(process.cwd(), "content/blogs");

export type Post = {
  slug: string;
  title: string;
  description: string;
  publishedAt: string;
  updatedAt?: string;
  tags: string[];
  coverImage?: string;
  readingTime: string;
  content: string;
};

export function getAllPosts(): Post[] {
  const files = fs.readdirSync(POSTS_PATH);

  const posts = files.map((file) => {
    const filePath = path.join(POSTS_PATH, file);
    const fileContent = fs.readFileSync(filePath, "utf-8");

    const { data, content } = matter(fileContent);

    const slug = file.replace(/\.mdx$/, "");

    return {
      slug,
      title: data.title,
      description: data.description,
      publishedAt: data.publishedAt,
      tags: data.tags || [],
      coverImage: data.coverImage || "",
      readingTime: readingTime(content).text,
      content,
    };
  });

  return posts.sort(
    (a, b) =>
      new Date(b.publishedAt).getTime() -
      new Date(a.publishedAt).getTime()
  );
}

export function getPostBySlug(slug: string) {
  return getAllPosts().find((post) => post.slug === slug);
}

export function extractFirstImage(content: string) {
  const regex = /!\[.*?\]\((.*?)\)/;
  const match = content.match(regex);
  return match?.[1] || null;
}

Breaking this down line by line:

fs.readdirSync(POSTS_PATH) reads the filenames of every .mdx file inside content/blogs.
matter(fileContent) splits each file into data (the frontmatter object) and content (the raw MDX body below the frontmatter).
slug is derived directly from the filename — hello-world.mdx becomes the slug hello-world, which later becomes the URL /blog/hello-world.
readingTime(content).text automatically calculates something like "3 min read" based on word count — no manual math needed.
Posts are sorted newest-first by comparing publishedAt dates.
extractFirstImage() is a small helper that scans the Markdown content for the first ![alt](url) image — handy for auto-generating Open Graph preview images later.

💡 Tip: Because this uses fs (Node's filesystem module), it can only run on the server — inside Server Components, generateStaticParams, or generateMetadata. Never import lib/posts.ts into a "use client" component.

Step 5: Create Custom MDX Components

By default, MDX renders plain, unstyled HTML tags (<h1>, <p>, <code>, etc). To make your blog actually look good, you override these tags with your own styled versions.

// mdx-components.tsx
import React, { ComponentPropsWithoutRef } from 'react';
import Link from 'next/link';
import { highlight } from 'sugar-high';

type HeadingProps = ComponentPropsWithoutRef<'h1'>;
type ParagraphProps = ComponentPropsWithoutRef<'p'>;
type ListProps = ComponentPropsWithoutRef<'ul'>;
type ListItemProps = ComponentPropsWithoutRef<'li'>;
type AnchorProps = ComponentPropsWithoutRef<'a'>;
type BlockquoteProps = ComponentPropsWithoutRef<'blockquote'>;

const components = {
    h1: (props: HeadingProps) => (
        <h1 className="scroll-m-20 text-4xl font-bold tracking-tight lg:text-5xl" {...props} />
    ),
    h2: (props: HeadingProps) => (
        <h2 className="scroll-m-20 mt-16 pb-2 text-3xl font-semibold tracking-tight" {...props} />
    ),
    h3: (props: HeadingProps) => (
        <h3 className="scroll-m-20 mt-12 text-2xl font-semibold tracking-tight" {...props} />
    ),
    p: (props: ParagraphProps) => (
        <p className="text-gray-800 dark:text-zinc-300" {...props} />
    ),
    ul: (props: ListProps) => (
        <ul className="text-gray-800 dark:text-zinc-300 list-disc pl-5 space-y-1" {...props} />
    ),
    li: (props: ListItemProps) => <li className="pl-1" {...props} />,
    a: ({ href, children, ...props }: AnchorProps) => {
        const className = 'text-blue-500 hover:text-blue-700';

        // Internal links use Next.js's Link for client-side navigation
        if (href?.startsWith('/')) {
            return <Link href={href} className={className} {...props}>{children}</Link>;
        }

        // External links open in a new tab
        return (
            <a href={href} target="_blank" rel="noopener noreferrer" className={className} {...props}>
                {children}
            </a>
        );
    },
    code: ({ children, ...props }: ComponentPropsWithoutRef<'code'>) => {
        const codeHTML = highlight(String(children));
        return <code dangerouslySetInnerHTML={{ __html: codeHTML }} {...props} />;
    },
    blockquote: (props: BlockquoteProps) => (
        <blockquote className="ml-[0.075em] border-l-3 border-green-400 pl-4 text-gray-700" {...props} />
    ),
    em: (props: ComponentPropsWithoutRef<'em'>) => (
        <em className="font-medium" {...props} />
    ),
};

declare global {
    type MDXProvidedComponents = typeof components;
}

export { components };
export function useMDXComponents(): MDXProvidedComponents {
    return components;
}

What's happening here:

Every key in the components object (h1, p, code, etc.) maps directly to that HTML tag name inside your MDX files. Write # My Heading in MDX, and it renders through your custom h1 component automatically.
The code component is the interesting one — instead of plain unstyled text, it runs the code through sugar-high's highlight() function, which returns syntax-highlighted HTML. This gives you colored code blocks with zero client-side JavaScript, since sugar-high runs entirely at render time on the server.
The a component checks whether a link is internal (starts with /) or external. Internal links use Next.js's <Link> for fast client-side navigation; external links get target="_blank" so readers don't lose your site.

⚠️ Common Mistake: Forgetting to style the code component is the #1 reason MDX blogs look broken — code blocks renders with no formatting. Always wire up a syntax highlighter here.

Step 6: Build the Dynamic Blog Route

This is where everything comes together — reading the post, compiling the MDX, and rendering it.

// app/blog/[slug]/page.tsx
import { notFound } from "next/navigation";
import { MDXRemote } from "next-mdx-remote/rsc";
import remarkGfm from "remark-gfm";
import { getAllPosts, getPostBySlug } from "@/lib/posts";
import { components } from "@/mdx-components";

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

// Pre-renders every post at build time (Static Site Generation)
export async function generateStaticParams() {
    const posts = getAllPosts();
    return posts.map((post) => ({ slug: post.slug }));
}

export async function generateMetadata({ params }: BlogPostPageProps) {
    const { slug } = await params;
    const post = getPostBySlug(slug);

    if (!post) return {};

    return {
        title: post.title,
        description: post.description,
    };
}

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

    if (!post) {
        notFound();
    }

    return (
        <article className="prose dark:prose-invert mx-auto">
            <h1>{post.title}</h1>

            <MDXRemote
                source={post.content}
                components={components}
                options={{
                    mdxOptions: {
                        remarkPlugins: [remarkGfm],
                    },
                }}
            />
        </article>
    );
}

Understanding each piece:

generateStaticParams() tells Next.js every possible slug value ahead of time, so it can statically generate every blog post page at build time instead of rendering it on every request. This is what makes MDX blogs built this way extremely fast.
generateMetadata() dynamically sets the <title> and meta description per post — critical for SEO, since every post needs its own unique tags rather than a single site-wide default.
notFound() triggers Next.js's built-in 404 page if someone visits a slug that doesn't exist in content/blogs.
<MDXRemote source={...} /> is doing the real work: it takes the raw MDX string (post.content), compiles it into React on the server, and renders it — swapping in your custom components along the way.
remarkPlugins: [remarkGfm] enables GitHub-flavored Markdown syntax inside this specific render call — tables, ~~strikethrough~~, and - [ ] task lists all now work in your MDX files.

💡 Tip: MDXRemote from next-mdx-remote/rsc is an async Server Component. It streams and renders entirely on the server — no MDX compiler code ever ships to the browser, which keeps your client bundle small.

Step 7: Add JSON-LD Structured Data (Optional, but Great for SEO)

To help Google understand each post is a blog article (and potentially show rich snippets), add structured data using Next.js's <Script> component.

// app/blog/[slug]/page.tsx (addition)
import Script from "next/script";

<>
<article>
rest of the code
</article>
<Script
    type="application/ld+json"
    dangerouslySetInnerHTML={{
        __html: JSON.stringify({
            "@context": "https://schema.org",
            "@type": "BlogPosting",
            headline: post.title,
            description: post.description,
            datePublished: post.publishedAt,
            author: { "@type": "Person", name: "Your Name" },
        }),
    }}
/>
</>

This injects a <script type="application/ld+json"> tag containing structured metadata search engines can parse directly — no visible UI change, just better SEO.

Step 8: Update `global.css`

Blog content 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";

:root{
  /* your other styles */

  /* add code blocks styling */
  --sh-class: #7aa2f7;
  --sh-sign: #89ddff;
  --sh-string: #9ece6a;
  --sh-keyword: #bb9af7;
  --sh-comment: #acacac;
  --sh-jsxliterals: #7aa2f7;
  --sh-property: #73daca;
  --sh-entity: #e0af68;
  --sh-identifier: #fff;
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }

  body {
    @apply bg-background text-foreground;
  }

  button:not(:disabled),
  [role="button"]:not(:disabled) {
    cursor: pointer;
  }

  pre::-webkit-scrollbar {
    display: none;
  }

  code:not(pre code) {
    background-color: var(--color-gray-100);
  }

  code:not(pre code) span {
    font-weight: 600;
    color: black !important;
  }

  hr {
    color: var(--color-gray-200);
  }

  /* Remove Safari input shadow on mobile */
  input[type='text'],
  input[type='email'] {
    -webkit-appearance: none;
    -moz-appearance: none;
    appearance: none;
  }

  table {
    display: block;
    max-width: fit-content;
    overflow-x: auto;
    white-space: nowrap;
    text-align: left;
  }
}

Testing Your Setup

Start your dev server:

npm run dev

Then visit:

http://localhost:3000/blog/hello-world

You should see your MDX post fully rendered with styled headings, a working table, and a syntax-highlighted code block.

⚠️ Common Mistake: If you get a "module not found: fs" error, you've likely imported lib/posts.ts inside a Client Component ("use client"). The fs module only works on the server — remove the client directive or move the data fetching to a Server Component / route handler.

Bonus: Dynamic Open Graph Images

// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og';

export const runtime = 'edge'; // Use Edge Runtime for faster generation
export const alt = 'Blog Post Preview';
export const size = { width: 1200, height: 630 };
export const contentType = 'image/png';

export default async function Image({ params }: { params: Promise<{ slug: string; }> }) {
    const title = (await params).slug.replace(/-/g, ' ');

    return new ImageResponse(
        (
            <div
                style={{
                    height: "100%",
                    width: "100%",
                    display: "flex",
                    flexDirection: "column",
                    justifyContent: "space-between",
                    backgroundColor: "#fff",
                    padding: "60px",
                }}
            >

                <div
                    style={{
                        fontSize: 44,
                        display: 'flex',
                        alignItems: 'center',
                        fontWeight: 'bold',
                        gap: '15px'
                    }}
                >
                    <svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 24 24" fill="none" stroke="green" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12.83 2.18a2 2 0 0 0-1.66 0L2.6 6.08a1 1 0 0 0 0 1.83l8.58 3.91a2 2 0 0 0 1.66 0l8.58-3.9a1 1 0 0 0 0-1.83z" /><path d="M2 12a1 1 0 0 0 .58.91l8.6 3.91a2 2 0 0 0 1.65 0l8.58-3.9A1 1 0 0 0 22 12" /><path d="M2 17a1 1 0 0 0 .58.91l8.6 3.91a2 2 0 0 0 1.65 0l8.58-3.9A1 1 0 0 0 22 17" /></svg>
                    <span>Website Name</span>
                </div>

                <div
                    style={{
                        fontSize: 64,
                        fontWeight: 700,
                        lineHeight: 1.1,
                        maxWidth: 900,
                        textTransform: 'capitalize'
                    }}
                >
                    {title}
                </div>

                <div
                    style={{
                        fontSize: 28,
                        opacity: 0.7,
                    }}
                >
                    example.com
                </div>
            </div>
        ),
        { ...size }
    );
}

Frequently Asked Questions

Can I use next-mdx-remote with the Pages Router?

Yes, but you'd import from next-mdx-remote (not the /rsc subpath) and use getStaticProps/getStaticPaths instead of generateStaticParams. The /rsc version shown in this guide is built specifically for the App Router's Server Components.

Do I need @next/mdx if I'm already using MDXRemote?

Not strictly — MDXRemote compiles MDX at runtime regardless of your next.config.mjs setup. But registering .mdx as a page extension avoids editor/tooling quirks and keeps the door open if you ever want static .mdx route files too.

How do I add images inside my MDX posts?

Just use standard Markdown image syntax: ![alt text](/path/to/image.png). If you want Next.js's optimized <Image> component instead, add an img key to your components object in mdx-components.tsx that renders next/image under the hood.

Why is my code block not syntax highlighted?

Double-check that your code component in mdx-components.tsx is running the content through sugar-high's highlight() function. If you copy-pasted code but forgot this override, code blocks fall back to plain unstyled text.

Can I fetch MDX content from a CMS instead of the filesystem?

Yes — that's actually one of the biggest advantages of next-mdx-remote over @next/mdx. Since MDXRemote just needs a raw MDX string, you can fetch that string from Contentful, Sanity, a database, or anywhere else instead of fs.readFileSync. The rest of the setup stays identical.

Wrapping Up

You now have a complete, production-ready MDX blog setup running on Next.js 16 — MDX files stored cleanly in content/blogs, a typed data layer for reading and sorting posts, custom-styled components, GitHub-flavored Markdown support, and per-post SEO metadata.

From here, natural next steps include adding tag-based filtering, a search feature, or auto-generated Open Graph images per post using next/og.

Helpful Resources

Related Guides

If you'd like to keep building out your Next.js stack, these guides pair well with this one:

Try These Free Developer Tools

While you're here, a couple of free tools that pair naturally with a fresh MDX blog setup like this one:

Meta Tag Generator for Next.js & HTML — generate SEO meta tags, Open Graph tags, Twitter Cards, canonical URLs, and JSON-LD structured data instantly. Handy for wiring up per-post metadata like the generateMetadata() function above.
Supabase RLS Policy Generator — if your next project pairs this blog setup with a Supabase backend, generate secure, performance-optimized Row Level Security policies in seconds.
Zod Schema Generator — generate Zod schemas instantly from JSON or TypeScript. Includes smart inference, live validation, React Hook Form, Next.js API Routes, and Server Actions.

📦 Source Code: View on GitHub

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

Syed Muhammad Ali — Wed, 01 Jul 2026 03:32:44 +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

Best Hosting Platforms for Next.js in 2026: Who Actually Handles ISR & PPR Correctly?

Syed Muhammad Ali — Sun, 28 Jun 2026 19:00:00 +0000

Every "best hosting for Next.js" post you'll find says roughly the same thing: Vercel is great, Netlify is a solid alternative, Cloudflare is fast, AWS is for enterprises. None of them tell you what actually happens when you deploy a page using Incremental Static Regeneration (ISR) or Partial Prerendering (PPR) to platforms that aren't Vercel.

That's the gap this post fills. Instead of comparing dashboards and pricing pages, we're going to look at what each platform's adapter actually does with ISR and PPR — because "supported" doesn't mean the same thing everywhere. This article focuses on architecture and feature behavior rather than benchmark results, since latency varies significantly by region, workload, cache hit ratio, and deployment configuration.

The Distinction Nobody Explains: Functional vs. Performance Fidelity

This is the single most useful framing in this whole post, and it comes straight from Next.js's own platform documentation.

💡 Tip: Next.js draws a line between two levels of platform support:

Functional fidelity — the feature works correctly. Your ISR page revalidates, your PPR shell renders.

Performance fidelity — the feature works optimally. The static shell is served from the CDN edge in milliseconds, not from a server function in another region.

A platform can have full functional fidelity for PPR (it renders correctly) while having much lower performance fidelity than Vercel (it's served from a function instead of true edge-cached HTML). Both are "PPR support" — but they perform very differently in production. Keep this distinction in mind for every platform below.

Why ISR and PPR Are Hard for Non-Vercel Platforms

Quick recap if you need it: ISR lets a static page revalidate itself in the background after a set time, without a full rebuild. PPR (the rendering mode behind Cache Components, Next.js's "use cache" model) splits a single page into a static shell plus dynamic "holes" that stream in separately.

Both features assume something most CDNs weren't built for: that cached HTML can be mutated after deployment — purged, regenerated, and partially streamed — rather than treated as an immutable file tied to one deploy. Traditional CDN deploy models (Netlify, Cloudflare Pages, AWS Amplify, and others all once worked this way) assume deployed assets never change until the next deploy. ISR and PPR break that assumption on purpose.

This is exactly why Next.js, Netlify, Cloudflare, AWS Amplify, and Google Cloud spent over a year building a shared Deployment Adapter API, which went stable in Next.js 16.2 (March 2026). Before this, most non-Vercel platforms were reverse-engineering Vercel's undocumented internal build output to support ISR at all. Now there's a public, versioned contract every platform builds against — including Vercel itself.

That context matters because it means platform support for these features is improving rapidly and consistently right now, not stagnant.

Platform-by-Platform Breakdown

Vercel

Vercel built Next.js, so unsurprisingly it has both full functional and the highest performance fidelity for ISR and PPR.

ISR: Native. Stale content serves instantly while regeneration happens in the background, with sub-second revalidation propagation across their edge network.
PPR / Cache Components: This is where the gap is biggest. PPR's design intentionally splits a response into a CDN-cacheable static shell plus a dynamically-stitched stream appended at request time. As of this writing, Vercel is the only platform that stitches that static shell and the dynamic stream together at the CDN edge itself — every other platform currently resolves PPR through a server/function layer instead of true edge stitching.

// app/products/[id]/page.tsx — works identically everywhere,
// but only Vercel currently serves the static part from true edge cache
async function getProduct(id: string) {
  "use cache";
  const res = await fetch(`https://api.example.com/products/${id}`);
  return res.json();
}

Best for: teams who want zero deployment-config overhead and the fastest possible PPR/ISR performance out of the box, and don't mind paying for that convenience.

⚠️ Common Mistake: Assuming Vercel's free Hobby tier scales like its paid tier. Function execution time, image optimization, and bandwidth all meter separately — a project that feels free in development can post a real bill in production.

Netlify

Netlify's Next.js Runtime is an officially maintained adapter, tested against every new stable Next.js release.

ISR: Fully supported, including both time-based and on-demand revalidation, via Netlify's fine-grained caching primitives for the Full Route Cache and Data Cache.
PPR: Supported — Netlify provisions a serverless Function specifically to handle SSR, ISR, and PPR. This gives full functional fidelity, but the static shell isn't served straight from CDN edge cache the way Vercel's is — it still runs through that Function layer, which is the performance-fidelity gap described above.

// next.config.ts — no Netlify-specific config needed for PPR itself,
// the adapter detects and provisions the right Functions automatically
const nextConfig = {
  cacheComponents: true,
};

Best for: teams who want Vercel-like functional completeness with a different pricing model or existing Netlify infrastructure (Forms, Identity, etc.).

⚠️ Common Mistake: Pointing Next.js rewrites at static files inside public/ — Netlify's adapter doesn't support that pattern, so routes that worked locally can silently 404 in production.

Cloudflare Workers (via OpenNext)

Cloudflare doesn't have a native Next.js runtime — you deploy through the community-maintained @opennextjs/cloudflare adapter, which transforms Next.js's build output into something Workers can run.

ISR: Supported through the adapter's caching layer.
PPR: Documented as supported for the App Router, but it's newer and still maturing — Cloudflare's own docs list PPR alongside features like Node Middleware as areas with ongoing compatibility work. A dedicated, verified Cloudflare adapter built on Next.js's new stable Adapter API is in active development, which should close most remaining gaps.
The catch: image optimization needs to be delegated to Cloudflare Images or configured separately — next/image doesn't work out of the box the way it does on Vercel.

# Cloudflare-specific deploy flow
npm install @opennextjs/cloudflare
npx @opennextjs/cloudflare
npx wrangler deploy

Best for: teams already invested in Cloudflare's edge network (Workers, D1, KV, R2) who want Next.js to live in the same ecosystem, and who can tolerate being slightly behind the bleeding edge on newer caching features.

⚠️ Common Mistake: Forgetting the nodejs_compat compatibility flag in wrangler.toml / wrangler.jsonc. Without it, plenty of Next.js server dependencies simply fail at runtime with confusing errors.

AWS Amplify

Amplify has supported Next.js SSR for a while, but it's noticeably behind on the newer caching model.

ISR: Time-based revalidation works. On-demand ISR (revalidatePath / revalidateTag triggered manually) is explicitly not supported — if your app relies on on-demand revalidation, it silently won't behave as expected on Amplify.
PPR / Cache Components: Not clearly documented as supported at the time of writing. Amplify's adapter has had open compatibility issues tracking Next.js 16 support, which suggests PPR support is still catching up rather than production-proven.
Build output is also capped at 220 MB for SSR apps — easy to hit with image-heavy or dependency-heavy projects.

Best for: teams already deep in AWS infrastructure (IAM, CloudFront, existing AWS billing) who need simple SSR + scheduled ISR, and who can verify PPR behavior thoroughly before relying on it in production.

⚠️ Common Mistake: Deploying with output: "export" and expecting ISR or SSR to work. Static export disables the Next.js server runtime entirely — no SSR, no ISR, no API routes, full stop.

Railway & Render (Container/Docker Platforms)

These two get grouped together because they take the same fundamental approach: you give them a Dockerfile or a Node process, and they run it. Functionally, this means ISR and PPR work exactly as well as they do in self-hosting — because that's effectively what's happening.

Railway: Has an official Next.js + Postgres deployment guide using output: "standalone" in a Dockerfile. SSR, SSG, and ISR all work as expected since it's a real persistent Node process. PPR isn't explicitly documented but should work for the same reason — it's just next start. The bigger concern reported in 2026 production usage isn't feature support, some users have reported reliability concerns around persistent storage and deployments, so production testing is important.
Render: Supports SSR, ISR, and API routes through its Web Service deployment type, also via Docker or Git-based builds. Same story as Railway — because it's a real Node process, feature support isn't the limiting factor. Zero-downtime rolling deploys need deliberate configuration; they're not automatic the way they are on Vercel.

Best for: teams who want container-based pricing predictability without writing their own Dockerfile-to-production pipeline from scratch, and who are comfortable being early on platform maturity.

⚠️ Common Mistake: Treating Railway or Render as "set and forget" the way Vercel is. Both still require you to think about zero-downtime deploys, shared cache for multiple instances, and monitoring — that operational layer doesn't disappear just because there's no explicit Next.js adapter to configure.

Self-Hosting (Docker, VPS, Fly.io, Cloud Run)

This is the one with the cleanest answer of all of them, straight from Next.js's own documentation:

A single next start process handles every Next.js feature correctly: Server Components, ISR, PPR, Cache Components, Server Actions, Proxy, and after().

Full functional fidelity, no adapter, no caveats — because there's no translation layer between your app and the framework. The tradeoffs aren't about features; they're about who's doing the operational work.

# Minimal self-hosting Dockerfile
FROM node:22-alpine AS base
WORKDIR /app
COPY . .
RUN npm ci && npm run build

FROM node:22-alpine AS runner
WORKDIR /app
COPY --from=base /app/.next/standalone ./
COPY --from=base /app/.next/static ./.next/static
EXPOSE 3000
CMD ["node", "server.js"]

What you give up is everything Vercel/Netlify automate for you:

Multi-instance cache coordination — if you scale beyond one server, revalidateTag() only invalidates the instance that handled the request by default. You need a shared cache handler (commonly Redis) so other instances learn about invalidations.
Streaming infrastructure — PPR's time-to-first-byte advantage depends on your reverse proxy actually supporting streaming responses. Without it, the static shell and dynamic content get buffered and sent together, which still works but quietly loses PPR's main benefit.
All the DevOps, full stop: TLS, zero-downtime deploys, observability, scaling rules.

Best for: teams with existing DevOps capacity, strict data residency or compliance requirements, or sustained traffic where Vercel's usage-based pricing starts to outpace flat compute costs.

⚠️ Common Mistake: Self-hosting without output: "standalone" in next.config.ts. Without it, your Docker image drags in the entire node_modules tree instead of a trimmed production bundle.

Quick Comparison

Platform	ISR (time-based)	ISR (on-demand)	PPR / Cache Components	Performance Fidelity
Vercel	✅ Native	✅ Native	✅ True edge-stitched shell	Highest
Netlify	✅ Via adapter	✅ Via adapter	✅ Via Function layer	High
Cloudflare Workers	✅ Via OpenNext	🟡 Maturing	🟡 Documented, still maturing	Medium
AWS Amplify	✅ Time-based only	❌ Not supported	🟡 Unclear / catching up	Medium-Low
Railway / Render	✅ (it's just Node)	✅ (it's just Node)	✅ (it's just Node)	Depends on your setup
Self-hosted	✅ Full fidelity	✅ Full fidelity	✅ Full fidelity	You configure it

So, Which One Should You Actually Use?

Default choice for most SaaS/MVP work: Vercel. The performance-fidelity gap on PPR is real, and for most projects, not having to think about adapters or streaming infrastructure is worth the premium.
Want Vercel-level functional support on a different platform or pricing model: Netlify is the most production-proven non-Vercel option for ISR and PPR today.
Already living in Cloudflare's ecosystem: Workers via OpenNext is viable, just confirm PPR behavior for your specific routes before launch — it's improving fast but newer than Netlify's support.
On AWS for compliance or org reasons: Amplify works for SSR + scheduled ISR; don't build a feature around on-demand revalidation or PPR there yet without testing thoroughly.
Want container simplicity without managing your own VPS: Railway or Render — but budget time for reliability testing, especially anything stateful.
Have DevOps capacity, compliance needs, or are past the point where usage-based pricing makes sense: self-host. Every feature works correctly by default; you're trading platform fees for engineering time.

Frequently Asked Questions

Does "supports ISR" mean it works exactly like Vercel?

Not necessarily. Use the functional vs. performance fidelity distinction from earlier in this post — most platforms now have functional support, but the experience (latency, edge caching, revalidation propagation speed) still varies.

Is PPR available everywhere yet?

Functionally, on most major platforms — yes. With the same performance characteristics as Vercel — no, not yet. Vercel currently has unique edge-stitching infrastructure that other platforms haven't replicated.

Will the new Adapter API make all platforms equal eventually?

It makes them correct against the same shared contract, which is a big deal for portability. It doesn't automatically make them equally fast — that still depends on each platform's own CDN and edge infrastructure investment.

Is self-hosting actually cheaper?

Compute usually is. Total cost isn't always — factor in the engineering hours for setup and ongoing maintenance, not just server bills, before assuming self-hosting wins on price.

Can I switch platforms later if I start with Vercel?

Yes, especially now that the Adapter API is stable and shared across platforms. It's not zero-effort, but it's far less risky than it was before this API existed.

Platform Migration Difficulty

Move From	Difficulty
Vercel → Netlify	Low
Vercel → OpenNext	Medium
Vercel → Self-hosted	Medium
Amplify → Vercel	Low

Wrapping Up

"Best Next.js hosting" isn't really a single ranking — it's a tradeoff between performance fidelity, pricing model, and how much operational work you want to own. Vercel still leads on PPR/ISR performance specifically because it built the rendering model the rest of the ecosystem is now catching up to. Everyone else is closing that gap at different speeds, and the new shared Adapter API is exactly why that gap is closing faster in 2026 than it ever has before.

If you're deploying something today: pick based on where your team already lives, then verify ISR/PPR behavior yourself in a staging deploy rather than trusting a docs page's checkmark — the distinction between "works" and "works well" is exactly what most comparison posts skip.

Useful Resources

Continue Learning

Next.js Rendering Strategies Explained: SSR, SSG, CSR, ISR & Cache Components (2026)

Syed Muhammad Ali — Sat, 27 Jun 2026 19:00:00 +0000

Ever opened the Next.js docs and seen acronyms like SSR, SSG, CSR, and ISR thrown around like everyone's supposed to just know what they mean? You're not alone. Half the confusion around Next.js performance comes down to one simple question nobody explains clearly enough: when does your page actually get built — and where?

Once you understand that one question, every rendering strategy in Next.js suddenly makes sense. By the end of this guide, you'll know exactly what SSR, SSG, CSR, and ISR mean, how the newer Cache Components model (powered by Partial Prerendering, or PPR) ties it all together, and which one to reach for in your own projects.

Why This Matters

Every page you build has to answer one question: "When should the HTML for this page get generated?"

There are really only three possible answers:

Ahead of time, during next build — before any user even visits the site.
On request, every time a user visits — generated fresh on the server.
In the browser, after the page loads — generated by JavaScript running on the user's device.

Next.js gives you a strategy for each answer, plus a smart hybrid (Cache Components) that mixes them on the same page. Here's the whole picture at a glance before we go through each one:

What Is SSR (Server-Side Rendering)?

💡 Think of it like: ordering food at a restaurant — you ask, the kitchen cooks it fresh, then it's served to you. Every single time.

SSR means the HTML for a page is generated on the server, for every single request. The user always gets fresh data, but the server has to do work on every visit.

In the Next.js App Router, you get SSR automatically whenever a page reads something that can only be known at request time — like cookies, headers, or search params — or when you explicitly opt a page into dynamic rendering.

// app/dashboard/page.tsx
import { cookies } from "next/headers";

export default async function DashboardPage() {
  const cookieStore = await cookies();
  const userId = cookieStore.get("userId")?.value;

  const res = await fetch(`https://api.example.com/users/${userId}`, {
    cache: "no-store", // tells Next.js: never cache this, always fetch fresh
  });
  const user = await res.json();

  return <h1>Welcome back, {user.name}</h1>;
}

What's happening here: because we read cookies() and pass cache: "no-store" to fetch, Next.js knows this page depends on request-specific data. It renders the page on the server every time someone visits, instead of reusing a cached copy.

Use SSR when:

The content is personalized per user (dashboards, account pages).
Data changes frequently and must always be fresh (stock prices, live order status).

⚠️ Common Mistake: Using SSR for content that rarely changes (like a blog post) wastes server resources. If the data isn't user-specific or constantly changing, you probably want SSG or ISR instead.

What Is SSG (Static Site Generation)?

💡 Think of it like: a printed menu — it's made once, in advance, and handed to every customer exactly the same.

SSG means the HTML is generated once, at build time, and then reused for every visitor. No server work happens per request — Next.js just serves the same pre-built HTML file.

// app/blog/[slug]/page.tsx
import { getPostBySlug, getAllPosts } from "@/lib/posts";

// This tells Next.js which pages to pre-build at build time
export async function generateStaticParams() {
  const posts = getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

export default async function BlogPostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = getPostBySlug(slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.description}</p>
    </article>
  );
}

What's happening here: generateStaticParams() tells Next.js exactly which blog post pages exist. At build time, Next.js renders each one into static HTML. When a real visitor requests /blog/my-post, the server just hands over the already-built file — no rendering work, no database hit, nothing. It's instant.

Use SSG when:

Content doesn't change often (blog posts, marketing pages, documentation).
You want the fastest possible load times and lowest server cost.

⚠️ Common Mistake: If your content updates frequently but you're using pure SSG, visitors will keep seeing stale data until you rebuild and redeploy the entire site. That's exactly the problem ISR solves — keep reading.

What Is CSR (Client-Side Rendering)?

💡 Think of it like: ordering a build-it-yourself meal kit — the server hands you the box and instructions (a minimal HTML shell), but your browser does the actual cooking (fetching data and rendering the final content).

A common misconception is that CSR means the server does nothing. It doesn't — Next.js still renders and sends a minimal HTML shell from the server for Client Components (usually the loading/empty state). What makes it "client-side" is that the data fetching and the final content render happen in the browser, after JavaScript downloads and runs. The browser then "hydrates" that HTML — attaching event listeners and making it interactive — before fetching data and re-rendering with the real content.

In Next.js, you get CSR by using Client Components with hooks like useState and useEffect (or a data-fetching library like React Query).

// components/live-notifications.tsx
"use client";

import { useEffect, useState } from "react";

type Notification = { id: string; message: string };

export function LiveNotifications() {
  const [notifications, setNotifications] = useState<Notification[]>([]);

  useEffect(() => {
    fetch("/api/notifications")
      .then((res) => res.json())
      .then(setNotifications);
  }, []);

  return (
    <ul>
      {notifications.map((n) => (
        <li key={n.id}>{n.message}</li>
      ))}
    </ul>
  );
}

What's happening here: the "use client" directive tells Next.js this component should be interactive in the browser. The server sends an initial HTML shell (which may contain little or no real data), then the browser fetches data and renders the final UI after hydration. Once JavaScript loads and hydrates that HTML, useEffect fires, fetches data from /api/notifications, and re-renders the list with real content — all in the browser.

Use CSR when:

The content is highly interactive and user-specific (notification feeds, live chat, dashboards that update constantly).
SEO doesn't matter for that specific piece of UI (search engines don't need to see it).

⚠️ Common Mistake: Making your entire page a Client Component "just to be safe." This kills SEO and slows down the initial load. Only mark the interactive parts as client components — let everything else stay on the server.

What Is ISR (Incremental Static Regeneration)?

💡 Think of it like: a printed menu that quietly reprints itself in the background every hour — customers always get a menu instantly, and it's rarely more than an hour out of date.

ISR is SSG's smarter sibling. Pages are still pre-built and served instantly like static pages, but Next.js automatically regenerates them in the background after a set amount of time, without you needing to rebuild and redeploy your whole app.

// app/products/[id]/page.tsx
async function getProduct(id: string) {
  const res = await fetch(`https://api.example.com/products/${id}`, {
    next: { revalidate: 3600 }, // regenerate this page at most once every hour
  });
  return res.json();
}

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const product = await getProduct(id);

  return (
    <div>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
    </div>
  );
}

What's happening here: revalidate: 3600 tells Next.js "this page can be served from cache for up to 3,600 seconds (1 hour)." The first visitor after that hour expires still gets the old cached page instantly — but Next.js triggers a regeneration in the background, so the next visitor gets the updated version. Nobody ever waits for a rebuild.

Use ISR when:

Content changes occasionally, but not so often that it needs to be SSR (product pages, pricing pages, news listings).
You want the speed of static pages without manually rebuilding every time data changes.

What Are Cache Components (and PPR)?

This is where things get genuinely exciting — and where most beginner tutorials stop short.

💡 Think of it like: a restaurant table that's already set, with bread on it the moment you sit down (static shell) — while your actual hot meal (dynamic content) is still being cooked and gets brought out the second it's ready.

Cache Components is Next.js's newer model for controlling caching explicitly, and it's what powers Partial Prerendering (PPR) under the hood. Instead of choosing one rendering strategy for an entire page, PPR lets a single page mix static and dynamic content together.

Here's the key idea: Next.js pre-renders a static "shell" of your page instantly (the parts that don't depend on the current request), and then streams in the dynamic parts as soon as they're ready — all without making the visitor wait for the slowest piece of data.

Step 1: Enable Cache Components

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

const nextConfig: NextConfig = {
  cacheComponents: true, // turns on the Cache Components / PPR model
};

export default nextConfig;

💡 Tip: Once cacheComponents is enabled, Next.js stops caching things implicitly. You now have to explicitly mark what should be cached using "use cache" — this makes caching predictable instead of "magic."

Step 2: Mark cacheable parts with `"use cache"`

// app/store/page.tsx
import { Suspense } from "react";
import { CartStatus } from "@/components/cart-status";

async function FeaturedProducts() {
  "use cache"; // this function's result gets cached and reused

  const res = await fetch("https://api.example.com/products/featured");
  const products = await res.json();

  return (
    <ul>
      {products.map((p: { id: string; name: string }) => (
        <li key={p.id}>{p.name}</li>
      ))}
    </ul>
  );
}

export default function StorePage() {
  return (
    <div>
      <h1>Welcome to the Store</h1>

      {/* Static shell — cached, renders instantly */}
      <FeaturedProducts />

      {/* Dynamic hole — depends on the current user, streams in separately */}
      <Suspense fallback={<p>Loading your cart...</p>}>
        <CartStatus />
      </Suspense>
    </div>
  );
}

What's happening here: FeaturedProducts has "use cache" at the top, so Next.js treats it as part of the static shell — it's pre-rendered and reused across visitors, just like SSG. CartStatus, on the other hand, depends on who's visiting (their cart), so it's wrapped in <Suspense>. Next.js sends the static shell (heading + featured products) instantly, then streams in the cart status the moment it's ready — without blocking the rest of the page.

This is the best of every world: the instant load of SSG, the freshness of SSR, all on the same page, without you manually choosing one strategy for the whole route.

💡 Tip: You can control how long cached content lives using cacheLife() (time-based expiry) and invalidate it on demand using cacheTag() + revalidateTag() — similar in spirit to ISR's revalidate, but with much finer control over what gets invalidated and when.

⚠️ Common Mistake: Don't put "use cache" on a function that returns data specific to the logged-in user with the default (shared) cache — that data could end up served to other users. Use "use cache: private" for personalized cached content instead.

Quick Comparison

Strategy	When HTML is built	Best for	Server load per request	SEO
SSR	On every request	Personalized, frequently changing data	High	Excellent
SSG	Once, at build time	Content that rarely changes	None	Excellent
CSR	Minimal shell on server, content rendered in browser after hydration	Highly interactive, non-SEO UI	Low (just the shell)	Depends
ISR	At build time + periodic background refresh	Content that changes occasionally	Low	Excellent
Cache Components (PPR)	Mixed — static shell instantly, dynamic parts streamed	Pages with both static and personalized sections	Only for the dynamic parts	Excellent

Frequently Asked Questions

Do I have to pick one strategy for my whole app?

No — and that's the whole point of Cache Components. You can mix strategies per page, and with PPR, even within the same page. Most real-world Next.js apps use a combination of all of these depending on the route.

Is ISR the same as Cache Components?

Not quite. ISR revalidates an entire page on a timer. Cache Components give you finer control — you choose exactly which functions or components get cached, for how long, and how they get invalidated, all while letting other parts of the same page stay dynamic.

Will Cache Components replace ISR completely?

For new projects using cacheComponents: true, yes — "use cache" with cacheLife() covers what revalidate used to do, plus more. Existing apps using the older caching model can keep working as-is, but new apps are encouraged to adopt Cache Components.

Does SSR hurt my SEO?

No — search engines see fully rendered HTML either way with SSR, SSG, or ISR. CSR is the one to watch, since content rendered purely in the browser can be harder for some crawlers to index reliably.

How do I know which strategy a page is using?

Run next build and check the build output — Next.js labels each route as Static, Dynamic, or Partial Prerendered (when Cache Components is enabled), so you can see exactly how each page will behave in production.

💡 Tip: Always test caching behavior with next build && next start rather than next dev — caching behaves differently in development mode and can be misleading.

Wrapping Up

Rendering strategy isn't a one-time architectural decision anymore — it's a per-component choice. SSR gives you freshness, SSG gives you speed, CSR gives you interactivity, ISR gives you a balance between the two static options, and Cache Components (powered by PPR) let you combine all of it on a single page without compromise.

Start simple: default to SSG/ISR for content-heavy pages, reach for SSR only when you genuinely need per-request freshness, and once you're comfortable, experiment with Cache Components to squeeze instant load times out of pages that still need personalized data.

Decision Tree

Is content personalized?
→ SSR

Is content mostly static?
→ SSG

Does it update occasionally?
→ ISR

Is it highly interactive UI?
→ CSR

Need static + dynamic on same page?
→ Cache Components / PPR

Useful Resources

Continue Learning

Clerk vs NextAuth (Auth.js) in 2026: Which One Should You Choose?

Syed Muhammad Ali — Fri, 26 Jun 2026 19:00:00 +0000

If you're starting a new Next.js project in 2026, picking an auth solution isn't as simple as it used to be. NextAuth has been renamed to Auth.js, it shipped a near-complete rewrite in v5, and Clerk has kept pushing further into the "auth + user management" space rather than just sign-in forms.

A lot of comparison posts floating around are still talking about NextAuth v4 and Clerk's old pricing, neither of which reflects what's actually shipping today. This guide compares the current versions, what changed, and which one makes sense for your project.

Quick Answer

Choose Clerk if you want the fastest setup, prebuilt UI components, and built-in user management features such as organizations, session management, and administrative tooling.
Choose Auth.js v5 if you want full control over your data, no vendor lock-in, and you're comfortable building your own UI and database schema.

Now let's get into why.

What Changed: NextAuth Became Auth.js

If you haven't followed the project closely, here's the short version:

The package is still installed as next-auth on npm, but the project rebranded to Auth.js and now also supports frameworks beyond Next.js (SvelteKit, Express, etc.) through @auth/core.
v5 is a full rewrite. The old pages/api/auth/[...nextauth].ts + authOptions pattern is gone. Everything is now exported from a single NextAuth() call.
Auth.js is no longer an independent project — it's now maintained under Better Auth Inc., after Better Auth (a newer, fast-growing auth library) effectively absorbed the project.

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

export const { auth, handlers } = NextAuth({
  providers: [GitHub],
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
export const { GET, POST } = handlers;

// proxy.ts
export { auth as proxy } from "@/auth";

No more separate getServerSession() import — you just call auth() anywhere on the server.

What Changed: Clerk

Clerk hasn't rewritten its API the way Auth.js did, but a few things are different from what older tutorials show:

Middleware is now proxy.ts in Next.js 16 (it was middleware.ts in Next.js ≤15 — same code, new filename).
Clerk ships a <Show when="signed-in"> / <Show when="signed-out"> component pattern now, replacing the older <SignedIn> / <SignedOut> components in newer examples.
The free tier was raised to 50,000 monthly active users, making it viable for a lot more side projects and early-stage SaaS apps than it used to be.

// proxy.ts
import { clerkMiddleware } from "@clerk/nextjs/server";

export default clerkMiddleware();

export const config = {
  matcher: [
    "/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",
    "/(api|trpc)(.*)",
    "/__clerk/(.*)",
  ],
};

By default clerkMiddleware() doesn't protect anything — you opt routes into protection explicitly, which is worth knowing before you assume your dashboard is locked down.

Setup Time

This is still the biggest practical difference.

Clerk: install the package, drop your publishable/secret keys into .env, add clerkMiddleware() to proxy.ts, wrap your layout in <ClerkProvider>. You get a working sign-in/sign-up flow, hosted by Clerk's Account Portal, in well under 15 minutes — no database, no schema, no email provider setup.

npm install @clerk/nextjs

Auth.js v5: install the package, create auth.ts, set up a route handler, configure a database adapter if you want persistent sessions (Prisma, Drizzle, etc.), and build your own sign-in UI since Auth.js ships no components. Realistically an hour or more for a first-time setup, more if you're also wiring up a database.

npm install next-auth@beta

If you're optimizing purely for "ship the login screen today," Clerk wins. If you're fine writing more code in exchange for control, Auth.js works.

Customization & Branding

Clerk gives you prebuilt components (<SignIn />, <SignUp />, <UserButton />) that are themeable but still recognizably Clerk's UI unless you build fully custom flows using their lower-level APIs.
Auth.js gives you zero UI. You design every form, every error state, every redirect. More work, but your auth pages look exactly like the rest of your app with no extra effort to "de-Clerk" them.

If brand consistency matters a lot (e.g. an enterprise client app), Auth.js or a fully custom Clerk flow both work — Clerk's default components just need more styling effort to disappear into your design system.

Data Ownership & Vendor Lock-In

Clerk stores your users on its infrastructure. You get a dashboard, audit logs, and organization management for free, but your user data lives outside your own database unless you sync it via webhooks.
Auth.js stores sessions and users wherever you point your adapter — your own Postgres, MySQL, MongoDB, whatever. You own the schema and the data outright.

For SaaS products where "we never see our own user data" is a hard no from a client or compliance team, Auth.js (or self-hosted alternatives like Better Auth) is the safer default.

Security: The Middleware Caveat

Worth knowing regardless of which library you pick: middleware-only session protection in Next.js has had a documented bypass (CVE-2025-29927), where a spoofed x-middleware-subrequest header could skip middleware checks entirely. Next.js patched it, but it's a good reminder not to rely on proxy.ts alone.

Practical takeaway for both libraries:

Re-verify the session inside Server Actions and Route Handlers, not just in proxy.ts.
Treat proxy-level redirects as a UX nicety, not your only security boundary.

// inside a Server Action, regardless of auth library
const session = await auth(); // or currentUser() for Clerk

if (!session) {
  return { error: "Unauthorized" };
}

Pricing

	Clerk	Auth.js (v5)
License	Free up to 50,000 MAU, paid tiers after	Free, open source
Hosting cost	None for auth itself	You pay for your own DB/hosting
Hidden costs	Add-ons (orgs, billing) may cost extra at scale	Dev time to build what Clerk gives free

Auth.js is "free" in license terms, but you're trading subscription cost for development time — building your own password reset flow, email verification, and admin tooling isn't free, it's just paid in hours instead of dollars.

Feature Comparison

Feature	Clerk	Auth.js v5
Setup Time	⭐⭐⭐⭐⭐	⭐⭐⭐
Prebuilt UI	Yes	No
Data Ownership	Hosted by Clerk	Fully yours
Organizations / Teams	Built-in	Build it yourself
OAuth Providers	Built-in, dashboard config	Built-in, code config
Customization	Good, more work for full control	Full, by default
Best For	MVPs, SaaS, fast launches	Apps needing full data ownership
Maintenance	Low	Medium

When Should You Use Clerk?

You're building an MVP and want auth solved in an afternoon.
You need organizations/teams (B2B SaaS) without building that system yourself.
You're under the 50K MAU free tier and want to stay focused on your actual product.

When Should You Use Auth.js v5?

You're migrating an existing NextAuth v4 codebase (in which case, this is still your path forward).
Data residency or compliance requirements mean user data must live in your own database.
You want to avoid per-user authentication pricing as you scale.

Note: if you're starting completely fresh with no NextAuth history, it's worth also looking at Better Auth, since it's now the team behind Auth.js itself and is increasingly positioned as the recommended path for new self-hosted projects.

Final Recommendation

For most freelance and SaaS MVP work in 2026, Clerk remains the fastest way to ship, especially if the project needs organizations or billing-adjacent auth features later. Auth.js v5 is the right call when a client specifically needs full ownership of user data, or when you're maintaining a codebase that already has NextAuth baked in.

Neither choice is permanent — plenty of teams start with Clerk to validate an idea and migrate to a self-hosted option once they have real scale and real requirements.

Useful Resources

Continue Learning

If you'd like a full step-by-step implementation guide, check out:

How to Integrate Sanity CMS with Next.js 16 App Router (2026 Guide)

Syed Muhammad Ali — Fri, 26 Jun 2026 05:57:55 +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

Stripe Subscriptions in Next.js 16: Complete SaaS Billing Guide (2026)

Syed Muhammad Ali — Thu, 25 Jun 2026 19:00:00 +0000

Most developers can wire up a one-time payment in an afternoon. Subscriptions? That's where things get confusing fast.

What happens when a user's card expires? What if they cancel mid-cycle? How do you know their subscription is still active before letting them into your dashboard? These aren't edge cases — they're everyday realities of any SaaS product.

The good news is Stripe handles almost all of this complexity for you. Your job is knowing how to plug it in correctly. In this guide, you'll build a complete monthly subscription billing flow in Next.js 16 using Stripe Checkout Sessions — the fastest and most reliable way to add subscriptions to your SaaS.

By the end, you'll have:

A pricing page that redirects users to Stripe Checkout
Webhook handling that activates subscriptions in your database
A customer portal where users can manage or cancel their plan
A solid understanding of how subscription lifecycle events work

Why Subscriptions Are Different From One-Time Payments

A one-time payment is simple: user pays → you deliver → done.

A subscription is an ongoing relationship. Stripe needs to charge the user every month, handle failed payments, retry logic, and tell your app what's happening at every step. Your backend needs to listen to those updates via webhooks and keep your database in sync.

If you skip webhooks and just trust the frontend redirect, you're asking for trouble. The user's payment could fail silently, or they could cancel their plan and still access your app for months.

What We're Building

A minimal SaaS billing setup with two plans:

Plan	Price
Starter	$29/month
Pro	$79/month

The flow works like this:

User clicks "Subscribe"
        ↓
Server Action creates Checkout Session
        ↓
User redirected to Stripe hosted checkout
        ↓
Payment completed → user redirected back
        ↓
Stripe fires webhook → your app activates subscription
        ↓
User can manage billing via Customer Portal

Prerequisites

Make sure you have:

Node.js 20+ installed
A Stripe account (free to create)
Basic familiarity with Next.js App Router

We'll be using:

Next.js 16 with App Router
TypeScript strict mode
Tailwind CSS for any UI
React Compiler (no manual useMemo/useCallback needed)

Step 1: Create a Next.js Project

npx create-next-app@latest stripe-subscriptions

Choose:

TypeScript ✅
Tailwind CSS ✅
App Router ✅
React Compiler ✅
src/ directory ✅

Move into the project:

cd stripe-subscriptions

Step 2: Install Stripe

npm install stripe

This is the official Stripe Node.js SDK. We'll use it on the server only — it should never touch the browser.

Step 3: Set Up Stripe Server Client

Create a reusable Stripe instance so you don't initialize it in every file.

// src/lib/stripe.ts
import Stripe from "stripe";

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2026-05-27.dahlia",
});

⚠️ Common Mistake: Never import this file into a Client Component. The STRIPE_SECRET_KEY must stay server-side only.

Step 4: Create Products and Prices in Stripe

Before writing code, set up your products in the Stripe dashboard.

Go to dashboard.stripe.com
Enable Test Mode (toggle in the top right)
Copy Publishable & Secret keys
Navigate to Product Catalog → Create Product
Create two products:

Starter Plan

Name: Starter
Price: $29.00 USD
Billing: Recurring → Monthly

Pro Plan

Name: Pro
Price: $79.00 USD
Billing: Recurring → Monthly

After saving, click into each product and copy the Price ID (starts with price_). You'll need these next.

Step 5: Configure Environment Variables

Create .env.local in your project root:

# .env.local
STRIPE_SECRET_KEY=sk_test_xxxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxxx
NEXT_PUBLIC_APP_URL=http://localhost:3000
STRIPE_WEBHOOK_SECRET=whsec_xxxx

# Price IDs
STRIPE_STARTER_PRICE_ID=price_xxxx
STRIPE_PRO_PRICE_ID=price_xxxx

⚠️ Important: Add .env.local to .gitignore immediately. Never commit secret keys to version control.

Variables starting with NEXT_PUBLIC_ are safe to expose to the browser. Everything else is server-only.

Step 6: Define Plan Constants

Keep your plan data in one place so you never hardcode price IDs across multiple files.

// src/lib/plans.ts
export const PLANS = {
  starter: {
    id: "starter",
    name: "Starter",
    price: 29,
    priceId: process.env.STRIPE_STARTER_PRICE_ID!,
    features: [
      "Up to 5 projects",
      "10GB storage",
      "Email support",
    ],
  },
  pro: {
    id: "pro",
    name: "Pro",
    price: 79,
    priceId: process.env.STRIPE_PRO_PRICE_ID!,
    features: [
      "Unlimited projects",
      "100GB storage",
      "Priority support",
      "Advanced analytics",
    ],
  },
} as const;

export type PlanId = keyof typeof PLANS;

💡 Tip: Using as const gives you full TypeScript autocompletion on plan IDs throughout your app — no magic strings.

Step 7: Create the Checkout Server Action

A Server Action is an async function that runs on the server. We'll use one to create the Stripe Checkout Session — this keeps your secret key safe and your code clean.

// src/actions/create-checkout.ts
"use server";

import { redirect } from "next/navigation";
import { stripe } from "@/lib/stripe";
import { PLANS, PlanId } from "@/lib/plans";

export async function createCheckout(
  prev: unknown,
  formData: FormData
) {
  let url;
  try {
    const planId = formData.get("planId") as PlanId;

    if (!planId || !(planId in PLANS)) {
      return { error: "Invalid plan selected" };
    }

    const plan = PLANS[planId];

    const session = await stripe.checkout.sessions.create({
      mode: "subscription",           // ← this is the key difference from one-time payments
      line_items: [
        {
          price: plan.priceId,
          quantity: 1,
        },
      ],
      success_url: `${process.env.NEXT_PUBLIC_APP_URL}/`,
      cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
      metadata: {
        planId,
      },
      // Collect billing address for invoices
      billing_address_collection: "auto",
      // Allows users to apply promo codes at checkout
      allow_promotion_codes: true,
    });

    if (!session.url) {
      return { error: "Failed to create checkout session" };
    }
    url = session.url;
  } catch (err) {
    return {
      error: err instanceof Error ? err.message : "Something went wrong",
    };
  }
  if (url) {
    redirect(url);
  }
}

What's happening here:

mode: "subscription" tells Stripe this is a recurring payment, not a one-time charge
line_items specifies which price the user is subscribing to
success_url / cancel_url control where Stripe sends the user after checkout
metadata.planId lets you identify which plan was purchased inside your webhook later
In subscription mode, Stripe automatically creates a Customer object — no extra config needed

Step 8: Build the Pricing Page

// src/app/pricing/page.tsx
"use client";

import { useActionState } from "react";
import { createCheckout } from "@/actions/create-checkout";
import { PLANS } from "@/lib/plans";

export default function PricingPage() {
  const [state, action, isPending] = useActionState(createCheckout, {
    error: "",
  });

  return (
    <main className="min-h-screen py-20 px-4">
      <div className="max-w-4xl mx-auto text-center mb-12">
        <h1 className="text-4xl font-bold tracking-tight">
          Simple, transparent pricing
        </h1>
        <p className="mt-4 text-muted-foreground text-lg">
          Start free. Upgrade when you're ready.
        </p>
      </div>

      <div className="grid md:grid-cols-2 gap-6 max-w-3xl mx-auto">
        {Object.values(PLANS).map((plan) => (
          <div
            key={plan.id}
            className="rounded-2xl border p-8 flex flex-col gap-6"
          >
            <div>
              <h2 className="text-xl font-semibold">{plan.name}</h2>
              <div className="mt-2">
                <span className="text-4xl font-bold">${plan.price}</span>
                <span className="text-muted-foreground"> / month</span>
              </div>
            </div>

            <ul className="space-y-2 flex-1">
              {plan.features.map((feature) => (
                <li key={feature} className="flex items-center gap-2 text-sm">
                  <span className="text-green-500">✓</span>
                  {feature}
                </li>
              ))}
            </ul>

            <form action={action}>
              <input type="hidden" name="planId" value={plan.id} />
              <button
                type="submit"
                disabled={isPending}
                className="w-full rounded-xl bg-primary text-primary-foreground py-3 font-medium disabled:opacity-50 transition-opacity"
              >
                {`Subscribe to ${plan.name}`}
              </button>
            </form>
          </div>
        ))}
      </div>

      {state?.error && (
        <p className="text-red-500 text-center mt-6">{state.error}</p>
      )}
    </main>
  );
}

The hidden planId input is how the Server Action knows which plan the user clicked. The name attribute on form inputs is what formData.get("planId") reads.

Step 9: Handle Subscription Events with Webhooks

This is the most important part. When a user pays (or cancels, or their card fails), Stripe sends a POST request to your webhook endpoint. Your app listens, updates the database, and keeps subscription state accurate.

⚠️ Never trust the frontend redirect alone. A user could close the tab after payment, the redirect could fail, or someone could fake the success URL. Webhooks are your source of truth.

Create the Webhook Route

// src/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) {
  try {
    const payload = await req.text();
    const sig = (await headers()).get("stripe-signature")!;

    let event: Stripe.Event;

    // Verify the webhook actually came from Stripe
    try {
      event = stripe.webhooks.constructEvent(payload, sig, endpointSecret);
    } catch (err) {
      const message = err instanceof Error ? err.message : "Unknown error";
      return NextResponse.json(
        { error: `Webhook signature failed: ${message}` },
        { status: 400 }
      );
    }

    switch (event.type) {
      // Fired when a new subscription is created and first payment succeeds
      case "checkout.session.completed": {
        const session = event.data.object as Stripe.Checkout.Session;

        if (session.mode !== "subscription") break;

        const customerId = session.customer as string;
        const subscriptionId = session.subscription as string;
        const planId = session.metadata?.planId;

        console.log("New subscription:", {
          customerId,
          subscriptionId,
          planId,
        });

        // TODO: Save to your database
        // await db.user.update({ stripeCustomerId: customerId, subscriptionId, plan: planId, status: "active" })

        break;
      }

      // Fired on every successful recurring charge
      case "invoice.paid": {
        const invoice = event.data.object as Stripe.Invoice;
        const subscriptionId = invoice.subscription as string;

        console.log("Invoice paid — subscription renewed:", subscriptionId);

        // TODO: Mark subscription as active / extend access period
        // await db.subscription.update({ id: subscriptionId, status: "active" })

        break;
      }

      // Fired when a payment fails (expired card, insufficient funds, etc.)
      case "invoice.payment_failed": {
        const invoice = event.data.object as Stripe.Invoice;
        const subscriptionId = invoice.subscription as string;

        console.log("Payment failed for subscription:", subscriptionId);

        // TODO: Notify user and mark subscription as past_due
        // await db.subscription.update({ id: subscriptionId, status: "past_due" })
        // await sendPaymentFailedEmail(invoice.customer_email)

        break;
      }

      // Fired when user cancels or subscription expires
      case "customer.subscription.deleted": {
        const subscription = event.data.object as Stripe.Subscription;

        console.log("Subscription cancelled:", subscription.id);

        // TODO: Revoke access
        // await db.subscription.update({ id: subscription.id, status: "cancelled" })

        break;
      }

      // Fired when plan changes (upgrade/downgrade)
      case "customer.subscription.updated": {
        const subscription = event.data.object as Stripe.Subscription;

        console.log("Subscription updated:", subscription.id, subscription.status);

        // TODO: Sync the new plan and status to your database

        break;
      }

      default:
        // Ignore unhandled event types
        break;
    }

    // Always return 200 so Stripe knows the event was received
    return NextResponse.json({ received: true }, { status: 200 });

  } catch (err) {
    const error = err instanceof Error ? err.message : "Unexpected error";
    console.error("Webhook error:", error);
    return NextResponse.json({ error }, { status: 500 });
  }
}

Why req.text() instead of req.json()?

Stripe's signature verification requires the raw request body as a string. If you parse it with .json() first, the signature check will fail. Always use .text() in webhook handlers.

Why return 200 even for events you don't handle?

Stripe retries events that don't get a 2xx response. If you return a 4xx for an unknown event type, Stripe will keep retrying it forever. Return 200 for everything that isn't a genuine error.

Step 10: Test Webhooks Locally with Stripe CLI

Stripe can't reach localhost, so you need the Stripe CLI to forward events to your dev server.

Install the Stripe CLI: docs.stripe.com/stripe-cli

Then run:

stripe listen --forward-to localhost:3000/api/webhook

This prints a webhook signing secret — copy it into your .env.local as STRIPE_WEBHOOK_SECRET.

In a separate terminal, start your dev server:

npm run dev

Now when you complete a test checkout, you'll see the events streaming in your CLI terminal.

Step 11: Add a Customer Portal

Once users are subscribed, they'll need a way to update their card, change plans, or cancel. Stripe's Customer Portal handles all of this for you.

Enable the Portal in Stripe Dashboard

Go to Settings → Billing → Customer Portal
Enable it and configure:
- Allow plan changes ✅
- Allow cancellations ✅
- Allowed plans: select your Starter and Pro prices
Save settings

Create the Portal Server Action

// src/actions/create-portal.ts
"use server";

import { redirect } from "next/navigation";
import { stripe } from "@/lib/stripe";

export async function createPortalSession(customerId: string) {
  if (!customerId) {
    throw new Error("Customer ID is required");
  }

  const session = await stripe.billingPortal.sessions.create({
    customer: customerId,
    return_url: `${process.env.NEXT_PUBLIC_APP_URL}/`,
  });

  redirect(session.url);
}

Add a "Manage Billing" Button to Your Home

// src/app/page.tsx
import { createPortalSession } from "@/actions/create-portal";

// In a real app, fetch the stripeCustomerId from your database
const DEMO_CUSTOMER_ID = "cus_xxxx"; // replace with real DB lookup

export default function Page() {
    const action = createPortalSession.bind(null, DEMO_CUSTOMER_ID)
    return (
        <main className="p-8">
            <h1 className="text-2xl font-bold mb-6">Dashboard</h1>

            <form
                action={action}
            >
                <button
                    type="submit"
                    className="w-fit rounded-xl border p-2 text-sm font-medium hover:bg-muted transition-colors"
                >
                    Manage Billing
                </button>
            </form>
        </main>
    );
}

When the user clicks "Manage Billing", they're taken to Stripe's hosted portal. They can update payment methods, switch plans, or cancel — and Stripe fires webhooks for every action so your database stays in sync automatically.

Step 12: Deploy and Configure Production Webhooks

Before going live, update your environment variables in Vercel (or your hosting provider):

Add all your .env.local variables to your Vercel project settings
Switch to live Stripe keys (sk_live_, pk_live_)
Create a new webhook in the Stripe Dashboard:
- Endpoint URL: https://yourdomain.com/api/webhook
- Events to listen for:
  - checkout.session.completed
  - invoice.paid
  - invoice.payment_failed
  - customer.subscription.deleted
  - customer.subscription.updated
Copy the signing secret and add it as STRIPE_WEBHOOK_SECRET in Vercel

Preventing Duplicate Processing

Stripe may send the same webhook event more than once if your server is slow or returns an error. Before processing any event, check if you've already handled it:

// Inside your webhook handler, before processing:
const eventId = event.id;

// Check if already processed
const existing = await db.webhookEvent.findUnique({ where: { stripeEventId: eventId } });
if (existing) {
  return NextResponse.json({ received: true }, { status: 200 });
}

// Store the event ID first, then process
await db.webhookEvent.create({ data: { stripeEventId: eventId } });
// ... rest of processing

This is called idempotency — handling the same event twice has the same result as handling it once.

Frequently Asked Questions

How do I know if a user's subscription is active?

Store the subscription status in your database when the webhook fires. On every protected page load, query your database for the user's subscription status. Don't call the Stripe API on every request — that's slow and wastes API calls. Keep your DB as the source of truth, synced by webhooks.

What's the difference between `checkout.session.completed` and `invoice.paid`?

checkout.session.completed fires once when a user completes the initial checkout. invoice.paid fires every time a subscription renews (monthly/yearly). You need to listen to both — one to activate the account, one to keep it active.

Can I offer a free trial?

Yes. Add subscription_data: { trial_period_days: 14 } to your stripe.checkout.sessions.create() call. Stripe won't charge the user until the trial ends, and it'll fire the appropriate webhook events when it does.

💡 Tip: Set payment_method_collection: "always" alongside a trial so Stripe collects card details upfront even though no charge happens immediately.

How do I handle plan upgrades and downgrades?

The Customer Portal handles this automatically. When a user switches plans through the portal, Stripe fires a customer.subscription.updated event with the new price ID. Listen for that event in your webhook and update the user's plan in your database.

Can I use this with an auth system like Clerk or NextAuth?

Absolutely. After authentication, store the stripeCustomerId alongside the user record in your database. When creating a checkout session for a logged-in user, pass customer: existingStripeCustomerId instead of customer_creation: "always" — this links the subscription to their existing Stripe customer.

Conclusion

You now have a production-ready subscription billing flow in Next.js 16 — pricing page, Stripe Checkout, webhook handling for the full subscription lifecycle, and a customer portal for self-service billing management.

The pattern here scales cleanly: add more plans to PLANS, add more webhook event handlers as your app grows, and you'll never have to touch the core flow.

From here, the natural next steps are connecting a real database to persist subscription status, and gating your app's features based on the user's active plan.

📦 Source Code: View on GitHub

Useful Resources

Continue Learning

How to Setup Resend Email in Next.js 16 (2026 Complete Beginner Guide)

Syed Muhammad Ali — Tue, 23 Jun 2026 19:00:00 +0000

Sending emails is one of the most common requirements in modern web applications.

Whether you're building:

A contact form
Authentication system
SaaS application
Newsletter platform
E-commerce store

You'll eventually need a reliable way to send emails.

In the past, developers often relied on SMTP providers and complicated email configurations. Today, services like Resend make email delivery significantly easier with a modern API-first approach.

In this guide, you'll learn how to integrate Resend with Next.js 16 using the App Router, create a contact form, send transactional emails, build reusable React Email templates, verify your domain, and deploy everything to production.

By the end of this tutorial you'll know how to:

✅ Create a Resend account

✅ Generate API keys

✅ Send emails using API Routes

✅ Send emails using Server Actions

✅ Create React Email templates

✅ Verify a custom domain

✅ Deploy to Vercel

What We'll Build

Here's the flow we'll create:

   User submits form
           ↓
Server Action / API Route
           ↓
      Resend API
           ↓
      User Inbox

When a visitor submits their email address, Next.js will securely send a request to Resend, which then delivers the email to the recipient.

What is Resend?

Resend is a modern transactional email platform built specifically for developers.

Unlike traditional SMTP providers, Resend offers a simple API that allows you to send emails with minimal configuration.

Some of its key features include:

Simple API integration
React Email support
Fast email delivery
Email analytics
Domain verification
Excellent developer experience
Great documentation

Common use cases include:

Contact forms
Welcome emails
Password reset emails
OTP verification emails
SaaS notifications
E-commerce receipts

Why Use Resend Instead of SMTP?

Traditional SMTP setups can become frustrating.

You often need to configure:

SMTP servers
Ports
Authentication
SSL/TLS settings
Email clients

Resend eliminates most of this complexity.

Instead of configuring SMTP manually, you simply send a request like this:

await resend.emails.send({
  from: "Acme <onboarding@resend.dev>",
  to: "user@example.com",
  subject: "Hello World",
  html: "<p>Hello from Resend</p>",
});

Resend vs SMTP

Feature	Resend	Traditional SMTP
Easy Setup	✅	❌
API-Based	✅	❌
React Email Support	✅	❌
Analytics	✅	Limited
Developer Experience	Excellent	Average
Modern Documentation	✅	Varies

Prerequisites

Before getting started, make sure you have:

Node.js installed
Basic React knowledge
Basic Next.js knowledge
VS Code or another editor

Recommended:

Custom domain
Vercel account

Create a Next.js 16 Project

Create a new Next.js application:

npx create-next-app@latest resend-email-guide

For this tutorial, choose:

TypeScript
Tailwind CSS
React Compiler
src directory

Move into the project:

cd resend-email-guide

Start the development server:

npm run dev

Why These Options?

TypeScript improves code quality and catches errors early.
Tailwind CSS speeds up UI development.
App Router is the recommended routing system in Next.js 16.
React Compiler automatically memoizes components and hooks to eliminate unnecessary re-renders.

Install Resend

Install the official Resend SDK:

npm install resend

This package allows your application to communicate with the Resend API.

Create a Resend Account

Visit:

https://resend.com

Then:

Create an account
Verify your email address
Open the dashboard

Generate a Resend API Key

Inside the Resend dashboard:

Open API Keys
Click Create API Key
Copy the generated key

Create a .env.local file:

RESEND_API_KEY=your_api_key_here

Never expose your API key in client-side code. API keys should only be used on the server.

Create a Reusable Resend Client

Instead of creating a new Resend instance everywhere, create a reusable client.

Create:

src/lib/resend.ts

import { Resend } from "resend";

export const resend = new Resend(
  process.env.RESEND_API_KEY
);

Now you can import this client throughout your application.

Create Your First Email API Route

Create:

src/app/api/send/route.ts

Add the following code:

import { isValidEmail } from "@/lib/helpers";
import { resend } from "@/lib/resend";

export async function POST(request: Request) {
  const { email } = await request.json();

  if (!email) {
    return Response.json(
      { error: "Email is required" },
      { status: 400 }
    );
  }

  if (!isValidEmail(email)) {
    return Response.json(
      { error: "Please enter a valid email" },
      { status: 400 }
    );
  }

  try {
    const data = await resend.emails.send({
      from: "onboarding@resend.dev",
      to: email,
      subject: "Hello from Next.js 16",
      html: "<p>Email sent successfully!</p>",
    });

    return Response.json(data);
  } catch (error) {
    return Response.json({ error });
  }
}

Understanding the Code

Creating the Email Request

await resend.emails.send(...)

This sends an email through the Resend API.

Returning Responses

Response.json(...)

Returns a JSON response back to the frontend.

Validation

Before sending emails, we validate user input to prevent unnecessary API calls.

Create an Email Validation Helper

Create:

src/lib/helpers.ts

export const isValidEmail = (
  email: string
) =>
  /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(
    email
  );

Why Validate Emails?

Validation helps:

Improve user experience
Reduce API usage
Prevent invalid submissions
Avoid unnecessary errors

Why Emails Should Be Sent Server-Side

Many beginners try sending emails directly from the frontend.

This is dangerous because:

API keys become public
Attackers can abuse your account
Security risks increase

Always send emails using:

Route Handlers
Server Actions
Backend APIs

Never expose API keys in client-side code.

Build a Contact Form

Create:

src/app/page.tsx

"use client";

import { useActionState } from "react";
import { isValidEmail } from "@/lib/helpers";

async function handleSubmit(
  _: unknown,
  formData: FormData
) {
  const email = formData.get("email") as string;

  if (!email) {
    return {
      message: "Email is required",
      success: false,
    };
  }

  if (!isValidEmail(email)) {
    return {
      message: "Please enter a valid email",
      success: false,
      email,
    };
  }

  const response = await fetch("/api/send", {
    method: "POST",
    body: JSON.stringify({ email }),
    headers: {
      "Content-Type": "application/json",
    },
  });

  if (response.ok) {
    return {
      message: "Email sent!",
      success: true,
    };
  }

  return {
    message: "Something went wrong",
    success: false,
    email,
  };
}

export default function HomePage() {
  const [state, action, isPending] = useActionState(handleSubmit, { message: '', success: false, email: '' });

  return (
    <main className="min-h-screen flex flex-col items-center justify-center bg-gray-100 p-4">
      <h1 className="text-2xl font-bold mb-4">Subscribe to our Newsletter</h1>
      <form action={action}>
        <input defaultValue={state.email} type="email" name="email" placeholder="Enter your email" className="mb-4 p-2 border rounded w-full" required />
        <button type="submit" className="px-4 py-2 bg-blue-500 text-white rounded w-full cursor-pointer" disabled={isPending}>
          {isPending ? "Sending..." : "Subscribe"}
        </button>
      </form>
      {state.message &&
        <p className={`mt-4 ${state.success ? 'text-green-500' : 'text-red-500'}`}>{state.message}</p>
      }
    </main>
  );
}

Understanding useActionState

useActionState() helps manage form state automatically.

It provides:

Current state
Form action
Loading state

Without it, you'd need multiple state variables and manual loading logic.

Test the Contact Form

Run the application:

npm run dev

Submit an email address.

Expected flow:

User enters email
Email is validated
API Route executes
Resend sends email
User sees success message
Email arrives in inbox

Using Server Actions Instead of API Routes

Next.js 16 encourages using Server Actions for form submissions.

Server Actions reduce boilerplate and keep logic closer to components.

API Routes vs Server Actions

API Routes	Server Actions
Separate endpoint	Built into components
More boilerplate	Less boilerplate
Traditional approach	Modern Next.js
Great for APIs	Great for forms

Create a Server Action

Create:

src/actions/send-email.ts

"use server";

import { resend } from "@/lib/resend";
import { isValidEmail } from "@/lib/helpers";

export async function sendEmail(
  _: unknown,
  formData: FormData
) {
  const email = formData.get("email") as string;

  if (!email) {
    return {
      message: "Email is required",
      success: false,
    };
  }

  if (!isValidEmail(email)) {
    return {
      message: "Please enter a valid email",
      success: false,
      email,
    };
  }

  try {
    await resend.emails.send({
      from: "onboarding@resend.dev",
      to: email,
      subject: "Hello from Next.js 16",
      html: "<p>Email sent successfully!</p>",
    });

    return {
      message: "Email sent!",
      success: true,
    };
  } catch {
    return {
      message: "Something went wrong",
      success: false,
      email,
    };
  }
}

Now update /src/app/page.tsx

const [state, action, isPending] = useActionState(handleSubmit, { message: '', success: false, email: '' });

const [state, action, isPending] = useActionState(sendEmail, { message: '', success: false, email: '' });

Now your form can call the Server Action directly without using a separate API route.

Send Beautiful Emails with React Email

While plain HTML works, React Email makes creating templates much easier.

Install the packages:

npm install react-email @react-email/components

Benefits:

Reusable templates
Type safety
Responsive layouts
Better maintainability

Create Your First Email Template

Create:

src/components/emails/welcome.tsx

import {
  Html,
  Body,
  Container,
  Heading,
  Text,
  Button,
} from "@react-email/components";

interface WelcomeEmailProps {
  username: string;
}

export default function WelcomeEmail({
  username,
}: WelcomeEmailProps) {
  return (
    <Html>
      <Body>
        <Container>
          <Heading>
            Welcome!
          </Heading>

          <Text>
            Hello {username}, thanks for joining our
            platform.
          </Text>

          <Button href="https://example.com">
            Get Started
          </Button>
        </Container>
      </Body>
    </Html>
  );
}

Send Dynamic Emails

Instead of hardcoding HTML:

html: "<p>Hello</p>";

Use React Email templates:

import WelcomeEmail from "@/components/emails/welcome";

await resend.emails.send({
  from: "onboarding@resend.dev",
  to: "user@example.com",
  subject: "Welcome!",
  react: WelcomeEmail({
    username: "Muhammad",
  }),
});

This makes your emails reusable and easier to maintain.

Verify Your Domain (Very Important)

For production applications, domain verification is essential.

Instead of:

onboarding@resend.dev

You'll eventually send emails from:

hello@yourdomain.com

Why Domain Verification Matters

Verified domains provide:

Better deliverability
Better branding
Higher inbox placement
Reduced spam risk

Add a Domain in Resend

Inside the Resend dashboard:

Open Domains
Click Add Domain
Enter your domain
Copy the DNS records

Configure DNS Records

Resend typically provides:

SPF
DKIM
DMARC

These records help email providers trust your emails.

SPF

Defines which servers can send emails for your domain.

Example:

v=spf1 include:_spf.resend.com ~all

DKIM

Adds a cryptographic signature proving emails are legitimate.

DMARC

Defines how providers should handle suspicious emails.

Example:

v=DMARC1; p=none;

Testing Emails Locally

When testing locally:

Use test email addresses
Monitor API limits
Verify responses
Check inbox and spam folders

Free plans may have sending restrictions.

Common Errors and Fixes

Invalid API Key

Check:

RESEND_API_KEY=

Make sure the value is correct.

Restart the development server after changes.

Domain Not Verified

Symptoms:

Emails fail
Emails land in spam
Delivery issues

Solution:

Verify DNS records
Wait for propagation
Re-check configuration

Rate Limit Errors

Free plans have sending limits.

Avoid:

Infinite loops
Automated testing spam
Excessive test emails

Proper Error Handling

Always wrap email requests in try/catch.

try {
  await resend.emails.send();
} catch (error) {
  console.error(error);
}

Good error handling makes debugging much easier.

Email Deliverability Best Practices

To avoid spam folders:

Use verified domains
Avoid ALL CAPS subject lines
Keep HTML clean
Use proper sender names
Include text alternatives
Avoid excessive links

Deploy to Vercel

Build your application:

npm run build

Push your code to GitHub and import the repository into Vercel.

Add Environment Variables in Vercel

Inside your Vercel dashboard:

Open Project Settings
Navigate to Environment Variables
Add:

RESEND_API_KEY

Redeploy your project after adding environment variables.

Real-World Use Cases

Use Case	Example
Contact Forms	Portfolio Websites
OTP Emails	Authentication Systems
Welcome Emails	SaaS Products
Password Reset	User Accounts
Order Receipts	E-commerce Stores
Notifications	Dashboards
Newsletters	Content Platforms

Common Beginner Mistakes

Sending Emails From the Client

Never expose API keys publicly.

Always use server-side code.

Hardcoding API Keys

Use environment variables instead.

Skipping Validation

Always validate user input before sending emails.

Forgetting Domain Verification

This can significantly hurt email deliverability.

Frequently Asked Questions

Is Resend Free?

Yes. Resend offers a free tier suitable for development and small projects.

Can I Use Resend with Next.js Server Actions?

Absolutely. Server Actions are one of the best ways to integrate Resend with Next.js 16.

Do I Need a Custom Domain?

Not for testing. However, production applications should verify a custom domain.

Can I Send HTML Emails?

Yes. You can send raw HTML or use React Email templates.

Does Resend Work with Vercel?

Yes. Resend integrates perfectly with Vercel deployments.

What's Next?

After learning the basics, explore:

Scheduled emails
Email queues
Background jobs
Batch email sending
Attachments
Analytics
Webhooks

Conclusion

Resend is one of the easiest ways to send transactional emails in Next.js 16.

Compared to traditional SMTP providers, it offers a significantly better developer experience, simpler setup, and excellent React Email integration.

In this guide, you learned how to:

Setup Resend
Generate API keys
Send emails using API Routes
Send emails using Server Actions
Create React Email templates
Verify domains
Deploy to Vercel

From here, you can build:

Authentication systems
SaaS products
Newsletter platforms
E-commerce workflows

Helpful Resources

Continue Learning

Source Code: View on Github

Stripe Checkout vs Payment Element in 2026: Which One Should You Choose?

Syed Muhammad Ali — Wed, 17 Jun 2026 19:00:00 +0000

If you're planning to accept online payments with Stripe, one of the first decisions you'll need to make is choosing between Stripe Checkout and Stripe Payment Element.

Both solutions are officially supported by Stripe and can handle payments securely, but they are designed for different use cases.

Many developers, especially beginners working with Next.js, often ask:

Which Stripe integration is easier?
Should I use Stripe Checkout or Payment Element?
Which one is better for SaaS products?
Which option offers more customization?
Can I switch later if my application grows?

In this guide, we'll compare Stripe Checkout vs Payment Element, explain how each solution works, and help you decide which one is the best fit for your project.

What Is Stripe Checkout?

Stripe Checkout is a hosted payment page provided by Stripe.

Instead of building your own payment form, you create a Checkout Session on your server and redirect customers to Stripe's secure checkout page.

Stripe handles:

Payment UI
Payment method collection
Security
Mobile responsiveness
Compliance requirements

This makes Checkout the fastest and easiest way to start accepting payments online.

How Stripe Checkout Works

         Customer
            ↓
       Your Website
            ↓
Stripe Hosted Checkout Page
            ↓
    Payment Completed
            ↓
 Your Website Success Page

The customer temporarily leaves your website, completes payment on Stripe's hosted page, and is then redirected back to your application.

Advantages of Stripe Checkout

Fastest Integration

Most developers can integrate Checkout in less than an hour.

You only need:

A Stripe account
A Checkout Session endpoint
A redirect to Stripe

Stripe Handles Compliance

Checkout is hosted entirely by Stripe, reducing your PCI compliance burden.

Built-In Payment Methods

Stripe automatically supports many payment methods depending on region and customer eligibility.

Examples include:

Credit Cards
Apple Pay
Google Pay
Link
Bank Transfers
Regional Payment Methods

Mobile Optimized

Stripe continuously optimizes the checkout experience for mobile devices.

Less Maintenance

Stripe manages checkout updates, security improvements, and payment flow enhancements for you.

Disadvantages of Stripe Checkout

Limited Customization

You can customize branding, logos, and colors, but the overall experience remains Stripe-controlled.

Customer Leaves Your Website

Users are redirected away from your application during checkout.

Less Control

You cannot fully customize every aspect of the payment experience.

What Is Stripe Payment Element?

Stripe Payment Element is a fully embeddable payment form that lives directly inside your application.

Unlike Checkout, users never leave your website.

The Payment Element allows you to build a custom checkout experience while still using Stripe's secure payment infrastructure.

How Payment Element Works

        Customer
           ↓
      Your Website
           ↓
     Payment Element
           ↓
Stripe Processes Payment
           ↓
      Success Page

Everything happens within your application's UI.

Advantages of Payment Element

Full Customization

You have complete control over:

Layout
Branding
User experience
Checkout flow

Customers Stay on Your Website

No external redirects are required.

Better Brand Consistency

The payment experience can perfectly match your application's design system.

Supports Advanced Flows

Payment Element works well for:

Complex ecommerce stores
Multi-step checkouts
Enterprise applications
Custom user experiences

Disadvantages of Payment Element

More Development Work

Implementation requires more code and configuration.

More Frontend Logic

You'll need to handle:

Client Secrets
Payment Intents
Form state
Payment confirmation

More Testing

Because the checkout flow is custom, you'll need additional testing and maintenance.

Stripe Checkout vs Payment Element: Feature Comparison

Feature	Stripe Checkout	Stripe Payment Element
Setup Time	⭐⭐⭐⭐⭐	⭐⭐⭐
Customization	⭐⭐	⭐⭐⭐⭐⭐
Hosted by Stripe	Yes	No
Customer Stays on Site	No	Yes
PCI Burden	Lowest	Low
Development Effort	Low	Medium
Best for Beginners	Yes	No
Branding Flexibility	Limited	Excellent
Maintenance	Low	Medium
Time to Launch	Fast	Slower
Checkout Control	Limited	Full

Next.js 16 Implementation Comparison

For many developers, implementation complexity is the deciding factor.

Let's compare both approaches.

Stripe Checkout with Next.js 16

A typical Checkout integration usually requires:

API Route or Server Action
Checkout Session
Redirect

Example flow:

        User Clicks Buy
               ↓
API Route Creates Checkout Session
               ↓
   Stripe Returns Checkout URL
               ↓
        Redirect User
               ↓
       Payment Complete

This simplicity makes Checkout ideal for:

Beginners
Startups
MVPs
SaaS applications

Stripe Payment Element with Next.js 16

A typical Payment Element integration usually requires:

API Route or Server Action
Payment Intent
Client Secret
Payment Element UI
Confirmation Flow

Example flow:

     User Opens Checkout
              ↓
Server Creates Payment Intent
              ↓
Client Receives Client Secret
              ↓
    Payment Element Loads
              ↓
     User Submits Payment
              ↓
     Payment Confirmation

The additional flexibility comes with additional implementation complexity.

When Should You Use Stripe Checkout?

Stripe Checkout is the best choice when speed and simplicity matter most.

SaaS Products

Checkout works exceptionally well for:

AI tools
Developer platforms
Subscription products
Productivity applications
Membership websites

Examples:

AI Resume Builder
AI Content Generator
Developer API Platform
Project Management SaaS

Small Businesses

Checkout is perfect for:

Service providers
Coaches
Agencies
Consultants
Small ecommerce stores

MVPs and Startups

If your goal is validating an idea quickly, Checkout is usually the right choice.

Benefits include:

Faster launch
Less code
Lower maintenance
Fewer bugs

When Should You Use Payment Element?

Payment Element is ideal when checkout experience becomes part of your competitive advantage.

Custom Ecommerce Stores

Online stores often require:

Custom designs
Upsells
Coupons
Multi-step checkout flows

Payment Element provides the flexibility needed for these experiences.

Enterprise Applications

Larger organizations often need:

Custom checkout logic
Internal workflows
Advanced integrations
Unique business requirements

Branded Experiences

If maintaining a consistent brand experience is important, Payment Element offers significantly more control.

Real Example: SaaS Product

Imagine you're building:

AI Resume Builder

Users:

Choose a subscription plan
Click Upgrade
Pay
Access premium features

For this workflow, Stripe Checkout is often more than enough.

Benefits:

Faster development
Fewer bugs
Secure by default
Easier maintenance

Most successful SaaS startups begin with Checkout.

Real Example: Large Ecommerce Store

Now imagine you're building:

Fashion Store

Requirements:

Custom checkout pages
Loyalty rewards
Upsells
Dynamic shipping
Custom order flows

In this situation, Payment Element becomes more attractive because it provides full checkout customization.

Performance Considerations

Many developers assume one option is significantly faster than the other.

In reality, the difference is usually small.

Stripe Checkout Performance

Advantages:

Stripe optimizes the hosted page
Less frontend JavaScript
Fewer components to render

Because Stripe controls the experience, performance optimization is largely handled for you.

Payment Element Performance

Advantages:

No external redirect
More seamless experience
Checkout stays inside your application

For users, the experience can feel more integrated.

Performance Winner

Tie

Both options provide excellent performance when implemented correctly.

Choose based on user experience and development requirements rather than speed alone.

Security Comparison

Security is one area where both solutions perform exceptionally well.

Both Stripe Checkout and Payment Element support:

PCI compliance
Strong Customer Authentication (SCA)
3D Secure
Fraud detection
Encrypted payment processing

Both solutions rely on Stripe's infrastructure to securely process payment information.

Security Winner

Tie

Neither option has a meaningful security advantage over the other.

Which One Does Stripe Recommend in 2026?

Stripe actively supports and recommends both products.

The right choice depends on your business requirements.

Choose Stripe Checkout If

You:

Are new to Stripe
Need the fastest implementation
Want less maintenance
Have a small team
Are building an MVP
Run a SaaS business

Choose Payment Element If

You:

Need complete customization
Want customers to stay on your site
Have unique checkout requirements
Need advanced ecommerce experiences
Have resources for additional development

Decision Matrix

Your Situation	Recommendation
First Stripe Integration	Checkout
SaaS Product	Checkout
Startup MVP	Checkout
Subscription Product	Checkout
Digital Product Sales	Checkout
Custom Checkout Design	Payment Element
Enterprise Application	Payment Element
Large Ecommerce Store	Payment Element
Advanced Checkout Flow	Payment Element

Migration Path

One of the biggest misconceptions is that choosing Checkout locks you into that solution forever.

It doesn't.

Can You Start with Checkout and Later Move to Payment Element?

Yes.

Many companies follow this exact progression:

      Launch MVP
          ↓
    Stripe Checkout
          ↓
   Validate Product
          ↓
  Grow Customer Base
          ↓
Need More Customization
          ↓
 Stripe Payment Element

This approach allows you to:

Launch faster
Validate demand
Reduce initial complexity
Invest in customization later

For most startups, this is the recommended path.

Frequently Asked Questions

Is Stripe Checkout Free?

Stripe Checkout does not have an additional fee.

You'll only pay Stripe's standard payment processing fees.

Is Payment Element Better Than Checkout?

Not necessarily.

Payment Element provides more customization, while Checkout provides greater simplicity.

The better choice depends entirely on your requirements.

Which Is Easier With Next.js 16?

Stripe Checkout is significantly easier to implement.

Most developers can integrate it much faster than Payment Element.

Can I Use Subscriptions With Both?

Yes.

Both Checkout and Payment Element fully support subscription-based billing.

Can I Switch Later?

Yes.

Many businesses start with Checkout and migrate to Payment Element as their requirements evolve.

Final Recommendation

If you're building your first Next.js application and want to start accepting payments quickly, Stripe Checkout is usually the best choice.

It offers:

Faster implementation
Less code
Lower maintenance
Excellent security
Built-in payment optimizations

Choose Stripe Payment Element when your application requires a highly customized checkout experience that stays entirely within your website.

For most startups, SaaS products, and MVPs, starting with Checkout and migrating later is often the most practical approach.

Helpful Resources

Stripe Checkout: https://stripe.com/docs/payments/checkout
Stripe Payment Element: https://stripe.com/docs/payments/payment-element
Stripe Payments Overview: https://stripe.com/payments
Next.js Documentation: https://nextjs.org/docs

Continue Learning

If you'd like step-by-step implementation guides, check out these tutorials:

These guides walk through complete setup, API routes, server actions, webhooks, and production deployment for both Stripe integrations.

Build a Todo App with Next.js 16 and Supabase (2026 Guide)

Syed Muhammad Ali — Mon, 15 Jun 2026 19:00:00 +0000

In this guide, we’ll build a production-ready Todo App using:

Next.js 16
Supabase
TypeScript
Tailwind CSS
Server Actions
Authentication
Row Level Security (RLS)

This tutorial focuses more on logic and architecture rather than UI design.

By the end of this guide, you'll have:

Authentication with Supabase
Protected routes
Todo CRUD operations
Row Level Security (RLS)
Form validation with Zod
Server Actions
Secure session handling

What We’re Building

Our Todo App will include:

User Registration
User Login
Protected Dashboard
Create Todo
Complete Todo
Delete Todo
Secure Database Access with RLS

Prerequisites

Before starting, make sure you have:

Node.js installed
A Supabase account
Basic understanding of React and Next.js

Folder Structure

proxy.ts
src
├── actions
│   ├── auth.ts
│   └── todo.ts
├── app
│   ├── layout.tsx
│   ├── (auth)
│   │   ├── layout.tsx
│   │   ├── login
│   │   │   └── page.tsx
│   │   ├── register
│   │   │   └── page.tsx
│   ├── (private)
│   |   ├── layout.tsx
│   |   ├── page.tsx
│   |   ├── create
│   │   │   └── page.tsx
├── components
│   ├── form-error.tsx
│   ├── input.tsx
│   ├── loading-button.tsx
│   ├── navbar.tsx
│   └── todo-actions.tsx
├── utils
│   ├── supabase
│   |   ├── client.ts
│   |   ├── proxy.ts
│   |   └── server.ts
│   ├── validators
│   |   ├── auth.ts
│   │   └── todo.ts

Create a Next.js 16 Project

Run the following command:

npx create-next-app@latest todo-app

Choose options according to your preferences.

Recommended setup:

TypeScript
Tailwind CSS
App Router
React Compiler
src/ directory

Now move into the project:

cd todo-app

Setup Supabase

Go to Supabase Dashboard:

Create a New Project

Click New Project
Enter project name
Enter database password
Select region
Enable automatic RLS
Click Create Project

Add Environment Variables

Inside your project Dashboard:

Under Get Connected section
Click Frameworks

Copy the environment variables.

Create .env.local in your project root:

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=

Install Supabase Packages

Run:

npm install @supabase/supabase-js @supabase/ssr

We’ll also install Zod later for validation.

Understanding Supabase Clients

Supabase provides two client types:

Browser Client

Used inside Client Components.

Server Client

Used inside:

Server Components
Server Actions
Route Handlers

Create Supabase Browser Client

Create:

/src/utils/supabase/client.ts

import { createBrowserClient } from "@supabase/ssr";

export const createClient = () =>
  createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
  );

Create Supabase Server Client

Create:

/src/utils/supabase/server.ts

import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export async function createClient() {
  const cookieStore = await cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll();
        },

        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            );
          } catch {
            // Ignore if called from Server Component
          }
        },
      },
    }
  );
}

Setup Supabase Session Middleware

Create:

/src/utils/supabase/proxy.ts

import { createServerClient } from "@supabase/ssr";
import { NextResponse, type NextRequest } from "next/server";

export async function updateSession(request: NextRequest) {
  let supabaseResponse = NextResponse.next({
    request,
  });

  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
    {
      cookies: {
        getAll() {
          return request.cookies.getAll();
        },

        setAll(cookiesToSet, headers) {
          cookiesToSet.forEach(({ name, value }) =>
            request.cookies.set(name, value)
          );

          supabaseResponse = NextResponse.next({
            request,
          });

          cookiesToSet.forEach(({ name, value, options }) =>
            supabaseResponse.cookies.set(name, value, options)
          );

          Object.entries(headers).forEach(([key, value]) =>
            supabaseResponse.headers.set(key, value)
          );
        },
      },
    }
  );

  await supabase.auth.getClaims();

  return supabaseResponse;
}

Setup Next.js Middleware

Create:

/src/proxy.ts

import { type NextRequest } from "next/server";
import { updateSession } from "@/utils/supabase/proxy";

export async function proxy(request: NextRequest) {
  return await updateSession(request);
}

export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico (favicon file)
     * Feel free to modify this pattern to include more paths.
    */
    "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
  ],
};

Create Route Groups

We’ll use route groups for better organization.

app
 ├── (auth)
 └── (private)

Route groups help organize routes without affecting URLs.

Learn more about Nextjs Route Groups.

Create Auth Layout

Create:

/app/(auth)/layout.tsx

export default function AuthLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <div className="bg-gray-900 flex items-center justify-center flex-1">
      {children}
    </div>
  );
}

Create Login Page

Create:

/app/(auth)/login/page.tsx

"use client";

import { login } from "@/actions/auth";
import FormError from "@/components/form-error";
import Input from "@/components/input";
import LoadingButton from "@/components/loading-button";
import Image from "next/image";
import Link from "next/link";
import { useActionState } from "react";

export default function Login() {
  const [state, formAction] = useActionState(login, {
    errors: {
      email: [],
      password: [],
      formError: "",
    },
    data: {
      email: "",
      password: "",
    },
  });

  return (
    <div className="flex flex-col justify-center w-full">
      <div className="sm:mx-auto sm:w-full sm:max-w-sm">
        <Image
          src="https://tailwindcss.com/plus-assets/img/logos/mark.svg?color=indigo&shade=500"
          alt="Logo"
          className="mx-auto"
          width={50}
          height={50}
        />

        <h2 className="mt-10 text-center text-2xl/9 font-bold tracking-tight text-white">
          Sign in to your account
        </h2>
      </div>

      <div className="mt-10 sm:mx-auto sm:w-full sm:max-w-sm">
        <form action={formAction} className="space-y-6">
          <Input
            defaultValue={state?.data?.email || ""}
            name="email"
            type="email"
            label="Email address"
          />

          <FormError errors={state.errors.email} />

          <Input
            defaultValue={state?.data?.password || ""}
            name="password"
            type="password"
            label="Password"
          />

          <FormError errors={state.errors.password} />

          <LoadingButton title="Sign in" />

          <FormError errors={state?.errors?.formError} />
        </form>

        <p className="mt-10 text-center text-sm/6 text-gray-400">
          Not a member?{" "}
          <Link
            href="/register"
            className="font-semibold text-indigo-400 hover:text-indigo-300"
          >
            Register
          </Link>
        </p>
      </div>
    </div>
  );
}

Important Note About Input Names

The name attribute is extremely important because we later access form values using:

formData.get("email")

If names don’t match, your form won’t work correctly.

Create Reusable Input Component

Create:

/src/components/input.tsx

interface InputProps {
  name: string;
  label?: string;
  type?: string;
  defaultValue?: string;
  required?: boolean;
}

const Input = ({
  name,
  label,
  type = "text",
  defaultValue,
  required = true,
}: InputProps) => {
  return (
    <div>
      {label && (
        <label
          htmlFor={name}
          className="block text-sm/6 font-medium text-gray-100"
        >
          {label}
        </label>
      )}

      <div className="mt-2">
        <input
          id={name}
          type={type}
          name={name}
          defaultValue={defaultValue}
          required={required}
          autoComplete={type === "email" ? "email" : undefined}
          className="block w-full rounded-md bg-white/5 px-3 py-1.5 text-base text-white outline-1 outline-white/10"
        />
      </div>
    </div>
  );
};

export default Input;

Create Loading Button

Create:

/src/components/loading-button.tsx

"use client";

import { useFormStatus } from "react-dom";

const LoadingButton = ({
  title,
  className = "",
}: {
  title: string;
  className?: string;
}) => {
  const { pending } = useFormStatus();

  return (
    <button
      disabled={pending}
      type="submit"
      className={`cursor-pointer flex w-full justify-center rounded-md bg-indigo-500 px-3 py-1.5 text-white ${className}`}
    >
      {pending ? "Loading..." : title}
    </button>
  );
};

export default LoadingButton;

What is useFormStatus?

useFormStatus() gives information about the latest form submission state.

We use it to:

Disable button while submitting
Show loading state
Prevent duplicate submissions

Create Form Error Component

Create:

/src/components/form-error.tsx

export default function FormError({
  errors,
}: {
  errors?: string | string[];
}) {
  if (!errors || (Array.isArray(errors) && errors.length === 0)) {
    return null;
  }

  return (
    <p aria-live="polite" className="text-sm text-red-500">
      {typeof errors === "string" ? errors : errors.join(", ")}
    </p>
  );
}

Install Zod

Run:

npm install zod

Create Auth Validation Schema

Create:

/src/utils/validators/auth.ts

import z from "zod";

export const authSchema = z.object({
  email: z.email(),
  password: z
    .string()
    .min(6, "Password must be at least 6 characters long")
    .max(100, "Password must not exceed 100 characters"),
});

Create Login Action

Create:

/src/actions/auth.ts

"use server";

import { redirect } from "next/navigation";
import { createClient } from "@/utils/supabase/server";
import { authSchema } from "@/utils/validators/auth";

export async function login(prev: unknown, formData: FormData) {
  const data = {
    email: formData.get("email") as string,
    password: formData.get("password") as string,
  };

  const validatedFields = authSchema.safeParse(data);

  if (!validatedFields.success) {
    return {
      data,
      errors: {
        ...validatedFields.error.flatten().fieldErrors,
        formError: "",
      },
    };
  }

  const supabase = await createClient();

  const { error } = await supabase.auth.signInWithPassword(
    validatedFields.data
  );

  if (error) {
    return {
      data,
      errors: {
        formError: error.message,
        email: [],
        password: [],
      },
    };
  }

  redirect("/");
}

Understanding the Login Action

Here’s what happens:

Get form values using formData
Validate using Zod
Call Supabase Auth API
Redirect user after successful login

Because this is a Server Action, we must use the server Supabase client.

Create Register Page

Create:

/app/(auth)/register/page.tsx

Use the same structure as login page but replace:

import { signup } from "@/actions/auth";

and:

<LoadingButton title="Sign up" />

Create Signup Action

Add this inside:

/src/actions/auth.ts

export async function signup(prev: unknown, formData: FormData) {
  const data = {
    email: formData.get("email") as string,
    password: formData.get("password") as string,
  };

  const validatedFields = authSchema.safeParse(data);

  if (!validatedFields.success) {
    return {
      data,
      errors: {
        ...validatedFields.error.flatten().fieldErrors,
        formError: "",
      },
    };
  }

  const supabase = await createClient();

  const { error } = await supabase.auth.signUp(validatedFields.data);

  if (error) {
    return {
      data,
      errors: {
        formError: error.message,
        email: [],
        password: [],
      },
    };
  }

  redirect("/");
}

Supabase may require email confirmation depending on project settings after signup.

Create Private Layout

Create:

/app/(private)/layout.tsx

import Navbar from "@/components/navbar";

export default function PrivateLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <>
      <Navbar />

      <div className="mt-16">{children}</div>
    </>
  );
}

Create Navbar

Create:

/src/components/navbar.tsx

import { logout } from "@/actions/auth";
import { createClient } from "@/utils/supabase/server";
import LoadingButton from "./loading-button";
import Link from "next/link";

const Navbar = async () => {
  const supabase = await createClient();

  const {
    data: { user },
  } = await supabase.auth.getUser();

  return (
    <div className="w-full flex items-center gap-4 p-4 bg-gray-800 justify-between">
      <div className="text-lg font-bold">
        Hi {user?.email}
      </div>

      <div className="flex items-center gap-4">
        <nav className="flex items-center gap-4">
          <Link href="/">Home</Link>
          <Link href="/create">Create Todo</Link>
        </nav>

        <form action={logout}>
          <LoadingButton title="Logout" />
        </form>
      </div>
    </div>
  );
};

export default Navbar;

Create Logout Action

Add this to:

/src/actions/auth.ts

export async function logout() {
  const supabase = await createClient();

  const { data: claimsData } = await supabase.auth.getClaims();

  if (claimsData?.claims) {
    await supabase.auth.signOut();
  }

  redirect("/login");
}

Protect Private Routes

Right now, users can manually access protected pages.

We need route protection.

Update:

/src/utils/supabase/proxy.ts

Replace this

await supabase.auth.getClaims()

With

const { data } = await supabase.auth.getClaims();

const user = data?.claims;
const publicRoutes = ["/login", "/register"];

if (user && publicRoutes.includes(request.nextUrl.pathname)) {
  const url = request.nextUrl.clone();
  url.pathname = "/";
  return NextResponse.redirect(url);
}

if (!user && !publicRoutes.includes(request.nextUrl.pathname)) {
  const url = request.nextUrl.clone();
  url.pathname = "/login";
  return NextResponse.redirect(url);
}

Understanding Logic

Here’s what happens:

Get User
Create Public Routes
First if block checks if the user is logged in & trying to access public routes then navigates user to Home
Second if block checks if the user is not logged in & trying to access private routes then navigates user to Login

How Route Protection Works

Public Routes

Anyone can access:

/login
/register

Private Routes

Only authenticated users can access them.

Additional Protection

Logged-in users cannot revisit auth pages.

Create Todos Table

Open:

Supabase Project Dashboard
From sidebar click SQL Editor

Run:

create table todos (
  id uuid primary key default gen_random_uuid(),
  user_id uuid references auth.users(id) on delete cascade not null,
  title text not null,
  completed boolean default false,
  created_at timestamptz default now()
);

Add Row Level Security Policies

Run:

create policy "Users can view own todos"
on todos
for select
using (auth.uid() = user_id);

create policy "Users can insert own todos"
on todos
for insert
with check (auth.uid() = user_id);

create policy "Users can update own todos"
on todos
for update
using (auth.uid() = user_id);

create policy "Users can delete own todos"
on todos
for delete
using (auth.uid() = user_id);

Why RLS is Important

Without RLS:

Any user could access all data.

With RLS:

Users can only access their own data.

This is one of the most important security features in Supabase.

Create Todo Validation Schema

Create:

/src/utils/validators/todo.ts

import z from "zod";

export const todoSchema = z.object({
  title: z
    .string()
    .min(2, "Title must be at least 2 characters long")
    .max(100, "Title must not exceed 100 characters"),
});

Create Todo Form

Create:

/app/(private)/create/page.tsx

"use client";

import { createTodo } from "@/actions/todo";
import FormError from "@/components/form-error";
import Input from "@/components/input";
import LoadingButton from "@/components/loading-button";
import { useActionState } from "react";

const CreateTodo = () => {
  const [state, formAction] = useActionState(createTodo, {
    error: "",
    data: {
      title: "",
    },
  });

  return (
    <div className="mt-10 sm:mx-auto sm:w-full sm:max-w-sm">
      <form action={formAction} className="space-y-6">
        <Input
          defaultValue={state?.data?.title || ""}
          name="title"
          label="Todo Title"
        />

        <FormError errors={state?.error} />

        <LoadingButton title="Create Todo" />
      </form>
    </div>
  );
};

export default CreateTodo;

Create Todo Action

Create:

/src/actions/todo.ts

"use server";

import { todoSchema } from "@/utils/validators/todo";
import { createClient } from "@/utils/supabase/server";
import { redirect } from "next/navigation";

export async function createTodo(
  prev: unknown,
  formData: FormData
) {
  const supabase = await createClient();

  const data = {
    title: formData.get("title") as string,
  };

  const validatedFields = todoSchema.safeParse(data);

  if (!validatedFields.success) {
    return {
      data,
      error:
        validatedFields.error.flatten().fieldErrors.title?.[0],
    };
  }

  const {
    data: { user },
  } = await supabase.auth.getUser();

  if (!user) {
    return {
      data,
      error: "Please login first",
    };
  }

  const { error } = await supabase.from("todos").insert({
    title: validatedFields.data.title,
    user_id: user.id,
  });

  if (error) {
    return {
      data,
      error: error.message,
    };
  }

  redirect("/");
}

Understanding the Create Todo Action

Here’s what happens:

Get form values using formData
Validate using Zod
Get logged in user
Call Supabase Auth API
Redirect user after successful insert

Create Home Page

Move:

/app/page.tsx

to:

/app/(private)/page.tsx

Now update it:

import TodoActions from "@/components/todo-actions";
import { createClient } from "@/utils/supabase/server";

export default async function Home() {
  const supabase = await createClient();

  const { data } = await supabase
    .from("todos")
    .select("*")
    .order("created_at", {
      ascending: false,
    });

  return (
    <div className="overflow-x-auto rounded-2xl border border-gray-200 bg-white shadow-sm max-w-xl mx-auto">
      <table className="divide-y divide-gray-200 w-full">
        <thead className="bg-gray-50">
          <tr>
            {['Todo', 'Status', 'Actions'].map((header) => (
              <th
                key={header}
                className="px-6 py-4 text-left text-sm font-semibold text-gray-700">
                {header}
              </th>
            ))}
          </tr>
        </thead>

        <tbody className="divide-y divide-gray-100 bg-white">
          {data?.map((todo) => (
            <tr
              key={todo.id}
              className="transition-colors hover:bg-gray-50"
            >
              <td className="px-6 py-4">
                <p className="font-medium text-gray-900">
                  {todo.title}
                </p>
              </td>

              <td className="px-6 py-4">
                <span
                  className={`inline-flex rounded-full px-3 py-1 text-xs font-medium ${todo.completed
                    ? "bg-green-100 text-green-700"
                    : "bg-yellow-100 text-yellow-700"
                    }`}
                >
                  {todo.completed ? "Completed" : "Pending"}
                </span>
              </td>

              <td className="px-6 py-4">
                <TodoActions todoId={todo.id} isCompleted={todo.completed} />
              </td>
            </tr>
          ))}
        </tbody>
      </table>

      {data?.length === 0 && (
        <div className="py-10 text-center text-sm text-gray-500">
          No todos found
        </div>
      )}
    </div>
  );
}

We’re fetching todos in descending order so that the latest todo comes at top.

Create Todo Actions Component

Create:

/src/components/todo-actions.tsx

'use client';

import { handleTodoAction } from "@/actions/todo";
import { useActionState } from "react";

const TodoActions = ({ todoId, isCompleted }: { todoId: string; isCompleted: boolean; }) => {
    const [_, action, isPending] = useActionState(handleTodoAction, undefined);

    const completeTodo = () => action({ todoId, action: "complete" });
    const deleteTodo = () => action({ todoId, action: "delete" });

    return (
        <form className="flex justify-end gap-3">
            {!isCompleted &&
                <button
                    formAction={completeTodo}
                    disabled={isPending}
                    className="rounded-lg disabled:opacity-50 bg-blue-500 px-4 py-2 text-sm font-medium text-white transition hover:bg-blue-600"
                >
                    Complete
                </button>
            }
            <button
                formAction={deleteTodo}
                disabled={isPending}
                className="rounded-lg disabled:opacity-50 bg-red-500 px-4 py-2 text-sm font-medium text-white transition hover:bg-red-600"
            >
                Delete
            </button>
        </form>
    )
}

export default TodoActions

Complete and Delete Todo Action

Add inside:

/src/actions/todo.ts

import { revalidatePath } from "next/cache";

export async function handleTodoAction(prev: unknown, data: { todoId: string; action: "delete" | "complete" }) {

    const { todoId, action } = data;

    if (!todoId) return;

    const supabase = await createClient()
    const { data: { user } } = await supabase.auth.getUser();

    if (!user) return;

    if (action === 'delete') {
        await supabase
            .from("todos")
            .delete()
            .eq("id", todoId)
            .eq("user_id", user.id);
    } else {
        await supabase
            .from("todos")
            .update({
                completed: true,
            })
            .eq("id", todoId)
            .eq("user_id", user.id);
    }
    revalidatePath('/');
}

Final Result

You now have a fully functional Todo App with:

Next.js 16
Supabase Authentication
Protected Routes
Server Actions
Zod Validation
Secure RLS Policies
CRUD Operations

Conclusion

This project demonstrates a modern full-stack architecture using:

Next.js 16
Server Actions
Supabase
RLS
Authentication

Even though it’s a simple Todo App, the structure is production-ready and scalable.

You can now build larger applications using the same architecture and patterns.

Useful Resources

Source Code: View on GitHub

How to Add Clerk Authentication in Next.js 16 (2026 Guide)

Syed Muhammad Ali — Sun, 14 Jun 2026 19:00:00 +0000

Introduction

Authentication is one of the most important parts of modern web applications. Whether you're building a SaaS product, admin dashboard, marketplace, or social platform, you need a secure way to manage users, sessions, and protected routes.

In this guide, you'll learn how to add authentication to your Next.js 16 app using Clerk. We’ll cover:

Setting up Clerk in Next.js 16
Creating sign-in and sign-up pages
Protecting private routes
Accessing authenticated users in server components
Protecting server actions
Adding social login
Understanding route groups and dynamic routes

By the end, you’ll have a complete authentication system running in your app.

Why Use Clerk for Authentication?

Building authentication from scratch is time-consuming and error-prone. You need to handle:

Password hashing
Sessions
Social login
Email verification
Security best practices
Protected routes
User management

Instead of reinventing all of this, Clerk provides a production-ready authentication system with prebuilt UI components and secure session handling.

Key Features of Clerk

Prebuilt authentication UI
User management dashboard
Social login providers
Session management
Route protection
Server-side authentication helpers
Easy integration with Next.js

Clerk works extremely well with the App Router in Next.js 16 and makes authentication much simpler.

What You’ll Build

In this tutorial, we’ll create:

Sign-in page
Sign-up page
Protected private routes
Navbar with auth state
Server-side user authentication
GitHub OAuth login

Prerequisites

Before starting, make sure you have:

Node.js installed
Basic knowledge of React and Next.js
A Clerk account

Create a Next.js Project

Create a new Next.js app using:

npx create-next-app@latest clerk-auth

Choose the options according to your preferences.

For this tutorial, we’re using:

TypeScript
Tailwind CSS
React Compiler
src/ directory

Install Clerk

Install Clerk in your project:

npm install @clerk/nextjs

Project Folder Structure

Your project structure will look like this:

root/
    .env.local

src/
  proxy.ts

  app/
    layout.tsx
    globals.css

    (private)/
      layout.tsx
      page.tsx

    (public)/
      layout.tsx

        sign-in/[[...sign-in]]/
          page.tsx

        sign-up/[[...sign-up]]/
          page.tsx

  components/
    navbar.tsx

Add Clerk Middleware

Create a proxy.ts file.

If you’re using the src directory, place it inside src/proxy.ts.

src/proxy.ts

import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware();

export const config = {
  matcher: [
    // Skip Next.js internals and static files
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',

    // Always run for API routes
    '/(api|trpc)(.*)',

    // Clerk frontend API routes
    '/__clerk/(.*)',
  ],
}

What Does This Middleware Do?

The Clerk middleware:

Handles authentication sessions
Detects signed-in users
Protects routes
Works with both client and server components

The matcher ensures middleware runs only where necessary.

Wrap Your App with ClerkProvider

Now wrap your application with ClerkProvider.

src/app/layout.tsx

import { ClerkProvider } from '@clerk/nextjs'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body className="min-h-full flex flex-col">
        <ClerkProvider>
          {children}
        </ClerkProvider>
      </body>
    </html>
  )
}

Why Use ClerkProvider?

ClerkProvider gives your entire application access to:

Authentication state
User sessions
Clerk UI components
Server helpers

Without it, Clerk components won’t work.

Create a Navbar Component

Now let’s create a navigation bar that changes depending on whether the user is logged in.

src/components/navbar.tsx

import {
  Show,
  SignInButton,
  SignUpButton,
  UserButton,
} from '@clerk/nextjs'

const Navbar = () => {
  return (
    <header className="flex justify-end items-center p-4 gap-4 h-16 shadow-md">
      <Show when="signed-out">
        <SignInButton />

        <SignUpButton>
          <button className="bg-[#6c47ff] text-white rounded-full font-medium text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5 cursor-pointer">
            Sign Up
          </button>
        </SignUpButton>
      </Show>

      <Show when="signed-in">
        <UserButton />
      </Show>
    </header>
  )
}

export default Navbar

Understanding the Clerk Components

`Show`

The Show component conditionally renders content based on authentication state.

<Show when="signed-in">

<Show when="signed-out">

`SignInButton`

Opens the Clerk sign-in flow.

`SignUpButton`

Opens the Clerk sign-up flow.

`UserButton`

Displays the authenticated user avatar and account menu.

Clerk has a lots of built in UI components that’s already do the heavy lifting, learn more Clerk’s UI Components.

Add Navbar to Root Layout

Update your root layout:

src/app/layout.tsx

import { ClerkProvider } from '@clerk/nextjs'
import Navbar from '@/components/navbar'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <ClerkProvider>
          <Navbar />
          {children}
        </ClerkProvider>
      </body>
    </html>
  )
}

Start the Development Server

Run:

npm run dev

You’ll see a Clerk popup in the bottom-left corner.

Click:

Configure your application

You’ll be redirected to the Clerk dashboard.

Create a Clerk Application

After logging into Clerk:

Enter your application name
Create the application
Copy your environment variables

Add Environment Variables

Create a .env.local file.

.env.local

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_****
CLERK_SECRET_KEY=***

After adding them, restart your development server.

Create a Custom Sign-In Page

Now let’s create our own sign-in route.

src/app/(public)/sign-in/[[...sign-in]]/page.tsx

import { SignIn } from '@clerk/nextjs'

const Login = () => {
  return <SignIn />
}

export default Login

Understanding the Route Structure

Route Groups

(public)

This is a Route Group in Next.js.

Route groups help organize routes without affecting the URL.

Learn more about Nextjs Route Groups.

Dynamic Catch-All Routes

[[...sign-in]]

This is a dynamic catch-all route.

It allows Clerk to handle multiple auth-related routes internally.

Learn more about Nextjs Dynamic Routes.

Create a Custom Sign-Up Page

src/app/sign-up/[[...sign-up]]/page.tsx

import { SignUp } from '@clerk/nextjs'

export default function Page() {
  return <SignUp />
}

Redirect Clerk Buttons to Custom Pages

Right now, the buttons still redirect to Clerk-hosted pages.

To fix this, update .env.local.

.env.local

NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

Now the buttons will redirect to your custom routes.

Learn more about these environment variables and how to customize Clerk's redirect behavior in this dedicated clerk redirect guide.

Render User Information in a Server Component

Now let’s display the logged-in user’s name.

Move your homepage into a private route group:

app/(private)/page.tsx

And add

import { currentUser } from '@clerk/nextjs/server'

const Home = async () => {
  const user = await currentUser()

  return (
    <div className='mt-3 text-2xl'>
      Welcome {user?.fullName}
    </div>
  )
}

export default Home

Why Use `currentUser()`?

currentUser() works inside Server Components and allows you to securely access authenticated user data.

This is one of the best parts of using Clerk with Next.js App Router.

Protect Private Routes

Right now, unauthenticated users can still access your pages.

Let’s fix that.

Update your proxy.ts.

src/proxy.ts

import {
  clerkMiddleware,
  createRouteMatcher,
} from '@clerk/nextjs/server'

const isPublicRoute = createRouteMatcher([
  '/sign-in(.*)',
  '/sign-up(.*)',
])

export default clerkMiddleware(async (auth, req) => {
  if (!isPublicRoute(req)) {
    await auth.protect()
  }
})

export const config = {
  matcher: [
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    '/(api|trpc)(.*)',
    '/__clerk/(.*)',
  ],
}

How Route Protection Works

We created a public route matcher:

const isPublicRoute = createRouteMatcher([
  '/sign-in(.*)',
  '/sign-up(.*)',
])

Everything except those routes becomes protected.

await auth.protect()

If the user is not authenticated, Clerk automatically redirects them to the sign-in page.

Protect Server Actions

You can also secure server actions using Clerk’s auth() helper.

dummy-server-action.ts

'use server'

import { auth } from '@clerk/nextjs/server'

export const dummyAction = async () => {
  // Check if user is authenticated
  const { isAuthenticated } = await auth()

  if (!isAuthenticated) {
    return {
      error: 'Please login',
    }
  }

  // Database logic here
}

Why Protect Server Actions?

Even if your UI is protected, server actions should still verify authentication because users can manually send requests.

This adds an additional security layer.

Add GitHub Authentication

Clerk also supports social authentication providers like:

GitHub
Google
Discord
Microsoft
Apple

Let’s enable GitHub login.

Enable GitHub Login in Clerk

Go to your Clerk dashboard:

Select your application
Open the Configure tab
Click SSO Connections
Click Add Connection
Select GitHub
Enable:
- Sign-in
- Sign-up
Save the connection

Now users can authenticate using GitHub.

Important Production Note

When deploying to production, you should also enable:

Use Custom Credentials

This requires configuring your own GitHub OAuth credentials.

Follow this clerk doc on How to setup Github Custom Credentials.

Tip

If the built-in Clerk UI components don’t fully match your design requirements, you can create fully custom authentication flows using Clerk APIs. For more information, see the custom flow guide.

Common Mistakes to Avoid

Forgetting ClerkProvider

Without ClerkProvider, Clerk components won’t work.

Incorrect Middleware Location

If using src/, place middleware inside:

src/proxy.ts

Missing Environment Variables

Always restart your development server after changing .env.local.

Not Protecting Server Actions

Client-side protection alone is not enough.

Always validate authentication on the server.

Final Thoughts

You now have a complete authentication system in your Next.js 16 application using Clerk.

You learned how to:

Install Clerk
Create sign-in and sign-up pages
Protect routes
Access users in server components
Secure server actions
Add GitHub authentication

Clerk removes a huge amount of complexity from authentication and integrates extremely well with modern Next.js applications.

If you're building production-grade applications, Clerk is one of the fastest and safest ways to add authentication.

Next Steps

Helpful Resources

How to Integrate Stripe Payment Element with Next.js 16 (2026 Edition)

Syed Muhammad Ali — Sat, 13 Jun 2026 19:00:00 +0000

Stripe Payment Element is one of the best ways to accept payments in modern web applications. It keeps sensitive card information on Stripe servers, helping reduce PCI (Payment Card Industry) compliance complexity.

In this beginner-friendly guide, you'll learn how to integrate Stripe Payment Element with Next.js 16 using:

App Router
Server Actions
Payment Intents
Stripe Webhooks
TypeScript

By the end of this guide, you'll have a fully working checkout flow.

What We Are Building

In this tutorial, we'll create a simple SaaS pricing page with two packages:

Package	Price
Harmony	$399
Legacy	$599

When the user clicks a package:

A Stripe Payment Intent will be created
Stripe Payment Element will appear
User enters payment details
Payment is confirmed
Stripe webhook handles payment success

This guide mainly focuses on the Stripe integration rather than UI design, so we will keep the UI simple.

Two Ways to Accept Payments in Stripe

Stripe provides two main checkout methods.

1. Stripe Hosted Checkout

Stripe hosts the entire checkout page.

User flow:

Your Website → Stripe Checkout → Back to Your Website

This method is easier to set up. I've full guide covering this method please visit How to Integrate Stripe Hosted Checkout with Nextjs 16
.

2. Stripe Payment Element (What We'll Use)

Stripe checkout form is embedded directly inside your website.

Benefits:

Better UX
Fully customizable
No redirect before payment

Create a Next.js 16 Project

Run:

npx create-next-app@latest myapp

Choose your preferred setup.

Recommended:

TypeScript
App Router
src directory
React Compiler

Install Stripe Packages

Run:

npm install stripe @stripe/react-stripe-js @stripe/stripe-js

These packages help us:

Package	Purpose
stripe	Server-side Stripe SDK
@stripe/react-stripe-js	React components for Stripe
@stripe/stripe-js	Loads Stripe in browser

Stripe Setup

Create Stripe Server Instance

Create:

lib/stripe/server.ts

import Stripe from "stripe";

export const stripe = new Stripe(
  process.env.STRIPE_SECRET_KEY!,
  {
    apiVersion: "2026-04-22.dahlia",
  }
);

What Does This Do?

This creates a Stripe instance on the server side.

We'll use this object to:

Create Payment Intents
Handle webhooks
Access Stripe APIs securely

Create Stripe Client Instance

Create:

lib/stripe/client.ts

import { loadStripe } from "@stripe/stripe-js";

export const stripePromise = loadStripe(
  process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!
);

Why Do We Need This?

Stripe Payment Element runs in the browser.

This file loads Stripe safely on the client side.

Get Stripe API Keys

Go to the Stripe Dashboard:

Open the sidebar
Enable Test Mode

This gives you test keys instead of live keys.

You should use:

sk_test_
pk_test_

while developing locally.

Create Environment Variables

Create:

.env.local

STRIPE_SECRET_KEY=sk_test_xxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
NEXT_PUBLIC_APP_URL=http://localhost:3000

Understanding Environment Variables

Why NEXT_PUBLIC_?

Variables that start with NEXT_PUBLIC_ can be accessed on the client side.

This is safe for publishable Stripe keys.

Important:

Never expose your Stripe Secret Key to the client side.

Create Package Constants

Create:

lib/constants/package-tier.ts

export const PKG_TIER = {
  HARMONY: "harmony",
  LEGACY: "legacy",
} as const;

export const PACKAGES = {
  harmony: {
    id: "harmony",
    name: "Harmony",
    price: 399,
  },

  legacy: {
    id: "legacy",
    name: "Legacy",
    price: 599,
  },
};

export type PkgTierType = keyof typeof PACKAGES;

Why Store Package Data in One File?

This is a very important practice.

Instead of hardcoding package names and prices everywhere in your app, we keep everything in one place.

Benefits:

Easier maintenance
Easier updates
Less bugs
Better scalability

For example:

If later you rename:

Harmony → Premium

You only update one file.

Create Checkout Form

Create:

src/components/checkout-form.tsx

"use client";

import {
  PaymentElement,
  useElements,
  useStripe,
} from "@stripe/react-stripe-js";

import { useState, SubmitEvent } from "react";

export function CheckoutForm() {
  const stripe = useStripe();
  const elements = useElements();

  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handleSubmit = async (e: SubmitEvent<HTMLFormElement>) => {
    e.preventDefault();

    if (!stripe || !elements) return;

    setLoading(true);
    setError(null);

    const result = await stripe.confirmPayment({
      elements,
      confirmParams: {
        return_url:
          `${process.env.NEXT_PUBLIC_APP_URL}/checkout/success`,
      },
      redirect: "always",
    });

    if (result.error) {
      setError(result.error.message || "Payment failed");
      setLoading(false);
      return;
    }

    setLoading(false);
  };

  return (
    <form
      onSubmit={handleSubmit}
      className="space-y-4"
    >
      <PaymentElement />

      {error && (
        <div className="text-red-500 text-sm">
          {error}
        </div>
      )}

      <button
        type="submit"
        disabled={!stripe || loading}
        className="w-full rounded-md bg-black px-4 py-3 text-white disabled:opacity-50"
      >
        {loading ? "Processing..." : "Pay Now"}
      </button>
    </form>
  );
}

Understanding the Checkout Form

What is PaymentElement?

PaymentElement is Stripe's prebuilt checkout UI.

It automatically supports:

Cards
Apple Pay
Google Pay
Bank payments
Many regional payment methods

depending on your Stripe settings.

Important:
Some methods may not work in development mode.

What Happens on Form Submit?

When the user clicks the Pay button:

stripe.confirmPayment()

Stripe:

Validates card details
Processes payment
Handles authentication
Redirects user after success

Why Use return_url?

After payment, Stripe redirects the user to your payment success page.

Example:

/checkout/success

Create Stripe Provider

Create:

src/components/stripe-provider.tsx

import { Elements } from "@stripe/react-stripe-js";
import { stripePromise } from "@/lib/stripe/client";
import { ReactNode } from "react";

interface Props {
  children: ReactNode;
  clientSecret: string;
}

export function StripeProvider({
  children,
  clientSecret,
}: Props) {
  return (
    <Elements
      stripe={stripePromise}
      options={{
        clientSecret,
        appearance: {
          theme: "night",
        },
      }}
    >
      {children}
    </Elements>
  );
}

Customizing Stripe Appearance

You can customize:

Theme
Colors
Fonts
Border radius
Input styles

using the appearance object.

For more appearance options please visit Stripe Appearance API Docs

Create Payment Intent Server Action

Create:

lib/actions/create-payment-intent.ts

"use server";

export async function createPaymentIntent() {}

What Are Server Actions?

Before creating the payment intent, let's quickly understand Server Actions.

Server Actions are asynchronous functions that run on the server.

They help us:

Handle forms
Access databases
Call APIs securely
Mutate data

without creating traditional API routes.

Create Package List Component

Create:

src/components/package-list.tsx

"use client";

import { useActionState } from "react";

import { CheckoutForm } from "@/components/checkout-form";
import { StripeProvider } from "@/components/stripe-provider";

import { createPaymentIntent } from "@/lib/actions/create-payment-intent";

import { PACKAGES } from "@/lib/constants/package-tier";

export default function PackageList() {
  const [state, action, isPending] = useActionState(createPaymentIntent, { clientSecret: "", error: "" });

  return (
    <div>
      <form action={action}>
        {Object.values(PACKAGES).map(
          (pkg) => (
            <button
              key={pkg.id}
              type="submit"
              name="packageTier"
              value={pkg.id}
              disabled={
                isPending ||
                !!state?.clientSecret
              }
            >
              {pkg.name}
            </button>
          )
        )}
      </form>

      {state?.error && (
        <div>{state.error}</div>
      )}

      {state?.clientSecret && (
        <StripeProvider
          clientSecret={
            state.clientSecret
          }
        >
          <CheckoutForm />
        </StripeProvider>
      )}
    </div>
  );
}

Important: The name attribute is very important inside form on button element. Later we’ll access value from form data in our server action using this name attribute.

Understanding useActionState

useActionState():

connects forms with Server Actions
manages loading state
handles server responses

It accepts:

your action function
initial state

And returns:

current state
form action
pending state

Why Use "use client"?

Hooks only work in client components.

Since we're using:

useActionState()

we must add:

"use client"

Add Component to Homepage

import PackageList from "@/components/package-list";

export default function Page() {
  return <PackageList />;
}

Update Server Action

Now let's add the actual logic.

"use server";

import { stripe } from "@/lib/stripe/server";

import {
  PACKAGES,
  PkgTierType,
} from "../constants/package-tier";

export async function createPaymentIntent(
  prev: unknown,
  formData: FormData
): Promise<{
  clientSecret?: string;
  error?: string;
}> {
  try {
    const pkgTier =
      formData.get("packageTier");

    if (
      typeof pkgTier !== "string" ||
      !(pkgTier in PACKAGES)
    ) {
      return {
        error: "Invalid package tier",
      };
    }

    const pkg =
      PACKAGES[pkgTier as PkgTierType];

    const paymentIntent =
      await stripe.paymentIntents.create({
        amount: pkg.price * 100,

        currency: "usd",

        automatic_payment_methods: {
          enabled: true,
        },

        metadata: {
          packageTier: pkgTier,
        },
      });

    if (!paymentIntent.client_secret) {
      return {
        error:
          "Failed to create payment intent",
      };
    }

    return {
      clientSecret:
        paymentIntent.client_secret,
    };
  } catch (err) {
    return {
      error:
        err instanceof Error
          ? err.message
          : "Something went wrong",
    };
  }
}

Now let’s understand this action:

Firstly it has two parameters prev we’re not using this, our default state this paramater is provided by useActionState and second formData this paramater is provided by form element.

Now we’ll use that same name attribute packageTier we provided inside form element to get the package that user has clicked on. After validation we’ll create stripe payment intent now let’s understand stripe object.

Understanding Payment Intents

A Payment Intent represents a payment session in Stripe.

It tracks:

Payment amount
Currency
Payment status
Payment method
Authentication steps

Why Multiply Amount by 100?

Stripe expects amounts in cents.

Price	Stripe Amount
$10	1000
$399	39900

What is Metadata?

Metadata allows us to attach extra information to payments.

Example:

metadata: {
  packageTier: pkgTier
}

This becomes very useful later inside webhooks.

What Does automatic_payment_methods Do?

When enabled:

automatic_payment_methods: {
  enabled: true
}

Stripe automatically shows compatible payment methods.

This is the easiest and recommended approach.

Stripe Webhooks

Now the checkout works.

But we still need a secure way to confirm payments.

This is where webhooks come in.

What Are Stripe Webhooks?

Stripe webhooks are server endpoints that Stripe calls automatically whenever events happen.

Examples:

Payment succeeded
Payment failed
Subscription renewed

Webhooks are extremely important because:

Never trust frontend payment success alone.

Always verify payments on the server.

Create Webhook Route

Create:

src/app/api/webhook/route.ts

Configure Webhook in Stripe Dashboard

From Stripe Dashboard:

Developers → Webhooks → Add Destination

Select Events

Choose:

payment_intent.succeeded
payment_intent.payment_failed

Add Webhook URL

Example:

https://yourdomain.com/api/webhook

Localhost Webhook Problem

Stripe cannot access localhost directly.

For local development, use:

ngrok
Stripe CLI

to expose your localhost server publicly. For more info please check:

Add Webhook Secret

Copy the signing secret.

Add to .env.local:

STRIPE_WEBHOOK_SECRET=whsec_xxx

Create Webhook Route Logic

export async function POST(req: Request) {
    try {
        const payload = await req.text();
        const sig = (await headers()).get('stripe-signature')!;
        let event;
        try {
            event = stripe.webhooks.constructEvent(payload, sig, endpointSecret);
        } catch (err) {
            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
            return NextResponse.json(
                { message: `Webhook Error: ${errorMessage}` },
                { status: 400 }
            );
        }
        switch (event.type) {
            case "payment_intent.succeeded": {
                const paymentIntent = event.data.object as Stripe.PaymentIntent;

                if (paymentIntent.status !== 'succeeded') {
                    return NextResponse.json(
                        { message: 'Payment not completed' },
                        { status: 200 }
                    );
                }

                const pkgTier = paymentIntent.metadata?.packageTier;
                console.log("pkgTier", pkgTier);
                console.log("Payment success", paymentIntent.id);

                // Update database
                // Mark order paid
                // Send email
                // Trigger fulfillment

                break;
            }

            case "payment_intent.payment_failed": {
                console.log("Payment failed");
                break;
            }
        }

        return NextResponse.json({ message: 'Received' }, { status: 200 });

    } catch (err) {
        const error = err instanceof Error ? err.message : 'Something went wrong';
        console.error('error', error);

        return NextResponse.json(
            { error },
            { status: 500 }
        );
    }
}

Understanding the Webhook

Why Use req.text()?

Stripe requires the raw request body for signature verification.

In App Router:

await req.text()

works correctly without additional body parser configuration.

What Does constructEvent Do?

stripe.webhooks.constructEvent()

This verifies that the webhook request actually came from Stripe.

Without this verification, anyone could fake webhook requests.

Important Production Tip

Stripe may send the same webhook event multiple times.

Always:

Store Stripe event IDs
Ignore duplicate events

This prevents duplicate orders or emails.

Why Webhooks Matter

Your webhook is the safest place to:

Mark orders as paid
Save payment records
Send confirmation emails
Start product fulfillment

Never trust only frontend success pages.

Why Stripe expects 200

Notice in each return statement status is mostly 200.

When Stripe sends a webhook event, it waits for your server response.

200–299 → Stripe marks event as delivered successfully

400–499 → Stripe assumes your request is invalid

500+ → Stripe assumes your server failed

If Stripe does NOT get a 2xx response, it retries the webhook multiple times automatically.

Testing Stripe Payments

Use these test cards.

Successful Payment

4242 4242 4242 4242

Declined Card

4000 0000 0000 0002

3D Secure

4000 0025 0000 3155

Production Best Practices

Best Practice	Why It Matters
Use Webhooks	Never trust client-side payment success
Validate Metadata	Prevent invalid purchases
Store Event IDs	Avoid duplicate processing
Use HTTPS	Required for secure payments
Keep Secret Keys Server Side	Prevent security leaks

Final Thoughts

Stripe Payment Element is one of the best ways to build modern checkout flows according to your website theme in Next.js applications.

You now know how to:

Create Payment Intents
Use Stripe Payment Element
Handle payments
Use Server Actions
Verify Stripe webhooks
Build a production-ready checkout flow

This setup works great for:

SaaS products
Digital products
Agencies
AI tools
Membership websites

I hope this guide helps you build your own Stripe integration successfully.

Useful Resources

React useActionState Docs: https://react.dev/reference/react/useActionState
Next.js Server Actions Docs: https://nextjs.org/docs/app/getting-started/mutating-data
Stripe Payment Element Docs: https://docs.stripe.com/payments/payment-element

Continue Learning

If you'd like to learn more about stripe, check out these tutorials:

DEV Community: Syed Muhammad Ali

Complete MDX Blog Setup with next-mdx-remote and Next.js 16 (2026 Beginner Guide)

Why MDXRemote Instead of @next/mdx?

What We're Building

Step 1: Install Dependencies

Step 2: Configure next.config.mjs (Optional)

Step 3: Create the Content Folder

Step 4: Build the Data Layer (lib/posts.ts)

Step 5: Create Custom MDX Components

Step 6: Build the Dynamic Blog Route

Step 7: Add JSON-LD Structured Data (Optional, but Great for SEO)

Step 8: Update global.css

Testing Your Setup

Bonus: Dynamic Open Graph Images

Frequently Asked Questions

Can I use next-mdx-remote with the Pages Router?

Do I need @next/mdx if I'm already using MDXRemote?

How do I add images inside my MDX posts?

Why is my code block not syntax highlighted?

Can I fetch MDX content from a CMS instead of the filesystem?

Wrapping Up

Helpful Resources

Related Guides

Try These Free Developer Tools

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

Best Hosting Platforms for Next.js in 2026: Who Actually Handles ISR & PPR Correctly?

The Distinction Nobody Explains: Functional vs. Performance Fidelity

Why ISR and PPR Are Hard for Non-Vercel Platforms

Platform-by-Platform Breakdown

Vercel

Netlify

Cloudflare Workers (via OpenNext)

AWS Amplify

Railway & Render (Container/Docker Platforms)

Self-Hosting (Docker, VPS, Fly.io, Cloud Run)

Quick Comparison

So, Which One Should You Actually Use?

Frequently Asked Questions

Does "supports ISR" mean it works exactly like Vercel?

Is PPR available everywhere yet?

Will the new Adapter API make all platforms equal eventually?

Is self-hosting actually cheaper?

Can I switch platforms later if I start with Vercel?

Platform Migration Difficulty

Wrapping Up

Useful Resources

Continue Learning

Next.js Rendering Strategies Explained: SSR, SSG, CSR, ISR & Cache Components (2026)

Why This Matters

What Is SSR (Server-Side Rendering)?

What Is SSG (Static Site Generation)?

What Is CSR (Client-Side Rendering)?

What Is ISR (Incremental Static Regeneration)?

What Are Cache Components (and PPR)?

Step 1: Enable Cache Components

Step 2: Mark cacheable parts with "use cache"

Quick Comparison

Frequently Asked Questions

Do I have to pick one strategy for my whole app?

Step 8: Update `global.css`

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

Step 2: Mark cacheable parts with `"use cache"`