DEV Community: Aon infotech

Dynamic SEO Metadata in Next.js with generateMetadata() — Per-Page Titles, Descriptions, and OG Images

Aon infotech — Tue, 21 Jul 2026 07:35:57 +0000

Static metadata in Next.js is straightforward — export a metadata object from a route file. Dynamic metadata, where the title and description depend on the page content, requires generateMetadata(). This covers the complete pattern: per-page titles and descriptions, Open Graph and Twitter card generation, and dynamic OG images.

These patterns form the SEO infrastructure for content-heavy sites — the approach used across all 60+ blog posts at content generation pipeline.

Static Metadata

For static routes, export a metadata object:

// app/about/page.tsx
import { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'About Us',
  description: 'Learn about our team and mission.',
  openGraph: {
    title: 'About Us',
    description: 'Learn about our team and mission.',
    url: 'https://example.com/about',
  },
};

export default function AboutPage() {
  return <main>About content</main>;
}

Dynamic Metadata with generateMetadata()

For dynamic routes where title and description depend on fetched data:

// app/blog/[slug]/page.tsx
import { Metadata } from 'next';
import { notFound } from 'next/navigation';

type Props = {
  params: { slug: string };
};

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const post = await getPost(params.slug);

  if (!post) {
    return {
      title: 'Post Not Found',
    };
  }

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      url: `https://example.com/blog/${params.slug}`,
      type: 'article',
      publishedTime: post.publishedAt,
      authors: [post.authorName],
    },
    twitter: {
      card: 'summary_large_image',
      title: post.title,
      description: post.excerpt,
    },
  };
}

export default async function BlogPost({ params }: Props) {
  const post = await getPost(params.slug);
  if (!post) notFound();

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

Next.js deduplicates the getPost call — generateMetadata and the page component can both call it without making two network requests.

Open Graph Images

The openGraph.images field accepts URLs for static OG images or the Next.js image generation API for dynamic ones.

Static OG images — same image for every page of a type:

export const metadata: Metadata = {
  openGraph: {
    images: [
      {
        url: '/og/blog-default.jpg',
        width: 1200,
        height: 630,
        alt: 'Blog post default image',
      },
    ],
  },
};

Dynamic OG images — unique image for each post using the ImageResponse API:

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

export const runtime = 'edge';
export const size = { width: 1200, height: 630 };
export const contentType = 'image/png';

type Props = {
  params: { slug: string };
};

export default async function OGImage({ params }: Props) {
  const post = await getPost(params.slug);

  return new ImageResponse(
    (
      <div
        style={{
          background: '#0f172a',
          width: '100%',
          height: '100%',
          display: 'flex',
          flexDirection: 'column',
          alignItems: 'flex-start',
          justifyContent: 'flex-end',
          padding: '64px',
          fontFamily: 'system-ui',
        }}
      >
        <p
          style={{
            fontSize: '24px',
            color: '#94a3b8',
            margin: '0 0 16px',
          }}
        >
          {post?.category ?? 'Blog'}
        </p>
        <h1
          style={{
            fontSize: '64px',
            fontWeight: 700,
            color: '#f8fafc',
            margin: '0',
            lineHeight: 1.1,
            maxWidth: '900px',
          }}
        >
          {post?.title ?? 'Untitled Post'}
        </h1>
      </div>
    ),
    { ...size }
  );
}

Place this file at app/blog/[slug]/opengraph-image.tsx. Next.js automatically serves it at /blog/[slug]/opengraph-image and links it in the page's metadata.

Metadata Inheritance and the Layout Hierarchy

generateMetadata in nested layouts merges with parent metadata. Define defaults at the root layout level:

// app/layout.tsx
export const metadata: Metadata = {
  title: {
    default: 'My Site',
    template: '%s | My Site',
  },
  description: 'Default site description',
  openGraph: {
    siteName: 'My Site',
    type: 'website',
  },
};

With template: '%s | My Site', a page that exports title: 'Blog Post Title' renders as Blog Post Title | My Site in the browser tab. The default value applies when no child provides a title.

Structured Data for Blog Posts

Include JSON-LD in page components for rich results:

// app/blog/[slug]/page.tsx
export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);

  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'BlogPosting',
    headline: post.title,
    description: post.excerpt,
    datePublished: post.publishedAt,
    dateModified: post.updatedAt,
    author: {
      '@type': 'Person',
      name: post.authorName,
    },
    image: post.coverImage,
    url: `https://example.com/blog/${params.slug}`,
  };

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
      />
      <article>
        {/* post content */}
      </article>
    </>
  );
}

Canonical URLs

Set canonical URLs explicitly to avoid duplicate content issues, especially for paginated content or content syndicated from external sources:

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const post = await getPost(params.slug);

  return {
    title: post.title,
    alternates: {
      canonical: `https://example.com/blog/${params.slug}`,
    },
  };
}

This is important for blogs where the same content might be accessible at multiple URLs (with/without trailing slash, different query parameters, etc.).

Robots Meta

Control indexing per-page:

export const metadata: Metadata = {
  robots: {
    index: true,
    follow: true,
    'max-snippet': -1,
    'max-image-preview': 'large',
    'max-video-preview': -1,
  },
};

For pages you don't want indexed:

export const metadata: Metadata = {
  robots: {
    index: false,
    follow: false,
  },
};

Summary

Dynamic metadata flows from generateMetadata() returning a Metadata object with per-page title, description, OG, and Twitter values. OG images can be static (a single image per route type) or dynamic using the ImageResponse API in a colocated opengraph-image.tsx file. Title templates in the root layout handle the global brand suffix. JSON-LD and canonical URLs complete the SEO infrastructure.

Verifying Metadata in Production

After deploying, verify metadata appears correctly:

Browser DevTools: Right-click → View Page Source → search for <meta name="description", <meta property="og:title".

Open Graph Debugger: Use developers.facebook.com/tools/debug to preview how a URL appears when shared. Clears Facebook's cache when you submit.

Twitter Card Validator: cards-dev.twitter.com/validator previews Twitter card appearance.

Google Rich Results Test: search.google.com/test/rich-results validates structured data and previews rich results eligibility.

These tools catch issues before they affect actual shares and search appearances — a mistyped property name or missing field doesn't surface as an error in development but shows as missing data when someone shares the URL.

Metadata Gotchas

Title length. Google typically shows up to 60 characters. Titles longer than this get truncated in search results. With the template suffix adding | Site Name, the base title needs to be even shorter.

Description length. Meta descriptions at 150-160 characters display fully in search results. Longer descriptions get cut off.

OG image dimensions. 1200 × 630 pixels is the standard for most social platforms. Images outside this ratio display incorrectly on some platforms — the ImageResponse API defaults to these dimensions if you don't specify otherwise.

Missing fallbacks. generateMetadata can return partial metadata — if a post isn't found, returning { title: 'Not Found' } is fine. The page's notFound() call handles the 404 response separately from the metadata.

Data deduplication. Next.js automatically deduplicates fetch calls with the same URL and options — generateMetadata and the page component can both call getPost(slug) without making two database/network requests. This requires using fetch with Next.js's cache rather than a direct database call, or implementing your own deduplication with React's cache() function.

Using cache() for Data Deduplication Without fetch

For direct database queries that don't go through fetch, use React's cache() to deduplicate:

// lib/posts.ts
import { cache } from 'react';

export const getPost = cache(async (slug: string) => {
  // Direct database query — no fetch involved
  return db.posts.findUnique({ where: { slug } });
});

Wrap database functions in cache() and both generateMetadata and the page component call the same cached function. The database query runs once per request regardless of how many places call getPost(slug).

ISR and On-Demand Revalidation in Next.js App Router — Keeping Static Pages Fresh

Aon infotech — Mon, 20 Jul 2026 07:46:21 +0000

Static pages are fast, but they go stale. Incremental Static Regeneration (ISR) solves this by regenerating pages in the background after a set time interval. On-demand revalidation goes further — triggering regeneration immediately when data changes, rather than waiting for the time interval to expire.

Here's how both work in the App Router, with patterns from the content pipeline at AI image generation pipeline.

How Caching Works in App Router

Server Components in App Router are cached by default. The fetch cache determines how long a page stays fresh before Next.js regenerates it.

// Cached indefinitely (static) — the default
const data = await fetch('https://api.example.com/posts');

// Cached for 60 seconds, then regenerated
const data = await fetch('https://api.example.com/posts', {
  next: { revalidate: 60 }
});

// Never cached — always fresh (like getServerSideProps)
const data = await fetch('https://api.example.com/posts', {
  cache: 'no-store'
});

The revalidate value at the fetch level sets ISR for that data. Next.js serves cached pages until the revalidation time expires, then regenerates in the background on the next request.

Setting Revalidation at the Route Level

You can also set revalidation for an entire route using the exported revalidate constant:

// app/blog/[slug]/page.tsx
export const revalidate = 3600; // Regenerate every hour

export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);
  return <Article post={post} />;
}

This applies to all fetches in the route unless individual fetches override it. The most restrictive value wins — if the route exports revalidate = 3600 but a fetch uses cache: 'no-store', that fetch bypasses caching.

Generating Static Params

For dynamic routes, generateStaticParams tells Next.js which paths to pre-render at build time:

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

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

export const revalidate = 3600;
export const dynamicParams = true; // Allow params not in generateStaticParams

export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);

  if (!post) {
    notFound();
  }

  return <Article post={post} />;
}

With dynamicParams = true (the default), requests for slugs not in generateStaticParams are rendered on-demand and then cached. Set dynamicParams = false to return 404 for any path not pre-generated.

On-Demand Revalidation

Time-based ISR regenerates on a schedule regardless of whether data has actually changed. On-demand revalidation triggers regeneration immediately when you know data has changed — more efficient and more responsive.

Two functions: revalidatePath and revalidateTag.

revalidatePath

Invalidates the cache for a specific route:

// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const secret = request.headers.get('x-revalidate-secret');

  if (secret !== process.env.REVALIDATE_SECRET) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const { path } = await request.json();
  revalidatePath(path);

  return NextResponse.json({ revalidated: true, path });
}

Call this from your CMS webhook when content is updated:

curl -X POST https://your-site.com/api/revalidate \
  -H "x-revalidate-secret: your-secret" \
  -H "Content-Type: application/json" \
  -d '{"path": "/blog/my-post-slug"}'

revalidateTag

More granular — tag fetches with labels and invalidate all tagged fetches at once:

// Tagging fetches
const post = await fetch(`https://api.example.com/posts/${slug}`, {
  next: { tags: ['post', `post-${slug}`] }
});

const allPosts = await fetch('https://api.example.com/posts', {
  next: { tags: ['posts-list'] }
});

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache';

export async function POST(request: NextRequest) {
  const { tag } = await request.json();
  revalidateTag(tag);
  return NextResponse.json({ revalidated: true });
}

When a post is updated in your CMS, call the revalidation endpoint with the specific post tag. Only that post's data is invalidated — the posts list and other posts remain cached.

Combining ISR and On-Demand Revalidation

The pattern that works best for content sites: time-based ISR as a fallback, on-demand revalidation for immediate updates.

// app/blog/[slug]/page.tsx
export const revalidate = 86400; // Fallback: regenerate daily

// Fetches tagged for on-demand invalidation
async function getPost(slug: string) {
  const res = await fetch(`https://api.example.com/posts/${slug}`, {
    next: {
      revalidate: 86400,
      tags: [`post-${slug}`, 'posts']
    }
  });

  return res.json();
}

Daily ISR ensures pages stay fresh even if the webhook fails. On-demand revalidation ensures immediate updates when you need them.

Testing Cache Behavior

Next.js provides the X-Nextjs-Cache response header:

HIT — served from cache
MISS — cache miss, generated fresh
STALE — served stale while regenerating in background

curl -I https://your-site.com/blog/post-slug | grep x-nextjs-cache
# x-nextjs-cache: HIT

