DEV Community: Aon infotech

Next.js Font Optimization with next/font: No Layout Shift, No External Requests

Aon infotech — Tue, 11 Aug 2026 05:30:34 +0000

Typography is one of the most overlooked performance factors in Next.js apps. Fonts are typically render-blocking — the browser can't display styled text until the font file downloads, leading to either invisible text (FOIT) or a flash of unstyled text (FOUT), and potentially Cumulative Layout Shift if the fallback font's dimensions differ from the loaded font.

Next.js solves this with the next/font module. This covers how it works, the configuration that matters, and the gotchas you'll hit in production.

What next/font Does Differently

Traditional font loading: your CSS requests a font from Google Fonts, the browser fetches it from Google's CDN, and the font renders. This involves an external network request and gives Google visibility into your users' browsers.

next/font intercepts this at build time:

Downloads the font file during the build
Self-hosts it alongside your application
Injects optimized @font-face declarations
Generates a CSS variable or className with the correct font settings The result: no external font requests at runtime, no layout shift, no FOIT/FOUT, and no third-party tracking from font CDNs.

Google Fonts Integration

// app/layout.js
import { Inter, Playfair_Display } from 'next/font/google'

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',      // 'auto' | 'block' | 'swap' | 'fallback' | 'optional'
  variable: '--font-inter', // CSS variable name
})

const playfair = Playfair_Display({
  subsets: ['latin'],
  weight: ['400', '700'],
  style: ['normal', 'italic'],
  variable: '--font-playfair',
})

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={`${inter.variable} ${playfair.variable}`}>
      <body>{children}</body>
    </html>
  )
}

Then in your CSS:

/* globals.css */
body {
  font-family: var(--font-inter), sans-serif;
}

h1, h2, h3 {
  font-family: var(--font-playfair), serif;
}

Or use the className approach directly:

const inter = Inter({ subsets: ['latin'] })

// Apply directly to the element
<p className={inter.className}>Text here</p>

Subset Selection

Fonts contain character sets for every language they support. Loading the full font is wasteful if your app is English-only. The subsets option restricts which character sets are included:

const inter = Inter({
  subsets: ['latin'],           // English, Western European
  // subsets: ['latin', 'latin-ext'], // + Extended Latin
  // subsets: ['latin', 'cyrillic'],  // + Russian, etc.
})

Google Fonts documents available subsets for each font. Restricting to ['latin'] for English-only apps reduces font file size significantly.

font-display Strategy

The display option controls how the browser handles the period between when the font is requested and when it loads:

const inter = Inter({
  subsets: ['latin'],
  display: 'swap', // Recommended for body text
})

The options:

swap — shows fallback immediately, swaps when loaded. CLS risk if metrics differ significantly.
optional — gives the font a very short window (100ms). If not loaded, uses fallback permanently. Best for non-critical fonts on slow connections.
block — blocks rendering briefly. Avoids FOUT but can cause invisible text.
fallback — short block period, then fallback. Middle ground. For most body text: swap. For fonts where you'd rather use the fallback than cause a visible swap: optional.

Size Adjustments and Fallback Optimization

The CLS risk with display: swap comes from fallback font metrics differing from the web font. Next.js handles this automatically with adjustFontFallback and generates a fallback font that matches the web font's line height, size adjust, and ascent/descent.

You can also define custom fallback behavior:

const roboto = Roboto({
  weight: '400',
  subsets: ['latin'],
  display: 'swap',
  adjustFontFallback: true, // Enabled by default
  fallback: ['Helvetica Neue', 'Arial', 'sans-serif'],
})

Self-Hosted Local Fonts

For proprietary fonts or fonts not available on Google:

import localFont from 'next/font/local'

const brandFont = localFont({
  src: [
    {
      path: '../public/fonts/brand-regular.woff2',
      weight: '400',
      style: 'normal',
    },
    {
      path: '../public/fonts/brand-bold.woff2',
      weight: '700',
      style: 'normal',
    },
  ],
  variable: '--font-brand',
  display: 'swap',
})

The font files go in public/fonts/. Prefer .woff2 — it's the most compressed format with universal modern browser support.

Tailwind CSS Integration

If you're using Tailwind, map the CSS variables to Tailwind's fontFamily config:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: ['var(--font-inter)', 'sans-serif'],
        serif: ['var(--font-playfair)', 'serif'],
      },
    },
  },
}