In development (next dev), caching is disabled by default so you always get fresh data. To test ISR behavior, build and run locally with next build && next start.

When to Use Each Approach

Static (no revalidate): Pages that never change. Legal documents, about pages, marketing pages with manual deploy updates.

Time-based ISR: Content that changes on a predictable schedule. News sites (hourly), ecommerce inventory (15-minute intervals), dashboards.

On-demand revalidation: CMS-driven content where you want immediate updates on publish without waiting for an interval. Blog posts, product pages, anything with a webhook-capable CMS.

cache: 'no-store': User-specific data, real-time data, content that must always be fresh. Use sparingly — each request hits the origin.

Revalidation in Server Actions

Server Actions can trigger revalidation directly after mutations — no separate API route needed:

// app/actions/posts.ts
'use server';

import { revalidatePath, revalidateTag } from 'next/cache';

export async function updatePost(id: string, data: PostUpdateData) {
  await db.posts.update({ where: { id }, data });

  // Invalidate the specific post and the posts list
  revalidateTag(`post-${id}`);
  revalidateTag('posts-list');
  revalidatePath(`/blog/${data.slug}`);
}

This is the cleanest pattern for CMS-style applications built entirely in Next.js — the mutation and revalidation happen in the same Server Action, no webhook configuration needed.

Summary

ISR in App Router: set revalidate on fetch calls or export it as a route constant. Time-based ISR regenerates on a schedule; on-demand revalidation (revalidatePath, revalidateTag) triggers immediate regeneration when data changes.

The combination — time-based ISR as fallback plus on-demand revalidation from CMS webhooks or Server Actions — gives you both immediate updates and resilience against missed webhooks.

Handling Cache Misses Gracefully

When ISR generates a page for the first time (cache miss), there's a brief period while the page is being generated. Configure a loading UI to prevent users from seeing blank content:

// app/blog/[slug]/loading.tsx
export default function PostLoading() {
  return (
    <div className="max-w-3xl mx-auto px-4 py-12">
      <div className="h-8 bg-neutral-100 rounded w-2/3 animate-pulse mb-4" />
      <div className="h-4 bg-neutral-100 rounded w-full animate-pulse mb-2" />
      <div className="h-4 bg-neutral-100 rounded w-5/6 animate-pulse mb-2" />
      <div className="h-4 bg-neutral-100 rounded w-4/6 animate-pulse" />
    </div>
  );
}

The loading UI shows during the initial generation of uncached paths. Subsequent requests serve from cache instantly.

Debugging Stale Content

If content isn't updating when expected, check these in order:

Verify the revalidate value — console.log the revalidate export and confirm it's reaching the route
Check the cache header — X-Nextjs-Cache: HIT means you're seeing cached content
Verify webhook delivery — if using on-demand revalidation, check your CMS webhook logs for successful delivery
Check the secret — webhook revalidation with a wrong secret returns 401 silently
Test with next start — ISR doesn't work in next dev; always test with a production build locally

Most ISR issues are either the route not opting into revalidation, or on-demand webhooks not being delivered correctly.

Next.js Server Actions — Form Handling Without API Routes

Aon infotech — Mon, 20 Jul 2026 07:43:15 +0000

Server Actions let you run server-side code directly from React components — no separate API route file, no fetch call, no request/response boilerplate. A form submission can call a server function directly, and the result updates the UI. This is the pattern that replaces the classic POST /api/submit for most form handling.

Here's the complete pattern, including progressive enhancement, error handling, and the loading state management that makes forms feel responsive — the approach used for content management on website image generation patterns.

Defining a Server Action

Server Actions are async functions marked with 'use server'. They can be defined in a separate file or inline in a Server Component.

// app/actions/contact.ts
'use server';

import { revalidatePath } from 'next/cache';

type ContactFormData = {
  name: string;
  email: string;
  message: string;
};

type ActionResult = {
  success: boolean;
  error?: string;
};

export async function submitContact(
  formData: FormData
): Promise<ActionResult> {
  const name = formData.get('name') as string;
  const email = formData.get('email') as string;
  const message = formData.get('message') as string;

  // Validate
  if (!name || !email || !message) {
    return { success: false, error: 'All fields are required' };
  }

  if (!email.includes('@')) {
    return { success: false, error: 'Invalid email address' };
  }

  try {
    await saveToDatabase({ name, email, message });
    revalidatePath('/contact');
    return { success: true };
  } catch (error) {
    return { success: false, error: 'Submission failed. Please try again.' };
  }
}

The 'use server' directive marks this as a Server Action — Next.js handles the network boundary automatically. The function receives FormData and returns a result.

Basic Form With Server Action

The simplest usage: attach the action directly to a form's action prop.

// app/contact/page.tsx
import { submitContact } from '@/app/actions/contact';

export default function ContactPage() {
  return (
    <form action={submitContact} className="space-y-4">
      <div>
        <label htmlFor="name">Name</label>
        <input
          id="name"
          name="name"
          type="text"
          required
          className="block w-full border rounded px-3 py-2"
        />
      </div>
      <div>
        <label htmlFor="email">Email</label>
        <input
          id="email"
          name="email"
          type="email"
          required
          className="block w-full border rounded px-3 py-2"
        />
      </div>
      <div>
        <label htmlFor="message">Message</label>
        <textarea
          id="message"
          name="message"
          rows={4}
          required
          className="block w-full border rounded px-3 py-2"
        />
      </div>
      <button type="submit">Send Message</button>
    </form>
  );
}

This works — and it works without JavaScript enabled, because it's a standard HTML form submission. This is progressive enhancement built in.

Adding Loading State and Feedback With useFormState and useFormStatus

The basic form works but doesn't give users feedback. useFormState captures the action's return value; useFormStatus provides the pending state.

// app/contact/ContactForm.tsx
'use client';

import { useFormState, useFormStatus } from 'react-dom';
import { submitContact } from '@/app/actions/contact';

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      className="px-4 py-2 bg-blue-600 text-white rounded disabled:opacity-50"
    >
      {pending ? 'Sending...' : 'Send Message'}
    </button>
  );
}

const initialState = { success: false, error: undefined };

export function ContactForm() {
  const [state, formAction] = useFormState(submitContact, initialState);

  if (state.success) {
    return (
      <div className="p-4 bg-green-50 text-green-800 rounded">
        Message sent successfully. We'll be in touch.
      </div>
    );
  }

  return (
    <form action={formAction} className="space-y-4">
      {state.error && (
        <div className="p-3 bg-red-50 text-red-700 rounded text-sm">
          {state.error}
        </div>
      )}

      <div>
        <label htmlFor="name" className="block text-sm font-medium mb-1">
          Name
        </label>
        <input
          id="name"
          name="name"
          type="text"
          required
          className="block w-full border rounded px-3 py-2"
        />
      </div>

      <div>
        <label htmlFor="email" className="block text-sm font-medium mb-1">
          Email
        </label>
        <input
          id="email"
          name="email"
          type="email"
          required
          className="block w-full border rounded px-3 py-2"
        />
      </div>

      <div>
        <label htmlFor="message" className="block text-sm font-medium mb-1">
          Message
        </label>
        <textarea
          id="message"
          name="message"
          rows={4}
          required
          className="block w-full border rounded px-3 py-2"
        />
      </div>

      <SubmitButton />
    </form>
  );
}

Note that SubmitButton is a separate component — useFormStatus only works inside a form element, not in the component that renders the form. Moving it to a child component solves this.

Server Actions With Zod Validation

For robust validation, combine Server Actions with Zod:

// app/actions/contact.ts
'use server';

import { z } from 'zod';

const ContactSchema = z.object({
  name: z.string().min(1, 'Name is required').max(100),
  email: z.string().email('Invalid email address'),
  message: z.string().min(10, 'Message must be at least 10 characters').max(1000),
});

type FormState = {
  success: boolean;
  error?: string;
  fieldErrors?: Record<string, string[]>;
};

export async function submitContact(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  const raw = {
    name: formData.get('name'),
    email: formData.get('email'),
    message: formData.get('message'),
  };

  const result = ContactSchema.safeParse(raw);

  if (!result.success) {
    return {
      success: false,
      fieldErrors: result.error.flatten().fieldErrors,
    };
  }

  try {
    await saveToDatabase(result.data);
    return { success: true };
  } catch {
    return { success: false, error: 'Something went wrong. Please try again.' };
  }
}

The fieldErrors object maps field names to arrays of error messages — useful for displaying inline validation errors next to each field.

Mutations Beyond Forms

Server Actions aren't limited to forms. You can call them from event handlers in Client Components:

'use client';

import { deleteItem } from '@/app/actions/items';

export function DeleteButton({ id }: { id: string }) {
  return (
    <button
      onClick={async () => {
        await deleteItem(id);
      }}
      className="text-red-600 hover:text-red-800"
    >
      Delete
    </button>
  );
}

And the action:

// app/actions/items.ts
'use server';

import { revalidatePath } from 'next/cache';

export async function deleteItem(id: string) {
  await db.items.delete({ where: { id } });
  revalidatePath('/items');
}

revalidatePath tells Next.js to invalidate the cached data for a route after a mutation — so the list updates without a full page reload.

When to Use Server Actions vs API Routes

Server Actions are better for: form submissions, mutations triggered by user interaction, operations that need to revalidate cached data, and when you want progressive enhancement (works without JS).

API Routes are better for: webhook handlers, publicly accessible endpoints that external services call, streaming responses, and when you need fine-grained control over the HTTP response (status codes, headers, streaming).

The mental model: Server Actions are for your own UI. API Routes are for the outside world or situations where HTTP semantics matter.

Summary

Server Actions simplify the form handling pattern significantly. Instead of form → fetch('/api/submit') → handler → response → update state, you get form action → server function → return result. Less code, built-in progressive enhancement, and revalidatePath for cache invalidation after mutations.

The key files: the action function (marked 'use server'), the form component using useFormState for result capture, and a SubmitButton child component for useFormStatus access. That pattern covers the vast majority of form handling in Next.js applications.

Optimistic Updates With useOptimistic

For UI that should feel instant, useOptimistic lets you show the expected result before the server confirms it:

'use client';

import { useOptimistic } from 'react';
import { toggleLike } from '@/app/actions/likes';

type Post = { id: string; liked: boolean; likeCount: number };

export function LikeButton({ post }: { post: Post }) {
  const [optimisticPost, setOptimisticPost] = useOptimistic(
    post,
    (state, liked: boolean) => ({
      ...state,
      liked,
      likeCount: liked ? state.likeCount + 1 : state.likeCount - 1,
    })
  );

  const handleLike = async () => {
    setOptimisticPost(!optimisticPost.liked);
    await toggleLike(post.id);
  };

  return (
    <button onClick={handleLike} className="flex items-center gap-1">
      <span>{optimisticPost.liked ? '❤️' : '🤍'}</span>
      <span>{optimisticPost.likeCount}</span>
    </button>
  );
}

The UI updates immediately on click. If the server action fails, the optimistic state reverts automatically. For interactions where users expect instant feedback, this pattern eliminates the perception of latency.

Next.js Middleware — Redirects, Auth Guards, and A/B Testing at the Edge

Aon infotech — Sat, 18 Jul 2026 11:39:43 +0000

Middleware in Next.js runs before a request is completed — at the edge, before the page renders, before your API route executes. This makes it the right place for logic that needs to run on every request: authentication checks, redirects, geo-based routing, and A/B testing.

Here's the complete picture of what middleware is actually good for, with patterns from the request flow at free AI product image generation.

How Middleware Works

Create middleware.ts at the root of your project (same level as app/). Next.js automatically runs it before matched routes.

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
  // Runs before every matched request
  return NextResponse.next(); // Continue to the route
}

export const config = {
  matcher: [
    // Which paths to run middleware on
    '/((?!_next/static|_next/image|favicon.ico).*)',
  ],
};