Then use normally in your markup:

<h1 class="font-serif text-4xl">Heading</h1>
<p class="font-sans text-base">Body text</p>

Production Gotchas

Font files are emitted at build time. If you change font configuration, you need to rebuild. Dev server changes don't always hot-reload font configurations — restart if fonts aren't applying.

The variable option is required for CSS variable usage. Without it, you only get the className approach. If you want global font variables accessible across CSS files, set variable.

Google Fonts requires internet during build. In CI environments without outbound internet access, fonts won't download and the build fails. Either pre-download fonts and use localFont, or ensure your build environment has outbound internet.

Multiple weights increase file size proportionally. Each weight you request is a separate font file. Only load the weights you actually use.

Measuring the Impact

Before optimizing fonts, capture your baseline:

CLS score in Core Web Vitals — font swap is one of the most common CLS causes
Network tab in DevTools — look for requests to fonts.googleapis.com or fonts.gstatic.com
Third-party requests in PageSpeed Insights — external font CDN requests show up here After next/font implementation, you should see: third-party font requests eliminated, CLS reduced toward zero from font swap, and LCP potentially improved if the font was previously render-blocking.

For AI-generated content like Pixova's steampunk art generator, typography choices for the blog significantly affect both aesthetics and Core Web Vitals — both worth optimizing.

Next.js Image Optimization: next/image Deep Dive for Production Apps

Aon infotech — Sat, 08 Aug 2026 06:28:08 +0000

Images consistently account for 50–70% of total page weight in most web applications. Next.js ships a built-in next/image component that handles the heavy lifting automatically — but using it correctly means understanding what it actually does, what configuration matters in production, and where the defaults fall short.

What next/image Actually Does

When you use next/image, requests go through Next.js's image optimization API at /_next/image. On each request it:

Converts to WebP or AVIF (significantly smaller than JPEG/PNG)
Resizes to the requested display dimensions
Lazy loads by default
Reserves layout space to prevent Cumulative Layout Shift
Caches the optimized output server-side Self-hosted deployments need sharp for server-side optimization:

npm install sharp

On Vercel, optimization runs at the edge automatically.

Basic Implementation

import Image from 'next/image'
import heroImage from '@/public/hero.jpg'

// Local image — dimensions extracted at build time
export function Hero() {
  return (
    <Image
      src={heroImage}
      alt="Descriptive alt text here"
      priority
    />
  )
}

// Remote image — must specify dimensions
export function ProductCard({ imageUrl }) {
  return (
    <Image
      src={imageUrl}
      alt="Product"
      width={400}
      height={300}
      sizes="(max-width: 768px) 100vw, 400px"
    />
  )
}

The `sizes` Prop — Most Commonly Misused

Without sizes, Next.js generates a single large image. With it, the browser receives multiple sizes and selects the correct one for the current viewport.

// Wrong — browser downloads large image regardless of display size
<Image src={src} alt={alt} width={800} height={600} />

// Correct — sizes match actual CSS rendering
<Image
  src={src}
  alt={alt}
  width={800}
  height={600}
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
/>

The sizes string describes your CSS layout. If the image is full-width on mobile, half-width on tablet, and 800px fixed on desktop, write exactly that.

`fill` for Flexible Containers

When you don't know dimensions ahead of time:

<div className="relative h-64 w-full">
  <Image
    src={imageUrl}
    alt="Cover"
    fill
    className="object-cover"
    sizes="(max-width: 768px) 100vw, 50vw"
  />
</div>

The parent needs position: relative and defined dimensions. fill makes the image absolutely positioned to match the parent.

Priority Loading for LCP

The Largest Contentful Paint image should never be lazy loaded:

// Any image visible on page load — hero, banner, above-fold card
<Image
  src={heroSrc}
  alt="Hero"
  fill
  priority
  sizes="100vw"
/>

priority adds a preload link and disables lazy loading. Don't add it to off-screen images — that wastes bandwidth on content users may not scroll to.

Remote Domains Configuration

Next.js blocks external images by default. Configure remotePatterns in next.config.js:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'images.example.com',
        pathname: '/uploads/**',
      },
      {
        protocol: 'https',
        hostname: '**.cloudinary.com', // wildcard subdomain
      },
    ],
  },
}