The config.matcher controls which paths trigger middleware. The pattern above runs on all paths except Next.js internals. Be specific here — middleware runs at the edge on every request, so unintentionally broad matchers create unnecessary latency.

Auth Guards — Protecting Routes

The most common middleware use case: redirect unauthenticated users away from protected routes.

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

const PROTECTED_ROUTES = ['/dashboard', '/account', '/settings'];
const LOGIN_PAGE = '/login';

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  const isProtectedRoute = PROTECTED_ROUTES.some(route => 
    pathname.startsWith(route)
  );

  if (!isProtectedRoute) {
    return NextResponse.next();
  }

  // Check for auth token in cookies
  const token = request.cookies.get('auth-token')?.value;

  if (!token) {
    const loginUrl = new URL(LOGIN_PAGE, request.url);
    loginUrl.searchParams.set('from', pathname);
    return NextResponse.redirect(loginUrl);
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/account/:path*', '/settings/:path*'],
};

The matcher config here is more specific — only runs on the protected route groups rather than every request. Faster and cleaner.

For JWT validation in middleware:

import { jwtVerify } from 'jose';

async function verifyToken(token: string): Promise<boolean> {
  try {
    const secret = new TextEncoder().encode(process.env.JWT_SECRET!);
    await jwtVerify(token, secret);
    return true;
  } catch {
    return false;
  }
}

export async function middleware(request: NextRequest) {
  const token = request.cookies.get('auth-token')?.value;

  if (!token || !(await verifyToken(token))) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  return NextResponse.next();
}

Note: keep token verification lightweight in middleware. Heavy database lookups don't belong here — middleware runs on every matched request and latency adds up.

Redirects at Scale

For simple redirects, next.config.js redirects are better. Middleware redirects make sense when the redirect logic is conditional or dynamic.

// middleware.ts — conditional redirect based on request properties
export function middleware(request: NextRequest) {
  const { pathname, searchParams } = request.nextUrl;

  // Redirect old URL patterns to new ones
  if (pathname.startsWith('/blog/post/')) {
    const slug = pathname.replace('/blog/post/', '');
    return NextResponse.redirect(
      new URL(`/blog/${slug}`, request.url),
      { status: 301 }
    );
  }

  // Redirect based on query param
  if (searchParams.get('ref') === 'old-campaign') {
    const url = request.nextUrl.clone();
    url.searchParams.delete('ref');
    url.searchParams.set('utm_source', 'old-campaign');
    return NextResponse.redirect(url);
  }

  return NextResponse.next();
}

Geo-Based Routing

Middleware receives geo data from the edge (Vercel populates this automatically):

export function middleware(request: NextRequest) {
  const country = request.geo?.country || 'US';

  // Redirect to localized version
  if (country === 'DE' && !request.nextUrl.pathname.startsWith('/de')) {
    return NextResponse.redirect(
      new URL(`/de${request.nextUrl.pathname}`, request.url)
    );
  }

  return NextResponse.next();
}

A/B Testing With Middleware

A/B testing at the edge — assigning users to buckets and serving different content — works well with middleware because it runs before the page renders.

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

const AB_COOKIE = 'ab-homepage';
const VARIANTS = ['control', 'variant-a'] as const;
type Variant = typeof VARIANTS[number];

function getVariant(): Variant {
  return Math.random() < 0.5 ? 'control' : 'variant-a';
}

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  if (pathname !== '/') {
    return NextResponse.next();
  }

  // Get or assign variant
  let variant = request.cookies.get(AB_COOKIE)?.value as Variant | undefined;

  if (!variant || !VARIANTS.includes(variant)) {
    variant = getVariant();
  }

  // Rewrite to variant page (URL stays the same for user)
  const response = NextResponse.rewrite(
    new URL(`/ab-variants/${variant}`, request.url)
  );

  // Set cookie so user stays in their bucket
  response.cookies.set(AB_COOKIE, variant, {
    maxAge: 60 * 60 * 24 * 30, // 30 days
    httpOnly: true,
    sameSite: 'lax',
  });

  return response;
}

export const config = {
  matcher: ['/'],
};

NextResponse.rewrite shows different content at the same URL — the user sees / but Next.js serves /ab-variants/variant-a. The cookie persists the assignment across sessions.

Adding Headers to Requests

Middleware can add headers that downstream components can read:

export function middleware(request: NextRequest) {
  const requestHeaders = new Headers(request.headers);

  // Add pathname as header for Server Components to read
  requestHeaders.set('x-pathname', request.nextUrl.pathname);

  // Add user segment based on cookie
  const segment = request.cookies.get('user-segment')?.value || 'unknown';
  requestHeaders.set('x-user-segment', segment);

  return NextResponse.next({
    request: { headers: requestHeaders },
  });
}

In a Server Component:

import { headers } from 'next/headers';

export default function Page() {
  const pathname = headers().get('x-pathname');
  const segment = headers().get('x-user-segment');

  return <div data-segment={segment}>Content for {pathname}</div>;
}

What Middleware Is Not For

Middleware runs at the edge with a limited runtime — no Node.js built-ins, no filesystem access, no database connections. It's for fast, lightweight request inspection and modification.

Heavy logic, database queries, and complex business logic belong in API routes or Server Components, not middleware. If you find middleware doing significant processing, that's a sign the logic belongs elsewhere.

The Matcher Config — Getting It Right

The matcher is worth getting right. Every path that matches runs middleware — unnecessary matches mean unnecessary latency.

export const config = {
  matcher: [
    // Match everything except static files and images
    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
};

For route group matching:

export const config = {
  matcher: [
    '/dashboard/:path*',    // matches /dashboard and /dashboard/anything
    '/api/:path*',          // matches all API routes
    '/((?!login|signup).*)', // matches everything except login and signup
  ],
};

Test your matchers before deploying. An overly broad matcher that runs middleware on image requests and static files adds latency to every asset load.

Summary

Middleware runs before matched routes at the edge. Use it for: auth guards that redirect unauthenticated users, conditional redirects based on request properties, geo-based routing, A/B testing with cookie-persisted assignments, and adding request headers for Server Components.

Keep it fast and lightweight — no database queries, no heavy computation. The edge runtime is intentionally limited to keep middleware responses fast.

Rate Limiting With Middleware

A common pattern: simple rate limiting at the edge before requests hit your API routes.

// middleware.ts — simple in-memory rate limiting (use Redis for production)
const rateLimitMap = new Map<string, { count: number; resetTime: number }>();

function isRateLimited(ip: string, limit = 10, windowMs = 60000): boolean {
  const now = Date.now();
  const record = rateLimitMap.get(ip);

  if (!record || now > record.resetTime) {
    rateLimitMap.set(ip, { count: 1, resetTime: now + windowMs });
    return false;
  }

  if (record.count >= limit) return true;

  record.count++;
  return false;
}

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/api/')) {
    const ip = request.ip || request.headers.get('x-forwarded-for') || 'unknown';

    if (isRateLimited(ip)) {
      return new NextResponse('Too Many Requests', { status: 429 });
    }
  }

  return NextResponse.next();
}

For production rate limiting across edge instances, use a shared store like Upstash Redis — in-memory Maps don't persist across serverless invocations.

Custom React Hooks — Extracting and Reusing Stateful Logic

Aon infotech — Fri, 17 Jul 2026 07:46:30 +0000

Custom hooks are one of React's most underused tools. They let you extract stateful logic from components into reusable functions — without adding components to your tree, without changing component hierarchy, and without any of the complexity of higher-order components or render props.

Here's the pattern, with practical examples from the kind of stateful logic that shows up repeatedly in real applications, including the generation state patterns used at pixova.io/blog/free-ai-architecture-generator.

The Core Idea

Any logic that uses React hooks (useState, useEffect, useRef, useCallback) can be extracted into a custom hook. The hook is just a function whose name starts with use. It can call any hooks internally and return whatever the calling component needs.

// Before — component with embedded stateful logic
function SearchBox() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    if (!query) {
      setResults([]);
      return;
    }

    const timeoutId = setTimeout(async () => {
      setIsLoading(true);
      const data = await searchApi(query);
      setResults(data);
      setIsLoading(false);
    }, 300);

    return () => clearTimeout(timeoutId);
  }, [query]);

  return (/* ...render... */);
}

That search logic — debounced API call, loading state, results — is now locked inside this component. You can't reuse it in a different search component without copying the logic.

// After — extracted into a custom hook
function useSearch(searchFn: (query: string) => Promise<any[]>, debounceMs = 300) {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    if (!query) {
      setResults([]);
      return;
    }

    const timeoutId = setTimeout(async () => {
      setIsLoading(true);
      const data = await searchFn(query);
      setResults(data);
      setIsLoading(false);
    }, debounceMs);

    return () => clearTimeout(timeoutId);
  }, [query, searchFn, debounceMs]);

  return { query, setQuery, results, isLoading };
}

// Reusable anywhere
function SearchBox() {
  const { query, setQuery, results, isLoading } = useSearch(searchApi);
  return (/* ...render... */);
}

function UserSearch() {
  const { query, setQuery, results, isLoading } = useSearch(searchUsers, 500);
  return (/* ...render... */);
}

Practical Custom Hook Examples

useLocalStorage — Persisted State

function useLocalStorage<T>(key: string, initialValue: T) {
  const [storedValue, setStoredValue] = useState<T>(() => {
    if (typeof window === 'undefined') return initialValue;

    try {
      const item = window.localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch {
      return initialValue;
    }
  });

  const setValue = useCallback((value: T | ((val: T) => T)) => {
    try {
      const valueToStore = value instanceof Function ? value(storedValue) : value;
      setStoredValue(valueToStore);

      if (typeof window !== 'undefined') {
        window.localStorage.setItem(key, JSON.stringify(valueToStore));
      }
    } catch (error) {
      console.error(`Error saving to localStorage key "${key}":`, error);
    }
  }, [key, storedValue]);

  return [storedValue, setValue] as const;
}

// Usage — exactly like useState but persisted
const [theme, setTheme] = useLocalStorage('theme', 'light');
const [preferences, setPreferences] = useLocalStorage('user-prefs', defaultPrefs);

useAsync — Managing Async Operations

type AsyncState<T> = {
  status: 'idle' | 'pending' | 'success' | 'error';
  data: T | null;
  error: Error | null;
};

function useAsync<T>() {
  const [state, setState] = useState<AsyncState<T>>({
    status: 'idle',
    data: null,
    error: null,
  });

  const execute = useCallback(async (promise: Promise<T>) => {
    setState({ status: 'pending', data: null, error: null });

    try {
      const data = await promise;
      setState({ status: 'success', data, error: null });
      return data;
    } catch (error) {
      const err = error instanceof Error ? error : new Error(String(error));
      setState({ status: 'error', data: null, error: err });
      throw err;
    }
  }, []);

  const reset = useCallback(() => {
    setState({ status: 'idle', data: null, error: null });
  }, []);

  return {
    ...state,
    execute,
    reset,
    isIdle: state.status === 'idle',
    isPending: state.status === 'pending',
    isSuccess: state.status === 'success',
    isError: state.status === 'error',
  };
}

// Usage
function GenerateButton() {
  const { execute, isPending, data, error } = useAsync<GeneratedImage>();

  const handleGenerate = async () => {
    await execute(generateImage(prompt));
  };

  return (
    <div>
      <button onClick={handleGenerate} disabled={isPending}>
        {isPending ? 'Generating...' : 'Generate'}
      </button>
      {data && <img src={data.url} alt="Generated" />}
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}

useMediaQuery — Responsive Logic in Components

function useMediaQuery(query: string): boolean {
  const [matches, setMatches] = useState(() => {
    if (typeof window === 'undefined') return false;
    return window.matchMedia(query).matches;
  });

  useEffect(() => {
    if (typeof window === 'undefined') return;

    const mediaQuery = window.matchMedia(query);
    const handler = (event: MediaQueryListEvent) => setMatches(event.matches);

    mediaQuery.addEventListener('change', handler);
    setMatches(mediaQuery.matches);

    return () => mediaQuery.removeEventListener('change', handler);
  }, [query]);

  return matches;
}

// Usage
function ResponsiveComponent() {
  const isMobile = useMediaQuery('(max-width: 768px)');
  const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');

  return (
    <div>
      {isMobile ? <MobileLayout /> : <DesktopLayout />}
    </div>
  );
}

useClickOutside — Dismissing Popups

function useClickOutside<T extends HTMLElement>(
  callback: () => void
): React.RefObject<T> {
  const ref = useRef<T>(null);

  useEffect(() => {
    const handler = (event: MouseEvent) => {
      if (ref.current && !ref.current.contains(event.target as Node)) {
        callback();
      }
    };

    document.addEventListener('mousedown', handler);
    return () => document.removeEventListener('mousedown', handler);
  }, [callback]);

  return ref;
}

// Usage
function Dropdown({ onClose }) {
  const dropdownRef = useClickOutside<HTMLDivElement>(onClose);

  return (
    <div ref={dropdownRef} className="dropdown">
      {/* dropdown content */}
    </div>
  );
}

Rules for Custom Hooks

Must start with use. React's linting rules enforce this. It's not just convention — it tells React to apply its hook rules to the function.

Can call other hooks. Custom hooks can call useState, useEffect, other custom hooks — anything. The rules of hooks (call at top level, not in conditions) apply inside custom hooks too.

Don't share state. Each component that calls a custom hook gets its own isolated state. If you need shared state between components, use context, Zustand, or another state management solution.

Return what the caller needs. There's no required return shape — objects, arrays, single values, or nothing. Design the return value around what calling components actually need.

When to Extract a Custom Hook

A good signal: you've copied the same useState + useEffect combination to two different components. Extract it.

Another signal: a component has more than two or three separate concerns managed with hooks. Separate them into hooks with clear single responsibilities.

A final signal: you want to test stateful logic without mounting a component. Custom hooks are testable with React Testing Library's renderHook without any component mounting.

Summary

Custom hooks extract stateful logic into reusable functions. They're the clean solution to the "I need to reuse this logic" problem — no extra components, no prop drilling, no wrapper complexity.

The pattern is simple: identify logic that uses React hooks, move it to a use-prefixed function, return what components need. Start with your most-duplicated stateful patterns and extract from there.

Testing Custom Hooks

renderHook from React Testing Library tests hooks without component wrappers:

import { renderHook, act } from '@testing-library/react';
import { useLocalStorage } from './useLocalStorage';

test('useLocalStorage initializes with stored value', () => {
  localStorage.setItem('test-key', JSON.stringify('stored-value'));

  const { result } = renderHook(() => useLocalStorage('test-key', 'default'));

  expect(result.current[0]).toBe('stored-value');
});

test('useLocalStorage updates localStorage on setValue', () => {
  const { result } = renderHook(() => useLocalStorage('test-key', 'initial'));

  act(() => {
    result.current[1]('updated');
  });

  expect(result.current[0]).toBe('updated');
  expect(JSON.parse(localStorage.getItem('test-key')!)).toBe('updated');
});

Testing hooks in isolation makes it easy to cover all the edge cases — error handling, initial state, state transitions — without rendering full component trees.

Parallel Routes in Next.js App Router — Rendering Multiple Pages in One Layout

Aon infotech — Thu, 16 Jul 2026 09:35:45 +0000

Parallel Routes let you render multiple pages simultaneously within the same layout. Instead of navigating away from a page to show another one, you can display both at the same time — a dashboard with independently navigable sections, a main content area alongside a sidebar that changes with its own navigation, or a feed with an openable detail panel that doesn't replace the feed.

This is one of the more powerful App Router features and one of the more confusing to set up initially. Here's the complete pattern, including the design approach used for complex multi-panel interfaces like the generation tool at Pixova.

The Core Concept — Named Slots

Parallel routes use named slots: special folders prefixed with @ that define independent rendering areas within a layout.

app/
├── layout.tsx              ← Receives slot props
├── page.tsx                ← Default slot content
├── @sidebar/
│   ├── page.tsx            ← Sidebar default
│   └── settings/
│       └── page.tsx        ← Sidebar settings view
└── @modal/
    ├── page.tsx            ← Modal default (null)
    └── photo/[id]/
        └── page.tsx        ← Photo modal

The layout receives each slot as a prop:

// app/layout.tsx
export default function Layout({
  children,
  sidebar,
  modal,
}: {
  children: React.ReactNode;
  sidebar: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
    <div className="flex h-screen">
      <aside className="w-64 border-r">{sidebar}</aside>
      <main className="flex-1">{children}</main>
      {modal}
    </div>
  );
}

Now children, sidebar, and modal can each navigate independently.

Independent Navigation — The Key Behavior

Each parallel route slot navigates independently. When a user navigates from / to /settings, the children slot updates. The sidebar slot stays exactly where it was — its navigation state is independent.

This is the key difference from nested layouts. Nested layouts rerender from the changed segment outward. Parallel routes don't affect each other.

User is at / (children shows home, sidebar shows default nav)
User navigates to /settings
→ children now shows settings
→ sidebar unchanged, still shows default nav

User then clicks "Account" in sidebar
→ sidebar now shows account content
→ children unchanged, still shows settings

Default Files — Handling Missing States

When a route navigates and a parallel slot doesn't have content for that URL, Next.js needs to know what to show. This is where default.tsx comes in:

app/
├── @sidebar/
│   ├── default.tsx   ← Shown when sidebar has no matching route
│   └── filters/
│       └── page.tsx
└── @modal/
    └── default.tsx   ← Usually null — modal is hidden by default

// app/@modal/default.tsx
// Return null when no modal should be shown
export default function ModalDefault() {
  return null;
}

// app/@sidebar/default.tsx
// Sidebar shows its default nav when no specific route is active
export default function SidebarDefault() {
  return <DefaultNavigation />;
}

Without default.tsx, navigating to a URL that doesn't match a slot will cause a 404 or error.

Modal Pattern — The Killer Use Case

The most compelling use of parallel routes: opening a detail modal without losing the underlying page, then being able to close the modal and return to the page — with full URL sharing support.

app/
├── @modal/
│   ├── default.tsx         ← null (no modal)
│   └── photos/
│       └── [id]/
│           └── page.tsx    ← Photo detail modal
├── layout.tsx
└── photos/
    └── page.tsx            ← Photo grid

When a user navigates to /photos/123, the @modal slot renders the photo detail while the photo grid stays visible underneath:

// app/@modal/photos/[id]/page.tsx
'use client';
import { useRouter } from 'next/navigation';

export default function PhotoModal({ params }: { params: { id: string } }) {
  const router = useRouter();

  return (
    <div 
      className="fixed inset-0 bg-black/60 flex items-center justify-center z-50"
      onClick={() => router.back()}
    >
      <div 
        className="bg-white rounded-xl max-w-2xl w-full mx-4 p-6"
        onClick={e => e.stopPropagation()}
      >
        <PhotoDetail id={params.id} />
      </div>
    </div>
  );
}

// app/@modal/default.tsx
export default function ModalDefault() {
  return null; // No modal rendered
}

The URL /photos/123 can be shared and when followed directly, the photo modal renders. When navigated to from within the app, the grid stays visible underneath. router.back() closes the modal and returns to the photo grid.

Intercepting Routes — Paired with Parallel Routes

Intercepting routes extend the modal pattern: intercept a link that would normally navigate away and instead show the content in a modal.

app/
├── photos/
│   ├── page.tsx           ← Photo grid
│   └── [id]/
│       └── page.tsx       ← Photo page (for direct access)
└── @modal/
    ├── default.tsx        ← null
    └── (.)photos/         ← Intercepts /photos/:id when navigating from same level
        └── [id]/
            └── page.tsx   ← Photo in modal

The (.) syntax intercepts routes at the same level. (..) intercepts one level up. (...) intercepts from root.

When a user clicks a photo link from the grid, (.)photos/[id] intercepts and shows the modal. When they refresh or share the URL /photos/123, Next.js serves photos/[id]/page.tsx — the full page version.

When to Use Parallel Routes

Use parallel routes for:

Dashboard layouts where sidebar and main content navigate independently
Modal patterns where the underlying page should stay visible
Split-view UIs with two independently navigable panes
Tabs that change URL without replacing the surrounding layout

Don't use parallel routes for:

Simple conditional UI — use state or context instead
Content that appears based on user interaction without changing the URL — useState is simpler
Small nested components — regular component composition works fine

The file system complexity of parallel routes is only worth it when you genuinely need independent URL-based navigation in multiple slots simultaneously.

Loading and Error States Per Slot

Each parallel route slot can have its own loading and error states:

app/
├── @sidebar/
│   ├── loading.tsx    ← Sidebar loading skeleton
│   ├── error.tsx      ← Sidebar error state
│   └── page.tsx
└── @modal/
    ├── loading.tsx    ← Modal loading state
    └── ...

This means the sidebar can show a skeleton while loading without affecting the main content area, and a sidebar error doesn't break the rest of the page.

// app/@sidebar/loading.tsx
export default function SidebarLoading() {
  return (
    <div className="p-4 space-y-3">
      {[...Array(5)].map((_, i) => (
        <div key={i} className="h-8 bg-neutral-100 rounded animate-pulse" />
      ))}
    </div>
  );
}

Summary

Parallel routes use @named folders to define independent rendering slots in a layout. Each slot navigates independently — changes in one slot don't affect others.

The essential files: layout.tsx accepts slot props, default.tsx provides fallback content when a slot has no matching route, loading.tsx and error.tsx give per-slot loading and error states.

The modal pattern — pairing parallel routes with intercepting routes for URL-addressable modals that don't replace the underlying page — is the feature's most powerful application.

Debugging Common Issues

Slot showing wrong content after navigation: Check that default.tsx exists for each slot at every level where navigation could leave the slot without matching content.

404 when navigating parallel routes: Usually means a default.tsx is missing. Every @slot folder that could be in a "no matching route" state needs a default.tsx.

Slots affecting each other: Parallel route slots are independent — if a change in one is affecting another, check that the layout isn't rerendering more than expected. Use React DevTools to verify slot isolation.

Refresh shows different content than navigation: This is the intercepting route working correctly — direct access shows the full page, navigation within the app intercepts to show the modal. If you don't want this behavior, remove the intercept folder.

The File Structure at a Glance

For a dashboard with an independent sidebar and an optional modal:

app/
├── layout.tsx                    # children + sidebar + modal slots
├── page.tsx                      # Main content default
├── settings/
│   └── page.tsx                  # Main content: settings
├── @sidebar/
│   ├── default.tsx               # Default sidebar nav
│   ├── page.tsx                  # Sidebar: home
│   └── admin/
│       └── page.tsx              # Sidebar: admin nav
└── @modal/
    ├── default.tsx               # null — no modal
    └── (.)items/
        └── [id]/
            └── page.tsx          # Item detail modal

That structure handles: independent sidebar navigation, optional modals that intercept item links, URL-addressable modal state, and per-slot loading/error states — all with clean URL semantics.

next/image Deep Dive — Optimization, Lazy Loading, and the Props That Actually Matter

Aon infotech — Tue, 14 Jul 2026 11:19:01 +0000

next/image does a lot automatically — format conversion, lazy loading, preventing layout shift. But several props change behavior significantly, and getting them wrong either hurts performance or breaks things in production. Here's the complete picture of what actually matters, with the approach used in the image-heavy generation results interface.

What next/image Does By Default

When you use <Image> from next/image, you get automatically:

Format conversion: Serves WebP or AVIF to browsers that support them
Lazy loading: Images below the fold don't load until the user scrolls near them
Size optimization: Resizes images to the dimensions you specify
Layout stability: Reserves space before image loads, preventing cumulative layout shift (CLS) These happen without any configuration. The props you add tune this behavior.

The `sizes` Prop — The Most Underused Optimization

The sizes prop tells the browser what size the image will be at different viewport widths. Without it, Next.js can't serve optimally-sized images and defaults to generating several sizes that may be larger than needed.

// Without sizes — Next.js doesn't know the display size
<Image src="/hero.jpg" alt="Hero" fill />

// With sizes — Next.js serves the right size for each viewport
<Image
  src="/hero.jpg"
  alt="Hero"
  fill
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
/>

Read the sizes value as: "On mobile (under 768px), this image takes 100% of the viewport width. On tablets (under 1200px), 50%. On desktop, 33%."

Next.js uses this to calculate which image size to serve. Correct sizes values can reduce image payload by 50-70% on mobile.

Common patterns:

// Full-width hero or banner
sizes="100vw"

// Half-width on desktop, full on mobile
sizes="(max-width: 768px) 100vw, 50vw"

// Card grid — 1 col mobile, 2 col tablet, 3 col desktop
sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"

// Small thumbnail — always small
sizes="150px"

`priority` — For Above-the-Fold Images

By default, next/image lazy loads everything. For images visible immediately on page load (hero images, header images, above-the-fold content), lazy loading is counterproductive — you want these to load as fast as possible.

// Hero image — load immediately, don't lazy load
<Image
  src="/hero.jpg"
  alt="Page hero"
  width={1200}
  height={600}
  priority
/>

Add priority to the first image visible on page load. This tells Next.js to preload it and not apply lazy loading.

The rule: One or two images maximum per page should have priority. If you add it to many images, you've eliminated the performance benefit of lazy loading.

`fill` vs Width/Height — When to Use Each

Explicit width/height: Use when you know the exact dimensions at render time. Generates precise sizes.

<Image
  src="/thumbnail.jpg"
  alt="Product thumbnail"
  width={300}
  height={200}
/>

fill mode: Use when the image should fill its container. The container must be position: relative (or absolute or fixed).

<div className="relative h-64 w-full">
  <Image
    src="/cover.jpg"
    alt="Article cover"
    fill
    sizes="100vw"
    className="object-cover"
  />
</div>

className="object-cover" on the Image determines how it fills the container. object-cover maintains aspect ratio and crops. object-contain maintains aspect ratio with letterboxing.

`quality` — When Default Isn't Right

Default quality is 75, which is a good balance. For specific cases you might adjust:

// Photographic images — default 75 is fine
<Image src="/photo.jpg" alt="Photo" width={800} height={600} />

// Icons or images with sharp lines — higher quality prevents artifacts
<Image src="/logo.png" alt="Logo" width={100} height={50} quality={90} />

// Background textures where quality difference isn't visible
<Image src="/texture.jpg" alt="" width={1200} height={800} quality={60} />

Higher quality = larger file size. The default is right for most cases.

External Images — The `remotePatterns` Config

By default, next/image only optimizes images from your own domain. For external images, you need to configure allowed patterns:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'cdn.example.com',
        port: '',
        pathname: '/images/**',
      },
      {
        protocol: 'https',
        hostname: '*.cdn-example.com', // wildcard subdomain
      },
    ],
  },
};