Use remotePatterns over the deprecated domains array — it gives you path-level control.

Quality, Format, and Cache Configuration

module.exports = {
  images: {
    quality: 80,                    // default 75 — increase for sharper images
    formats: ['image/avif', 'image/webp'], // AVIF first, WebP fallback
    deviceSizes: [640, 750, 828, 1080, 1200, 1920],
    minimumCacheTTL: 60 * 60 * 24, // cache for 24h instead of default 60s
  },
}

AVIF compresses better than WebP but encodes slower. Browser negotiation handles the format selection — keep both in the array.

Blur Placeholder

// Local image — blur data generated at build time automatically
<Image
  src={productImage}
  alt="Product"
  placeholder="blur"
/>

// Remote image — provide base64 blurDataURL
<Image
  src={remoteUrl}
  alt="Product"
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,/9j/4AAQ..."
  width={800}
  height={600}
/>

The blur shows immediately while the full image loads. Perceived performance improves significantly even when actual load time stays the same.

Production Gotchas

Sharp is not optional for self-hosted apps. Without it, Next.js falls back to a slower path or disables optimization entirely.

Memory watch on high-traffic sites. Each unique URL/size combination gets cached. Applications serving user-uploaded images with unique filenames can exhaust cache memory. Set a reasonable minimumCacheTTL and monitor.

SVGs bypass the optimizer. SVG files are served as-is — the optimizer is designed for raster images. Handle SVGs with SVGR or as static assets.

Build-time vs request-time dimensions. Local imports have their dimensions extracted at build time. Remote URLs need width and height specified in the component or fill layout.

Measuring the Impact

Track these before and after switching to next/image:

LCP score in Core Web Vitals (primary image performance metric)
Total image transfer size in DevTools Network tab filtered by Img
CLS score — proper dimension reservation eliminates most image-related layout shift For most apps serving photographic content, correctly configured next/image reduces image payload by 50–70% and brings CLS to near zero.

For AI-generated imagery like the content at Pixova's free sketch generator, the WebP conversion from PNG source files typically produces 40–60% size reduction — meaningful at scale when thousands of users are loading AI-generated images daily.

Next.js Middleware — Request Interception, Authentication Guards, and A/B Testing

Aon infotech — Wed, 29 Jul 2026 10:02:04 +0000

Middleware in Next.js runs before a request is processed — before the cache is checked, before the route renders, before any server code executes. This makes it the right place for authentication checks, redirects, request modification, and A/B testing logic that needs to apply across multiple routes without being duplicated in each one.

Here's the complete middleware pattern, including auth guards, geographic redirects, A/B testing with cookies, and the performance considerations that determine when middleware is and isn't the right tool — including patterns used in the infrastructure behind ai caricature generation workflows.

Creating Middleware

Create middleware.ts at the project root (same level as app/):

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

export function middleware(request: NextRequest) {
  return NextResponse.next();
}

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

The matcher is critical — middleware that runs on static assets and image optimization requests adds latency for no reason.

Authentication Guard

The most common middleware use: blocking unauthenticated access to protected routes.

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

const protectedPaths = ['/dashboard', '/account', '/settings'];
const authPath = '/login';

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

  const isProtected = protectedPaths.some(path =>
    pathname.startsWith(path)
  );

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

  const token = request.cookies.get('auth-token')?.value;

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

  // Optionally validate token structure here
  // For full JWT validation, use an Edge-compatible library
  return NextResponse.next();
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|api/auth).*)'],
};

The from parameter preserves the original destination — after login, the user can be redirected back to where they were going.

JWT Validation in Middleware

For proper JWT validation, use an Edge-compatible library (standard Node.js crypto isn't available in middleware's Edge runtime):

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { jwtVerify } from 'jose'; // Edge-compatible JWT library

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

async function validateToken(token: string): Promise<boolean> {
  try {
    await jwtVerify(token, JWT_SECRET);
    return true;
  } catch {
    return false;
  }
}

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

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

  const token = request.cookies.get('auth-token')?.value;

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

  return NextResponse.next();
}

jose is Edge-compatible unlike jsonwebtoken, which requires Node.js crypto.

Geographic Redirects