module.exports = nextConfig;

Be specific with pathname patterns. Wildcard /** allows any path on that host. More restrictive patterns are safer.

The `placeholder` Prop — Blur-Up Loading

For a smooth loading experience, next/image supports a blur placeholder that shows while the full image loads:

// Static images — Next.js generates blurDataURL automatically at build time
import heroImage from '/public/hero.jpg';

<Image
  src={heroImage}
  alt="Hero"
  placeholder="blur"
  priority
/>

For dynamic images (external URLs), you need to provide the blur data yourself:

// Generate a tiny blurred placeholder (many services provide these)
const blurDataURL = 'data:image/jpeg;base64,/9j/4AAQ...'; // tiny base64 image

<Image
  src={dynamicImageUrl}
  alt="Dynamic image"
  width={800}
  height={600}
  placeholder="blur"
  blurDataURL={blurDataURL}
/>

The placeholder="blur" approach significantly improves perceived loading performance for above-the-fold images.

Checking What's Actually Being Served

To verify your image optimization is working:

Open DevTools → Network tab
Filter by Img
Check the Type column — should show webp or avif instead of jpeg/png
Check image size in the Size column vs original file size A well-optimized image should be significantly smaller than the original and in a modern format.

Common Mistakes

Forgetting sizes on fill images. Without sizes, Next.js can't optimize for viewport — generates full-size images for all viewports.

Adding priority to too many images. It's for above-the-fold only. One or two per page maximum.

Not configuring remotePatterns. External images without pattern configuration fall back to unoptimized serving, breaking the performance benefits.

Using <img> instead of <Image>. Native <img> tags don't get any next/image optimization — no format conversion, no lazy loading, no layout stability. ESLint rule next/no-img-element catches this.

Summary Table

Prop	When to use
`sizes`	Always, when using `fill` or when image width changes across viewports
`priority`	First 1-2 visible images on page load only
`fill`	When image should fill a container with unknown dimensions
`quality`	When default 75 is visibly too low (icons) or unnecessarily high
`placeholder="blur"`	Above-the-fold images where loading is visible to users

The three that move the needle most: correct sizes (biggest file size impact), priority on LCP images (biggest perceived performance impact), and remotePatterns configuration (required for external images to optimize at all).

Loader Configuration for Custom CDNs

If you serve images from a custom CDN with its own optimization parameters, you can configure a custom loader:

// next.config.js
module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './imageLoader.js',
  },
};

// imageLoader.js
export default function myImageLoader({ src, width, quality }) {
  return `https://your-cdn.com/image?url=${src}&w=${width}&q=${quality || 75}`;
}

This gives you full control over how image URLs are constructed for optimization, useful when your CDN uses different query parameter formats than Next.js expects.

For most applications using standard hosting, the default loader is correct. Custom loaders are for specific CDN integrations that need URL format control.

Image Domains Migration From Old Config

If you're on an older Next.js version using domains config, migrate to remotePatterns:

// Old (deprecated)
images: {
  domains: ['cdn.example.com'],
}

// New (use this)
images: {
  remotePatterns: [
    { protocol: 'https', hostname: 'cdn.example.com' }
  ],
}

remotePatterns is more secure — it supports pathname restrictions that domains doesn't, preventing a compromised external hostname from serving arbitrary paths through your Next.js image optimizer.

Error Handling in Next.js App Router — error.tsx, not-found.tsx, and global-error.tsx

Aon infotech — Mon, 13 Jul 2026 08:23:30 +0000

Error handling in Next.js App Router works through a file-based convention — specific files at specific locations in your route structure automatically catch and handle errors at different levels. Understanding the hierarchy prevents the most common error handling gaps.

Here's the complete error handling system, including the patterns I use for user-facing tools like the free image generation tool for teachers where error UX directly affects how much users trust the product.

The Error Handling File Hierarchy

Next.js App Router provides four files for error handling:

app/
├── error.tsx           ← Catches errors in route segments
├── not-found.tsx       ← Handles 404s (notFound() calls)
├── global-error.tsx    ← Catches errors in root layout
└── loading.tsx         ← Loading UI (not error, but related)

Each serves a different purpose and operates at a different level of the rendering tree.

error.tsx — The Main Error Boundary

error.tsx wraps a route segment in a React Error Boundary. When any component in that segment throws, error.tsx catches it and renders instead.

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

import { useEffect } from 'react';

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

export default function DashboardError({ error, reset }: ErrorProps) {
  useEffect(() => {
    // Log to your error reporting service
    console.error('Dashboard error:', error);
  }, [error]);

  return (
    <div className="flex flex-col items-center justify-center min-h-[400px] gap-4">
      <div className="text-center">
        <h2 className="text-xl font-semibold text-neutral-800">
          Something went wrong
        </h2>
        <p className="text-neutral-500 mt-1 text-sm">
          {error.digest 
            ? `Error ID: ${error.digest}` 
            : 'An unexpected error occurred'}
        </p>
      </div>
      <button
        onClick={reset}
        className="px-4 py-2 bg-orange-500 text-white rounded-full text-sm"
      >
        Try again
      </button>
    </div>
  );
}

Key points:

Must be a Client Component ('use client')
Receives error object and reset function
reset() re-renders the segment, giving the user a retry path
error.digest is a hash Next.js generates for server-side errors — matches the log entry in your server logs

Nesting error.tsx Files

error.tsx only catches errors in its sibling directory and below. You can nest them:

app/
├── error.tsx           ← Catches errors in all routes
├── dashboard/
│   ├── error.tsx       ← Catches errors in /dashboard routes
│   └── settings/
│       └── error.tsx   ← Catches errors in /dashboard/settings

The most specific error.tsx catches first. Errors bubble up if no closer handler exists.

This allows granular error UI: /dashboard/settings might show an inline error with specific settings-context help, while a top-level error shows a generic fallback.

not-found.tsx — Handling Missing Resources

not-found.tsx renders when notFound() is called from a Server Component. This is for expected 404s — resource doesn't exist, ID not found in database.

// app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation';

export default async function BlogPost({ params }: { params: { slug: string } }) {
  const post = await getPost(params.slug);

  if (!post) {
    notFound(); // Triggers not-found.tsx
  }

  return <Article post={post} />;
}

// app/blog/not-found.tsx
import Link from 'next/link';

export default function BlogNotFound() {
  return (
    <div className="flex flex-col items-center justify-center min-h-[400px] gap-4 text-center">
      <h1 className="text-2xl font-semibold">Post not found</h1>
      <p className="text-neutral-500">
        This post may have been moved or removed.
      </p>
      <Link 
        href="/blog"
        className="px-4 py-2 bg-neutral-900 text-white rounded-full text-sm"
      >
        Browse all posts
      </Link>
    </div>
  );
}

not-found.tsx can be Server or Client — unlike error.tsx. It doesn't receive props.

global-error.tsx — Catching Root Layout Errors

error.tsx doesn't catch errors thrown in the root layout.tsx — the error boundary is siblings with the layout, not wrapping it. global-error.tsx handles this case.

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

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    // global-error replaces the root layout entirely
    // Must include html and body tags
    <html>
      <body>
        <div style={{ 
          minHeight: '100vh',
          display: 'flex',
          flexDirection: 'column',
          alignItems: 'center',
          justifyContent: 'center',
          fontFamily: 'system-ui, sans-serif'
        }}>
          <h2>Something went wrong</h2>
          <button onClick={reset}>Try again</button>
        </div>
      </body>
    </html>
  );
}

global-error.tsx replaces the entire page — including the root layout — so it must include <html> and <body> tags. It only fires in production (not in development, where the error overlay shows instead).

Error Reporting Integration

The error.tsx useEffect is where you connect to error reporting services:

'use client';
import { useEffect } from 'react';

export default function Error({ error, reset }: ErrorProps) {
  useEffect(() => {
    // Sentry
    Sentry.captureException(error);

    // Or any other error reporting service
    reportError({
      message: error.message,
      digest: error.digest,
      stack: error.stack,
    });
  }, [error]);

  return (/* ... */);
}

The error.digest is critical for server-side errors: the actual error message is not sent to the client (for security), but the digest lets you match the client error to the full server-side error in your logs.

Typed Error Responses

For API routes, return typed error responses rather than throwing:

// app/api/generate/route.ts
export async function POST(request: Request) {
  try {
    const data = await processRequest(request);
    return Response.json({ success: true, data });
  } catch (error) {
    // Return structured error, don't throw
    return Response.json(
      { 
        success: false, 
        error: 'Generation failed',
        code: 'GENERATION_ERROR'
      },
      { status: 500 }
    );
  }
}

Client-side, check response.ok before using data:

const response = await fetch('/api/generate', { method: 'POST', body });
if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error ?? 'Request failed');
}
const data = await response.json();

The Common Mistake

The most common error handling mistake: not providing a reset path. An error component that just shows "something went wrong" with no way forward forces users to refresh the entire page, which loses their context and feels like the app broke.

Always provide: a clear error message, what to try, and a reset() button that retries the failed segment. Where appropriate, also provide navigation away (home page link, search) in case retry fails too.

Testing Error Boundaries

Testing that error boundaries actually catch errors requires deliberately throwing:

// components/ErrorThrower.tsx (test utility)
'use client';
import { useState } from 'react';

export function ErrorThrower() {
  const [shouldThrow, setShouldThrow] = useState(false);

  if (shouldThrow) {
    throw new Error('Test error from ErrorThrower');
  }

  return (
    <button onClick={() => setShouldThrow(true)}>
      Trigger test error
    </button>
  );
}

Place this in a route surrounded by your error.tsx to verify the error boundary renders correctly. Remove before production.

For automated testing of error states, React Testing Library's console.error mocking prevents test pollution from expected error outputs:

test('error boundary shows error UI', () => {
  const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => {});

  render(<ComponentThatThrows />);

  expect(screen.getByText('Something went wrong')).toBeInTheDocument();
  expect(screen.getByRole('button', { name: 'Try again' })).toBeInTheDocument();

  consoleSpy.mockRestore();
});

Summary

The App Router error handling hierarchy: error.tsx for route-segment errors, not-found.tsx for missing resources via notFound(), global-error.tsx for root layout errors. Nest error.tsx at the granularity you need — more specific error UI for more specific routes.

Always include a reset() retry path. Always log errors in useEffect. Use error.digest to correlate client errors with server logs.

Quick Reference

File	Catches	Must be client?	Receives props?
`error.tsx`	Segment errors	Yes	`error`, `reset`
`not-found.tsx`	`notFound()` calls	No	None
`global-error.tsx`	Root layout errors	Yes	`error`, `reset`

Place each file as a sibling to the page.tsx you want it to protect. global-error.tsx goes directly in the app/ directory.

useFormState and useFormStatus in Next.js App Router — React 19 Form Handling

Aon infotech — Sun, 12 Jul 2026 07:13:07 +0000

React 19 introduced two hooks specifically for server action forms: useFormState and useFormStatus. Together they solve the main UX problems with form submissions — showing loading states, displaying server errors, and updating UI based on server responses — without requiring client-side state management for the form itself.

Here's how both hooks work in Next.js App Router and the patterns that produce the cleanest implementations, including the approach used for the generation form at AI presentation images.

The Problem These Hooks Solve

Before React 19, handling a Server Action form required:

A Server Action for the form submission
Client-side state (useState) for pending state
Client-side state for error display
useTransition or isPending for loading state The new hooks reduce this significantly.

useFormStatus — Pending State Inside Forms

useFormStatus gives any component inside a form access to the form's submission status. The key behavior: it reads from the nearest parent <form>, not from props.

// components/SubmitButton.jsx
'use client';
import { useFormStatus } from 'react-dom';

export function SubmitButton({ children }) {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      className={`px-6 py-2 rounded-full font-medium transition-all
        ${pending 
          ? 'bg-neutral-400 cursor-not-allowed' 
          : 'bg-orange-500 hover:bg-orange-600'
        }`}
    >
      {pending ? 'Submitting...' : children}
    </button>
  );
}

This SubmitButton component automatically shows a pending state when the parent form is submitting — no prop drilling, no manual state required.

// Any form that uses this button
export function ContactForm() {
  return (
    <form action={submitContactForm}>
      <input name="email" type="email" required />
      <textarea name="message" required />
      <SubmitButton>Send Message</SubmitButton>
      {/* SubmitButton knows the form is pending automatically */}
    </form>
  );
}

useFormStatus also exposes data (the FormData being submitted), method, and action — useful for more advanced patterns.

useFormState — Server Response in the Client

useFormState wraps a Server Action and gives you access to its return value in the client component. This is how you display server-side validation errors and success states.

// app/actions/contact.ts
'use server';

type FormState = {
  success: boolean;
  error?: string;
  fieldErrors?: Record<string, string>;
};

export async function submitContactForm(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  const email = formData.get('email') as string;
  const message = formData.get('message') as string;

  if (!email || !email.includes('@')) {
    return {
      success: false,
      fieldErrors: { email: 'Please enter a valid email address' }
    };
  }

  if (!message || message.length < 20) {
    return {
      success: false,
      fieldErrors: { message: 'Message must be at least 20 characters' }
    };
  }

  try {
    await sendEmail({ email, message });
    return { success: true };
  } catch {
    return { success: false, error: 'Failed to send. Please try again.' };
  }
}

Notice the signature: the Server Action now takes prevState as its first argument — useFormState passes the previous state on each submission.

// components/ContactForm.jsx
'use client';
import { useFormState } from 'react-dom';
import { submitContactForm } from '@/app/actions/contact';
import { SubmitButton } from './SubmitButton';

const initialState = { success: false };

export function ContactForm() {
  const [state, formAction] = useFormState(submitContactForm, initialState);

  if (state.success) {
    return (
      <div className="p-6 bg-green-50 rounded-xl text-green-700">
        Message sent successfully. We'll be in touch soon.
      </div>
    );
  }

  return (
    <form action={formAction}>
      <div className="flex flex-col gap-4">
        <div>
          <input
            name="email"
            type="email"
            placeholder="Your email"
            className="w-full p-3 border rounded-lg"
            aria-describedby="email-error"
          />
          {state.fieldErrors?.email && (
            <p id="email-error" className="text-sm text-red-500 mt-1">
              {state.fieldErrors.email}
            </p>
          )}
        </div>

        <div>
          <textarea
            name="message"
            placeholder="Your message"
            className="w-full p-3 border rounded-lg h-32"
            aria-describedby="message-error"
          />
          {state.fieldErrors?.message && (
            <p id="message-error" className="text-sm text-red-500 mt-1">
              {state.fieldErrors.message}
            </p>
          )}
        </div>

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

        <SubmitButton>Send Message</SubmitButton>
      </div>
    </form>
  );
}

The form now: shows field-level errors from the server, shows a success state after submission, has an automatically pending submit button — all without any manual useState for pending or error state.

Combining Both Hooks

The pattern works best when both hooks are used together:

'use client';
import { useFormState } from 'react-dom';
import { useFormStatus } from 'react-dom';

// useFormStatus: used inside the form, shows pending state
function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Saving...' : 'Save'}
    </button>
  );
}

// useFormState: wraps the action, provides state to the component
function EditProfileForm({ user }) {
  const [state, action] = useFormState(updateProfile, { success: false });

  return (
    <form action={action}>
      <input name="name" defaultValue={user.name} />
      {state.fieldErrors?.name && <p>{state.fieldErrors.name}</p>}

      <input name="bio" defaultValue={user.bio} />
      {state.fieldErrors?.bio && <p>{state.fieldErrors.bio}</p>}

      {state.success && <p>Profile updated!</p>}
      {state.error && <p>{state.error}</p>}

      <SubmitButton />
    </form>
  );
}

Progressive Enhancement

One significant benefit of this pattern: forms built this way work without JavaScript. The Server Action handles submission, the server returns a response, and the form shows the updated state — all without client-side JavaScript.

With JavaScript enabled, the experience is faster (no page reload, pending state feedback). Without JavaScript, it still works. This progressive enhancement happens automatically when you use native <form> elements with action attributes pointing to Server Actions.

When Not to Use This Pattern

Complex multi-step forms. Forms where each step depends on the previous step's data are better handled with client-side state management (Zustand or React Query) rather than Server Actions.

Optimistic updates. If you want to show the result immediately before the server confirms it, useOptimistic combined with useTransition is more appropriate than useFormState.

Real-time validation. useFormState triggers only on submission. For field-level validation as users type, client-side validation logic is still needed.

For most simple forms — contact, login, settings, profile — useFormState + useFormStatus is the cleanest pattern available in React 19 App Router.

Accessibility Considerations

The pattern above includes aria-describedby to connect error messages to their fields. This is important when using server-returned validation errors — screen readers need to know which field an error refers to.

<div>
  <label htmlFor="email">Email</label>
  <input
    id="email"
    name="email"
    type="email"
    aria-describedby={state.fieldErrors?.email ? "email-error" : undefined}
    aria-invalid={state.fieldErrors?.email ? "true" : undefined}
  />
  {state.fieldErrors?.email && (
    <p id="email-error" role="alert">
      {state.fieldErrors.email}
    </p>
  )}
</div>

The role="alert" on the error paragraph announces the error to screen readers when it appears — without requiring focus management.

Testing

Testing useFormState components requires wrapping the form in an act() call and simulating submission:

import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { ContactForm } from './ContactForm';

// Mock the server action
jest.mock('@/app/actions/contact', () => ({
  submitContactForm: jest.fn().mockResolvedValue({ 
    success: true 
  })
}));

test('shows success state after submission', async () => {
  render(<ContactForm />);

  fireEvent.change(screen.getByPlaceholderText('Your email'), {
    target: { value: 'test@example.com' }
  });

  fireEvent.change(screen.getByPlaceholderText('Your message'), {
    target: { value: 'This is a test message that is long enough' }
  });

  fireEvent.click(screen.getByRole('button', { name: 'Send Message' }));

  await waitFor(() => {
    expect(screen.getByText(/message sent successfully/i)).toBeInTheDocument();
  });
});

The mock replaces the Server Action with a resolved promise, which is what useFormState expects.

Summary

useFormStatus gives any component inside a form instant access to the form's pending state — no prop drilling, no context.

useFormState wraps a Server Action to give the client component access to the action's return value — perfect for server-side validation errors and success states.

Together they cover most form handling needs in Next.js App Router with minimal client-side code, progressive enhancement built in, and clean separation between client and server concerns.

Next.js ISR and On-Demand Revalidation — Caching Without Staleness

Aon infotech — Sat, 11 Jul 2026 11:14:10 +0000

Incremental Static Regeneration (ISR) is one of the more powerful caching strategies in Next.js — and one that's often misconfigured in ways that either make it useless or cause unexpected staleness. On-demand revalidation, added in later Next.js versions, fixes the main problems with time-based ISR. Here's how both work and when to use which.

The pattern I'm describing here runs in production powering the free image generation for Etsy sellers use case where stale gallery data would be confusing.

What ISR Actually Does

ISR lets you pre-render pages at build time and then update them in the background when they go stale. The key behaviors:

First request after cache expiry: serve the stale page immediately (no wait), trigger background regeneration
Subsequent requests while regenerating: still serve stale content
After regeneration completes: new requests get the fresh page This "stale-while-revalidate" approach means users never wait for a slow page render — but it also means they might see outdated content for a period after data changes.

Time-Based ISR

// app/blog/[slug]/page.js
export const revalidate = 3600; // Revalidate at most every hour

export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);
  return <Article post={post} />;
}

Or for more granular control in fetch calls:

async function getPost(slug) {
  const res = await fetch(`https://api.example.com/posts/${slug}`, {
    next: { revalidate: 3600 }
  });
  return res.json();
}

When time-based ISR works well:

Content that changes on a predictable schedule (daily, hourly)
Content where slightly stale data is acceptable
High-traffic pages where you want the performance benefits of static serving When it doesn't work well:
Content that changes unpredictably (user actions, CMS updates)
Content where staleness is confusing or misleading

- Low-traffic pages that might not get re-validated within the revalidation window

The Problem With Time-Based ISR

The main failure mode: an editor publishes an urgent update (price change, event cancellation, product correction) and it doesn't appear for up to an hour because the revalidation window hasn't expired.

This is where on-demand revalidation solves a real problem.

On-Demand Revalidation

On-demand revalidation lets you programmatically invalidate specific cached pages or data when you know the underlying data has changed — from a webhook, a CMS publish event, or an admin action.

Setting Up the Revalidation Endpoint