Middleware can read the geo data that Vercel and other platforms inject into requests:

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

  if (country === 'DE') {
    return NextResponse.redirect(new URL('/de', request.url));
  }

  if (country === 'JP') {
    return NextResponse.redirect(new URL('/jp', request.url));
  }

  return NextResponse.next();
}

request.geo is populated by Vercel's edge network. On other platforms, use the CF-IPCountry header (Cloudflare) or similar. In development, request.geo is undefined.

A/B Testing With Cookies

Middleware is ideal for A/B testing because it assigns the variant before any rendering occurs, ensuring the user consistently sees the same variant across page loads:

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

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

function getVariant(request: NextRequest): Variant {
  const existing = request.cookies.get(AB_COOKIE)?.value;
  if (existing === 'control' || existing === 'treatment') {
    return existing;
  }
  return Math.random() < 0.5 ? 'control' : 'treatment';
}

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

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

  const variant = getVariant(request);
  const response = NextResponse.next();

  // Persist the variant
  response.cookies.set(AB_COOKIE, variant, {
    maxAge: 60 * 60 * 24 * 30, // 30 days
    httpOnly: true,
    sameSite: 'lax',
  });

  // Pass variant to the page via header
  response.headers.set('x-ab-variant', variant);

  return response;
}

In the page component, read the header to determine which variant to render:

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

export default function PricingPage() {
  const headersList = headers();
  const variant = headersList.get('x-ab-variant') ?? 'control';

  if (variant === 'treatment') {
    return <PricingV2 />;
  }

  return <PricingV1 />;
}

Request Modification and Header Injection

Middleware can modify requests before they reach route handlers — useful for injecting context that components or API routes need:

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

  // Add the request URL for server components that need it
  requestHeaders.set('x-pathname', request.nextUrl.pathname);

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

The Matcher — Getting It Right

The matcher config determines which requests trigger middleware:

export const config = {
  matcher: [
    // Match all paths except static files and Next.js internals
    '/((?!_next/static|_next/image|favicon.ico).*)',

    // Or: match specific paths only
    '/dashboard/:path*',
    '/account/:path*',

    // Or: match API routes
    '/api/:path*',
  ],
};

Incorrect matchers are the most common middleware bug — middleware running on _next/static paths adds latency to every static asset request.

Performance Considerations

Middleware runs on the Edge runtime, which has constraints:

No Node.js APIs (no fs, no native crypto)
No npm packages that use Node.js internals
Execution time limits (typically under 50ms)

For heavy operations — database queries, complex business logic — don't put them in middleware. Middleware should handle fast operations: cookie reads, header inspection, simple redirects. Anything that requires database access belongs in the route handler or Server Component.

When NOT to Use Middleware

Middleware is not the right place for:

Database queries. Every request that triggers middleware will wait for the database call. Use middleware for fast cookie/header checks; move database calls to Server Components or route handlers where caching applies.

Heavy business logic. Complex calculations or multi-step operations belong in server-side code where they can be cached and where the full Node.js environment is available.

Per-request secret handling. Don't access environment variables containing secrets in middleware for operations that could be handled with a simple cookie check. Keep middleware logic minimal and fast.

Image optimization. The _next/image path should be excluded from middleware matchers — running middleware on image optimization requests adds latency to every image load.

The mental model: middleware handles routing decisions. Route handlers and Server Components handle business logic and data fetching.

Summary

Middleware intercepts requests before rendering — right for auth checks, redirects, A/B variant assignment, and request header injection. Create at project root as middleware.ts. Use the Edge-compatible jose for JWT validation. Always configure matcher to exclude static assets. Keep logic fast — no database calls, no heavy computation.

Testing Middleware Locally

Middleware runs in the Edge runtime even during local development with next dev. Test by:

# Check which paths trigger middleware with a simple log
export function middleware(request: NextRequest) {
  console.log('[Middleware]', request.method, request.nextUrl.pathname);
  return NextResponse.next();
}

For auth middleware specifically: test with an expired/invalid token, a missing token, and a valid token to cover the three cases that matter. Also test that the from redirect parameter round-trips correctly through the login flow.

Route Groups in Next.js App Router — Organizing Layouts Without Changing URLs

Aon infotech — Wed, 22 Jul 2026 09:25:33 +0000