// app/api/revalidate/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { revalidatePath, revalidateTag } from 'next/cache';

const REVALIDATION_SECRET = process.env.REVALIDATION_SECRET;

export async function POST(request: NextRequest) {
  const body = await request.json();

  // Verify the request is from a trusted source
  if (body.secret !== REVALIDATION_SECRET) {
    return NextResponse.json({ message: 'Invalid secret' }, { status: 401 });
  }

  try {
    if (body.type === 'path') {
      // Revalidate a specific path
      revalidatePath(body.path);
    } else if (body.type === 'tag') {
      // Revalidate all pages tagged with this cache tag
      revalidateTag(body.tag);
    }

    return NextResponse.json({ revalidated: true });
  } catch (error) {
    return NextResponse.json({ message: 'Error revalidating' }, { status: 500 });
  }
}

Cache Tags — The Better Approach

Cache tags let you invalidate multiple related pages at once:

// Tag fetches with semantic cache tags
async function getPost(slug) {
  const res = await fetch(`https://api.example.com/posts/${slug}`, {
    next: { 
      tags: [`post-${slug}`, 'posts'],
      revalidate: false // Never time-expire — rely on on-demand only
    }
  });
  return res.json();
}

async function getPostList() {
  const res = await fetch('https://api.example.com/posts', {
    next: { 
      tags: ['posts'],
      revalidate: false
    }
  });
  return res.json();
}

// Revalidate endpoint using tags
export async function POST(request: NextRequest) {
  const body = await request.json();

  if (body.secret !== REVALIDATION_SECRET) {
    return NextResponse.json({ message: 'Invalid secret' }, { status: 401 });
  }

  // When a post is updated, invalidate both the specific post and the list
  if (body.event === 'post.updated') {
    revalidateTag(`post-${body.slug}`); // Just this post
    revalidateTag('posts'); // Also the list
  }

  if (body.event === 'post.deleted') {
    revalidateTag(`post-${body.slug}`);
    revalidateTag('posts');
  }

  return NextResponse.json({ revalidated: true });
}

Connecting to a CMS Webhook

Most headless CMS platforms (Contentful, Sanity, Notion CMS, etc.) support webhooks on content changes. Configure the webhook to call your revalidation endpoint:

Webhook URL: https://yourdomain.com/api/revalidate
Method: POST
Body:

{
  "secret": "your-secret-here",
  "event": "post.updated",
  "slug": "the-updated-post-slug"
}

When content is published or updated in the CMS, the webhook fires, your endpoint revalidates the affected tags, and the next request to the relevant pages triggers fresh data fetching.

The `revalidatePath` vs `revalidateTag` Decision

revalidatePath: Invalidates a specific URL path. Simple, direct.

revalidatePath('/blog/my-post-slug');
revalidatePath('/blog'); // Revalidate the blog index
revalidatePath('/', 'layout'); // Revalidate everything that uses the root layout

revalidateTag: Invalidates all pages that fetched data with that cache tag. More flexible, works across related pages.

Use revalidatePath when you know exactly which URL needs updating. Use revalidateTag when a data change affects multiple pages you can't enumerate upfront.

Combining Both Strategies

In practice, a combination works well:

// Default: moderate time-based revalidation as a safety net
export const revalidate = 3600;

// Specific fetches: tagged for on-demand invalidation
async function getProductData(id) {
  const res = await fetch(`/api/products/${id}`, {
    next: { 
      tags: [`product-${id}`, 'products'],
      revalidate: 3600 // Time-based as fallback
    }
  });
  return res.json();
}

The time-based revalidation ensures even if webhook delivery fails, the cache eventually refreshes. The on-demand revalidation ensures intentional updates appear immediately when the CMS fires a webhook.

Testing Revalidation

Manual testing for your revalidation endpoint:

curl -X POST https://your-domain.com/api/revalidate \
  -H "Content-Type: application/json" \
  -d '{"secret": "your-secret", "type": "tag", "tag": "posts"}'

Check the response: {"revalidated": true}. Then request the previously cached page — it should now reflect current data.

In development: revalidateTag and revalidatePath still work in next dev but the behavior is different from production — dev mode doesn't cache in the same way. Test revalidation in a production-like staging environment for accurate behavior validation.

Common ISR Mistakes

Setting revalidate: 0. This disables caching entirely — equivalent to making every request server-rendered. Not ISR. Use revalidate: false if you want on-demand-only revalidation with no time-based expiry.

Not securing the revalidation endpoint. Without the secret check, anyone can force-revalidate your cache, which is a minor DoS vector. Always validate the secret.

Revalidating too broadly. revalidatePath('/', 'layout') revalidates everything — expensive and slow. Use specific paths or tags wherever possible.

Not handling revalidation failures. If the webhook fires but the revalidation endpoint returns an error, the stale content persists. Add monitoring for revalidation endpoint failures and consider retry logic in the CMS webhook settings.

Forgetting that revalidation doesn't guarantee immediate freshness. After revalidateTag, the next request triggers regeneration. That user sees slightly old content during regeneration. Subsequent users see the fresh version. This is expected behavior, not a bug — but product teams need to understand it.

Summary

Time-based ISR (revalidate: 3600) is a simple, effective cache strategy for content that changes on a schedule. It has known limitations around unpredictable content changes.

On-demand revalidation via cache tags is the right solution when you need precise control: invalidate specific data when it changes, triggered by CMS webhooks or application events. Use both together — time-based as a safety net, on-demand for immediate intentional updates.

React Server Components vs Client Components in Next.js — A Practical Decision Framework

Aon infotech — Fri, 10 Jul 2026 11:48:16 +0000

The App Router's Server Component default confuses a lot of developers coming from Pages Router. Everything is a Server Component unless you opt out. Interactivity requires Client Components. Knowing when to use which — and where to draw the boundary — is the most important architectural decision in an App Router application.

Here's a practical framework for making that decision, including the patterns I've found most useful building generation interfaces at pixova.io.

The Core Distinction

Server Components run on the server, have access to server-side resources (databases, file system, environment variables), and never ship JavaScript to the browser. They render to HTML.

Client Components run in the browser. They can use React hooks (useState, useEffect), handle DOM events, access browser APIs, and create interactive UI.

The practical question isn't "do I want this to be interactive?" It's "what is the minimum client-side JavaScript this component actually needs?"

When to Use Server Components (Default)

Use Server Components for anything that:

Fetches data. Data fetching on the server avoids client-side loading states and keeps data fetching logic close to where data is used.

// Server Component — no 'use client' needed
async function ProductList() {
  const products = await db.products.findMany({ where: { active: true } });

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

Renders conditionally based on server state. Authorization checks, feature flags, A/B testing logic.

async function AdminSection() {
  const user = await getCurrentUser();
  if (!user?.isAdmin) return null;

  return <AdminDashboard />;
}

Is primarily static HTML. Navigation, headers, footers, content sections, layouts — anything that doesn't need to update or respond to user input.

Needs server-only data. API keys, database connections, server-only environment variables — these should never reach the client.

When to Use Client Components

Opt into Client Components ('use client') for components that need:

React hooks for local state:

'use client';
import { useState } from 'react';

function Accordion({ items }) {
  const [openIndex, setOpenIndex] = useState(null);

  return (
    <div>
      {items.map((item, i) => (
        <div key={i}>
          <button onClick={() => setOpenIndex(i === openIndex ? null : i)}>
            {item.title}
          </button>
          {openIndex === i && <p>{item.content}</p>}
        </div>
      ))}
    </div>
  );
}

Browser event handlers. Any onClick, onChange, onSubmit, onFocus — these can only run in the browser.

Browser APIs. window, document, localStorage, navigator, geolocation, clipboard API — only available client-side.

Real-time updates. WebSockets, SSE, polling — requires client-side code.

Third-party client-side libraries. Libraries that use browser APIs internally need to run client-side.

The Boundary Pattern

The most important pattern: push 'use client' as deep into the component tree as possible.

Wrong — unnecessarily large client boundary:

// Entire page becomes a Client Component just because of one button
'use client';
import { useState } from 'react';
import { ProductList } from './ProductList'; // Now this is also client-side

export default function ProductPage({ products }) {
  const [filter, setFilter] = useState('all');

  return (
    <div>
      <h1>Products</h1>
      <FilterButton filter={filter} onChange={setFilter} /> // Needs client
      <ProductList products={products} filter={filter} />   // Doesn't need client
    </div>
  );
}

Right — minimal client boundary:

// Page remains a Server Component
import { FilterableProductList } from './FilterableProductList';

export default async function ProductPage() {
  const products = await db.products.findMany();

  return (
    <div>
      <h1>Products</h1>
      <FilterableProductList products={products} />
    </div>
  );
}

// Only the interactive part is a Client Component
'use client';
import { useState } from 'react';

export function FilterableProductList({ products }) {
  const [filter, setFilter] = useState('all');

  const filtered = products.filter(p => 
    filter === 'all' || p.category === filter
  );

  return (
    <div>
      <select value={filter} onChange={e => setFilter(e.target.value)}>
        <option value="all">All</option>
        <option value="sale">Sale</option>
      </select>
      <ul>
        {filtered.map(p => <li key={p.id}>{p.name}</li>)}
      </ul>
    </div>
  );
}

The second version keeps the data fetching on the server while limiting client JavaScript to the interactive parts.

Passing Server Data to Client Components

Server Components can pass data to Client Components through props. The data must be serializable (JSON-compatible):

// Server Component
import { UserProfile } from './UserProfile';

async function UserPage({ userId }) {
  const user = await db.users.findUnique({ where: { id: userId } });

  // Pass serializable data only — no functions, no class instances
  return (
    <UserProfile 
      id={user.id}
      name={user.name}
      email={user.email}
      // Not: user object with methods, Date objects that need serialization
    />
  );
}

// Client Component
'use client';
function UserProfile({ id, name, email }) {
  const [isEditing, setIsEditing] = useState(false);
  // ...
}

What can be passed: strings, numbers, booleans, plain objects, arrays of these.
What can't be passed: functions, class instances, non-serializable objects, React Server Component output.

The Interleaving Pattern

Server Components can render Client Components. Client Components can't render Server Components directly — but they can render children that happen to be Server Components.

// Server Component
import { Modal } from './Modal'; // Client Component
import { ExpensiveServerData } from './ExpensiveServerData'; // Server Component

async function Page() {
  return (
    <Modal>
      <ExpensiveServerData /> {/* Server Component passed as children */}
    </Modal>
  );
}

// Client Component — receives children without knowing their type
'use client';
function Modal({ children }) {
  const [isOpen, setIsOpen] = useState(true);

  if (!isOpen) return null;

  return (
    <div className="modal">
      {children} {/* Could be Server Component output */}
      <button onClick={() => setIsOpen(false)}>Close</button>
    </div>
  );
}

This pattern lets interactive Client Components wrap expensive Server Component data fetching without making the data fetching client-side.

Common Mistakes

Adding 'use client' to leaf components unnecessarily. If a component doesn't need hooks or browser APIs, it should be a Server Component. Many developers add it "just in case" and lose the benefits.

Trying to use server-only APIs in Client Components. headers(), cookies(), direct database calls — these don't work in Client Components. Move them up to a Server Component parent.

Passing non-serializable data as props. Passing a full database row object, a Date object, or a function from a Server Component to a Client Component will fail at runtime or cause serialization issues.

Making layout files Client Components. Layout files should almost always be Server Components — they don't need interactivity, and making them client-side forces all nested components into the client bundle unnecessarily.

A Quick Decision Checklist

Before writing 'use client', ask:

Does this component use useState, useReducer, or custom hooks that use them? → Client
Does this component use useEffect or useLayoutEffect? → Client
Does this component attach browser event handlers? → Client
Does this component access window, document, or browser APIs? → Client
Does this component use a library that requires browser APIs? → Client If none of the above: leave it as a Server Component.

Then ask where the boundary belongs:

Can I split this component so only the interactive part needs 'use client'?
Can I extract the interactive part into a smaller child component? The goal is the smallest possible client bundle — every byte of JavaScript that doesn't need to be in the browser improves page load performance.

Summary

Server Components are the default in App Router — fast, zero JavaScript cost, direct data access. Use them for everything that doesn't require browser interactivity.

Client Components handle interactivity — hooks, events, browser APIs. Use them for the minimum necessary to make UI interactive.

The key architectural discipline: push 'use client' as deep as possible, keep Server Components doing data work, and pass serializable data down through props.

Next.js Middleware for Auth and Route Protection — The Complete Pattern

Aon infotech — Mon, 06 Jul 2026 12:01:58 +0000

Middleware in Next.js runs before every matched request. It's the right place for authentication checks, redirects, and route protection — logic that needs to run consistently regardless of which page hits first.

Here's the production-ready pattern for middleware auth in App Router, including the edge cases that catch most implementations off-guard. The same approach runs in production at pixova.io/blog/free-ai-background-generator.

What Middleware Can and Can't Do

Middleware runs at the edge — fast, close to users, before server or database hits. That speed comes with constraints.

Can do: Read/write cookies, read request headers, redirect requests, rewrite URLs, return early responses.

Can't do: Hit databases directly, use most Node.js APIs, call server-side libraries requiring Node runtime.

This means authentication in middleware needs to verify tokens without a database call. JWT-based auth is the standard solution.

Basic Structure

// middleware.ts — at project root, NOT inside /app
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const token = request.cookies.get('auth-token')?.value;

  const isProtected = pathname.startsWith('/dashboard') ||
    pathname.startsWith('/account');

  if (isProtected && !token) {
    const loginUrl = new URL('/login', request.url);
    loginUrl.searchParams.set('redirect', pathname);
    return NextResponse.redirect(loginUrl);
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/account/:path*'],
};

The matcher config is critical — without it, middleware runs on every request including static assets and Next.js internals, which creates unnecessary overhead.

JWT Verification at the Edge

Standard jsonwebtoken doesn't run at the edge. Use jose instead:

npm install jose

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { jwtVerify } from 'jose';

const JWT_SECRET = new TextEncoder().encode(process.env.JWT_SECRET!);

async function verifyToken(token: string) {
  try {
    const { payload } = await jwtVerify(token, JWT_SECRET);
    return payload;
  } catch {
    return null;
  }
}

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const token = request.cookies.get('auth-token')?.value;

  const isProtected = pathname.startsWith('/dashboard');
  const isAuthRoute = pathname === '/login' || pathname === '/signup';

  if (isProtected) {
    if (!token) {
      return redirectToLogin(request, pathname);
    }

    const payload = await verifyToken(token);

    if (!payload) {
      // Token invalid/expired — clean it up and redirect
      const response = redirectToLogin(request, pathname);
      response.cookies.delete('auth-token');
      return response;
    }

    // Valid — pass user context to downstream routes via headers
    const requestHeaders = new Headers(request.headers);
    requestHeaders.set('x-user-id', payload.sub as string);
    requestHeaders.set('x-user-role', payload.role as string);

    return NextResponse.next({ request: { headers: requestHeaders } });
  }

  // Redirect already-authenticated users away from login/signup
  if (isAuthRoute && token) {
    const payload = await verifyToken(token);
    if (payload) {
      return NextResponse.redirect(new URL('/dashboard', request.url));
    }
  }

  return NextResponse.next();
}