Route Groups let you organize your Next.js App Router file structure into logical sections without those sections appearing in the URL. A route at app/(marketing)/about/page.tsx serves at /about — the (marketing) group is invisible to the browser. This matters a lot when you need different layouts for different parts of your app without creating URL segments for the layout difference.

Here's the complete pattern, including nested groups, group-specific layouts, and the use cases that actually benefit from this approach — including the content organization used at content organization approach.

The Basics

Create a route group by wrapping a folder name in parentheses:

app/
├── (marketing)/        ← Route group — doesn't appear in URL
│   ├── layout.tsx      ← Layout for marketing pages only
│   ├── about/
│   │   └── page.tsx    ← Serves at /about
│   ├── pricing/
│   │   └── page.tsx    ← Serves at /pricing
│   └── blog/
│       └── page.tsx    ← Serves at /blog
├── (dashboard)/        ← Different route group
│   ├── layout.tsx      ← Different layout for dashboard
│   ├── overview/
│   │   └── page.tsx    ← Serves at /overview
│   └── settings/
│       └── page.tsx    ← Serves at /settings
└── layout.tsx          ← Root layout (applies to everything)

The marketing group has a layout with a public header and footer. The dashboard group has a layout with a sidebar and authenticated navigation. Both serve routes at the same URL level without the group name appearing anywhere.

Group-Specific Layouts

The main reason to use route groups: different layouts for different sections of the app without creating extra URL nesting.

// app/(marketing)/layout.tsx
export default function MarketingLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      <PublicHeader />
      <main className="max-w-7xl mx-auto px-4">{children}</main>
      <PublicFooter />
    </>
  );
}

// app/(dashboard)/layout.tsx
import { redirect } from 'next/navigation';
import { getSession } from '@/lib/auth';

export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const session = await getSession();
  if (!session) redirect('/login');

  return (
    <div className="flex h-screen">
      <DashboardSidebar />
      <main className="flex-1 overflow-auto p-6">{children}</main>
    </div>
  );
}

The auth check in the dashboard layout applies to every route in the group — cleaner than adding it to each individual page.

Opting Out of a Layout

If you have a route that doesn't belong in any group, or needs its own layout, place it outside the groups:

app/
├── (marketing)/
│   └── ...
├── (dashboard)/
│   └── ...
├── login/             ← No group — uses only root layout
│   └── page.tsx       ← Serves at /login, no public header or dashboard sidebar
└── layout.tsx         ← Root layout only

The login page uses only the root layout. Neither the marketing header/footer nor the dashboard sidebar applies to it.

Multiple Root Layouts

Route groups can each have their own separate root layout — including their own <html> and <body> tags. This is used when different parts of an app are so different they need completely separate HTML structures:

app/
├── (app)/
│   ├── layout.tsx     ← Has <html>, <body>, loads app fonts/styles
│   └── dashboard/
│       └── page.tsx
├── (marketing)/
│   ├── layout.tsx     ← Has <html>, <body>, loads marketing fonts/styles
│   └── home/
│       └── page.tsx

When using multiple root layouts, each group's layout must include <html> and <body> tags, and there should be no root app/layout.tsx. This is a more advanced pattern — typically used when an app and its marketing site share a codebase but have genuinely different visual identities.

Shared Layouts Across Groups

Sometimes pages from different groups need the same layout component without being in the same group. A few options:

Create a shared component and import it in both group layouts:

// components/SiteHeader.tsx
export function SiteHeader() {
  return <header>...</header>;
}

// app/(marketing)/layout.tsx
import { SiteHeader } from '@/components/SiteHeader';

// app/(dashboard)/layout.tsx
// Also import SiteHeader if it should appear here too

Use a parent layout — the root layout applies to all routes regardless of group:

// app/layout.tsx — applies everywhere
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <SiteHeader />  {/* Appears on all pages */}
        {children}
      </body>
    </html>
  );
}

Common Use Cases

Marketing vs. App: Separate layouts for a public marketing site and the authenticated app within the same Next.js project.

Admin vs. User: Different navigation and permissions for admin users versus regular users.

Multi-tenant apps: Different brand layouts for different tenant segments sharing the same codebase.

A/B testing layouts: Two groups with the same routes but different layout implementations, controlled by a middleware that rewrites to one group or the other.

Organizing large projects: Even without different layouts, groups help organize large projects into logical sections. The URL structure stays clean while the file structure communicates meaning.

What Route Groups Are Not

Route groups don't create URL segments — that's the whole point. If you want a URL like /dashboard/overview, you need the dashboard folder in your file structure normally, not as a group. Groups are for layout organization and code organization, not for URL structuring.

Debugging Route Group Issues

Layout not applying: Check that the route file is inside the group folder, not just that the group folder exists. A page at app/(marketing)/page.tsx uses the marketing layout. A page at app/page.tsx doesn't.

Unexpected 404: Route groups can't have conflicting routes. If app/(a)/about/page.tsx and app/(b)/about/page.tsx both exist, Next.js will error — two routes resolving to /about is a conflict regardless of which groups they're in.

Layout inheritance confusion: The root layout always applies. Group layouts apply additionally for routes inside the group. There's no way to "opt out" of the root layout for a specific group — if you need that, use multiple root layouts as described above.

Navigating between groups: Client-side navigation between routes in different groups works normally. The user navigating from /about (in the marketing group) to /dashboard (in the dashboard group) triggers a full layout swap — the marketing layout unmounts and the dashboard layout mounts. This is expected behavior.

Summary

Route groups (parentheses-wrapped folders) organize your app's file structure without affecting URLs. Their primary use is applying different layouts to different sections of an app — a marketing layout for public pages, a dashboard layout for authenticated pages — without the section name appearing in the URL. Secondary use: organizing large projects into logical code groups even when the layout difference doesn't apply.

TypeScript Types for Route Group Layouts

When writing group layouts with TypeScript, the props type is consistent across all layouts:

// Works for any group layout
type LayoutProps = {
  children: React.ReactNode;
};

// With parallel routes in a group
type GroupLayoutWithParallelProps = {
  children: React.ReactNode;
  modal: React.ReactNode;   // @modal parallel route
  sidebar: React.ReactNode; // @sidebar parallel route
};

// With params when the group contains dynamic routes
type DynamicGroupLayoutProps = {
  children: React.ReactNode;
  params: {
    // If the GROUP contains a dynamic segment
    // e.g. app/(dashboard)/[orgId]/settings/
    orgId: string;
  };
};

The group itself never contributes a param — only actual named segments in square brackets do. Route groups are invisible to TypeScript params just as they're invisible to URLs.

When Not to Use Route Groups

Route groups add a layer of indirection that makes the file system harder to navigate for new contributors. If you're not getting a layout benefit from the group — if all routes in the group use the same layout as adjacent routes — the group is adding complexity without adding value.

Use route groups when: you need different layouts for different sections, you're organizing a large project into logical units, or you're implementing multiple root layouts.

Skip route groups when: you're using them purely to add nested folders for aesthetic reasons, all routes use the same layout anyway, or the project is small enough that the organization overhead costs more than it saves.

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.

DEV Community: Aon infotech

Next.js Font Optimization with next/font: No Layout Shift, No External Requests

What next/font Does Differently

Google Fonts Integration

Subset Selection

font-display Strategy

Size Adjustments and Fallback Optimization

Self-Hosted Local Fonts

Tailwind CSS Integration

Production Gotchas

Measuring the Impact

Next.js Image Optimization: next/image Deep Dive for Production Apps

What next/image Actually Does

Basic Implementation

The sizes Prop — Most Commonly Misused

fill for Flexible Containers

Priority Loading for LCP

Remote Domains Configuration

Quality, Format, and Cache Configuration

Blur Placeholder

Production Gotchas

Measuring the Impact

Next.js Middleware — Request Interception, Authentication Guards, and A/B Testing

Creating Middleware

Authentication Guard

JWT Validation in Middleware

Geographic Redirects

A/B Testing With Cookies

Request Modification and Header Injection

The Matcher — Getting It Right

Performance Considerations

When NOT to Use Middleware

Summary

Testing Middleware Locally

Route Groups in Next.js App Router — Organizing Layouts Without Changing URLs

The Basics

Group-Specific Layouts

Opting Out of a Layout

Multiple Root Layouts

Shared Layouts Across Groups

Common Use Cases

What Route Groups Are Not

Debugging Route Group Issues

Summary

TypeScript Types for Route Group Layouts

When Not to Use Route Groups

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

The `sizes` Prop — Most Commonly Misused

`fill` for Flexible Containers

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