function redirectToLogin(request: NextRequest, from: string) {
  const url = new URL('/login', request.url);
  url.searchParams.set('redirect', from);
  return NextResponse.redirect(url);
}

export const config = {
  matcher: ['/dashboard/:path*', '/account/:path*', '/login', '/signup'],
};

Reading User Context in Server Components

The headers set by middleware flow through to Server Components:

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

export default async function DashboardPage() {
  const headersList = headers();
  const userId = headersList.get('x-user-id');
  const role = headersList.get('x-user-role');

  // Only fetch user data — auth already handled by middleware
  const userData = await fetchUserData(userId!);

  return <Dashboard user={userData} role={role} />;
}

This pattern means Server Components handle data fetching. Middleware handles auth. Clean separation.

Role-Based Access Control

type Role = 'user' | 'admin' | 'moderator';

const routeAccess: Record<string, Role[]> = {
  '/admin': ['admin'],
  '/moderation': ['admin', 'moderator'],
  '/dashboard': ['user', 'admin', 'moderator'],
};

function canAccess(pathname: string, role: Role): boolean {
  const matched = Object.keys(routeAccess).find(r => pathname.startsWith(r));
  if (!matched) return true;
  return routeAccess[matched].includes(role);
}

// Inside middleware, after verifying token:
const role = payload.role as Role;

if (!canAccess(pathname, role)) {
  return NextResponse.redirect(new URL('/unauthorized', request.url));
}

Rate Limiting in Middleware

Middleware is the right place for basic rate limiting before API routes:

const requestCounts = new Map<string, { count: number; reset: number }>();

function rateLimit(ip: string, limit = 60, windowMs = 60_000): boolean {
  const now = Date.now();
  const record = requestCounts.get(ip);

  if (!record || now > record.reset) {
    requestCounts.set(ip, { count: 1, reset: now + windowMs });
    return true;
  }

  if (record.count >= limit) return false;
  record.count++;
  return true;
}

// In middleware, before other checks:
if (request.nextUrl.pathname.startsWith('/api/')) {
  const ip = request.ip ?? 
    request.headers.get('x-forwarded-for')?.split(',')[0] ?? 
    'unknown';

  if (!rateLimit(ip)) {
    return new NextResponse('Too Many Requests', {
      status: 429,
      headers: { 'Retry-After': '60' },
    });
  }
}

Note: in-memory rate limiting only works for single-instance deployments. For multi-instance, use Redis via an edge-compatible client.

Common Pitfalls

Infinite redirect loops. Middleware that protects /login will redirect to /login, which triggers middleware again. Fix: explicitly exclude auth routes from the protected route check, and use the matcher config carefully.

Missing matcher config. Without matcher, middleware runs on /_next/static, /_next/image, and favicon requests. Always set the matcher.

Wrong library for JWT. jsonwebtoken won't run at the edge. Use jose — it's designed for edge environments and has the same JWT capabilities.

Not cleaning up expired tokens. If you redirect on invalid token, also delete the cookie — otherwise the user arrives at the login page with an expired cookie that will fail again if they navigate back.

Testing with expired tokens. Your manual testing probably uses fresh tokens. Write tests specifically for the expired token flow — it's where the most user-visible bugs hide.

Testing

// Tests require NextRequest, not standard fetch mocks
import { NextRequest } from 'next/server';
import { middleware } from '../middleware';

test('unauthenticated → redirect to login', async () => {
  const req = new NextRequest('https://example.com/dashboard');
  const res = await middleware(req);

  expect(res.status).toBe(307);
  const location = res.headers.get('location')!;
  expect(location).toContain('/login');
  expect(location).toContain('redirect=%2Fdashboard');
});

test('authenticated → passes through with user headers', async () => {
  const token = createTestJWT({ sub: 'u-123', role: 'user' });
  const req = new NextRequest('https://example.com/dashboard');
  req.cookies.set('auth-token', token);

  const res = await middleware(req);
  expect(res.status).toBe(200);
});

Summary

Middleware is the right layer for auth because it runs before any route handler, handles the logic once regardless of which protected page is hit, and runs fast at the edge without needing a database call.

The key design decision: middleware verifies whether the user is authenticated and passes context through headers. Server Components and API routes handle what the authenticated user can access and see.

One More Edge Case — Middleware and Static Exports

If you're using next export (static site generation), middleware doesn't run — there's no server. Static exports and middleware are incompatible.

This is usually obvious but catches people who start with dynamic middleware and later try to add static export for performance. If you need static export, move auth logic to the client side or use a CDN-level auth proxy instead of Next.js middleware.

For standard Vercel or server deployments, middleware runs at the edge without issues. The incompatibility only affects the specific case of next export.

Debugging Middleware

Middleware runs at the edge, which means console.log doesn't appear in your terminal the same way server-side logs do. To debug:

// Use edge-compatible logging
export async function middleware(request: NextRequest) {
  // This appears in edge function logs, not terminal
  console.log('Middleware hit:', request.nextUrl.pathname);

  // In Vercel, edge logs appear in the Functions tab
  // Locally, they appear in the terminal with [Middleware] prefix

  // ...rest of middleware
}

Vercel's dashboard shows edge function logs separately from server logs — look in the Functions tab, not the standard log view. Locally, next dev prefixes middleware logs with [Middleware] to distinguish them.

Setting NEXT_PUBLIC_DEBUG=true in local .env and adding conditional verbose logging during development is a common pattern for middleware-heavy applications.

DEV Community: Aon infotech

Dynamic SEO Metadata in Next.js with generateMetadata() — Per-Page Titles, Descriptions, and OG Images

Static Metadata

Dynamic Metadata with generateMetadata()

Open Graph Images

Metadata Inheritance and the Layout Hierarchy

Structured Data for Blog Posts

Canonical URLs

Robots Meta

Summary

Verifying Metadata in Production

Metadata Gotchas

Using cache() for Data Deduplication Without fetch

ISR and On-Demand Revalidation in Next.js App Router — Keeping Static Pages Fresh

How Caching Works in App Router

Setting Revalidation at the Route Level

Generating Static Params

On-Demand Revalidation

revalidatePath

revalidateTag

Combining ISR and On-Demand Revalidation

Testing Cache Behavior

When to Use Each Approach

Revalidation in Server Actions

Summary

Handling Cache Misses Gracefully

Debugging Stale Content

Next.js Server Actions — Form Handling Without API Routes

Defining a Server Action

Basic Form With Server Action

Adding Loading State and Feedback With useFormState and useFormStatus

Server Actions With Zod Validation

Mutations Beyond Forms

When to Use Server Actions vs API Routes

Summary

Optimistic Updates With useOptimistic

Next.js Middleware — Redirects, Auth Guards, and A/B Testing at the Edge

How Middleware Works

Auth Guards — Protecting Routes

Redirects at Scale

Geo-Based Routing

A/B Testing With Middleware

Adding Headers to Requests

What Middleware Is Not For

The Matcher Config — Getting It Right

Summary

Rate Limiting With Middleware

Custom React Hooks — Extracting and Reusing Stateful Logic

The Core Idea

Practical Custom Hook Examples

useLocalStorage — Persisted State

useAsync — Managing Async Operations

useMediaQuery — Responsive Logic in Components

useClickOutside — Dismissing Popups

Rules for Custom Hooks

When to Extract a Custom Hook

Summary

Testing Custom Hooks

Parallel Routes in Next.js App Router — Rendering Multiple Pages in One Layout

The Core Concept — Named Slots

Independent Navigation — The Key Behavior

Default Files — Handling Missing States

Modal Pattern — The Killer Use Case

Intercepting Routes — Paired with Parallel Routes

When to Use Parallel Routes

Loading and Error States Per Slot

Summary

Debugging Common Issues

The File Structure at a Glance

next/image Deep Dive — Optimization, Lazy Loading, and the Props That Actually Matter

What next/image Does By Default

The sizes Prop — The Most Underused Optimization

priority — For Above-the-Fold Images

fill vs Width/Height — When to Use Each

quality — When Default Isn't Right

External Images — The remotePatterns Config

The placeholder Prop — Blur-Up Loading

Checking What's Actually Being Served

Common Mistakes

Summary Table

The `sizes` Prop — The Most Underused Optimization

`priority` — For Above-the-Fold Images

`fill` vs Width/Height — When to Use Each

`quality` — When Default Isn't Right

External Images — The `remotePatterns` Config

The `placeholder` Prop — Blur-Up Loading

The `revalidatePath` vs `revalidateTag` Decision