Next.js 16 App Router: Production Patterns and Pitfalls

The Next.js App Router fundamentally changed how we build React applications, and by Next.js 16 the patterns have matured into something genuinely production-ready. But the conceptual shift from Pages Router is steep — server components, partial prerendering, nested layouts, and a completely redesigned data fetching model all require mental model rewiring that documentation alone can't fully convey.

This guide covers the patterns that actually matter in production: the ones that prevent cache poisoning, eliminate unnecessary client bundles, and keep your Core Web Vitals green at scale. We'll pull from the experience of building a 249-page Next.js 16 application with 11-locale i18n, dynamic OG images, and server-side rendering for 5,577 MDX content files.

Key Takeaways

• Never use export const metadata on pages that need locale-aware SEO — always use generateMetadata()
• Server Components are the default; only add 'use client' when you actually need interactivity
• loading.tsx and error.tsx colocate with their route segment, not at the root
• The proxy.ts file is Next.js 16's middleware — don't create both middleware.ts AND proxy.ts
• fetch() in Server Components automatically deduplicates identical requests within the same render
• unstable_cache with tags enables surgical cache invalidation without revalidating everything
• generateStaticParams() is required for dynamic routes you want to statically generate at build time
• JSON-LD structured data must sanitize script breakouts using unicode encoding

---

The Server Component Mental Model

The single biggest mistake developers make with the App Router is reaching for 'use client' too early. In Next.js 16, every component in the app/ directory is a Server Component by default. This is the right default — Server Components render on the server, have zero JavaScript bundle impact, and can directly access databases and APIs.

The rule: push 'use client' to the leaves of your component tree. A page can be a Server Component that fetches data and passes it to a thin Client Component shell that handles interactions.

// app/[locale]/blog/[slug]/page.tsx — Server Component (no directive needed)
import { getBlogPost } from '@/lib/blog';
import { BlogContent } from '@/components/blog/blog-content'; // Client Component

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

  if (!post) notFound();

  return (
    <article>
      <h1>{post.title}</h1>
      {/* Server Component — no JS sent to browser */}
      <PostMeta author={post.author} date={post.date} />
      {/* Client Component — only this file sent as JS */}
      <BlogContent content={post.content} />
    </article>
  );
}

// components/blog/blog-content.tsx — Client Component
'use client';

import { useState } from 'react';

export function BlogContent({ content }: { content: string }) {
  const [expanded, setExpanded] = useState(false);

  return (
    <div>
      <div>{content}</div>
      {/* Client-side interactivity lives here */}
    </div>
  );
}

The key insight: BlogContent sends JavaScript to the browser. PostMeta does not. Every unnecessary 'use client' directive inflates your bundle.

---

generateMetadata Over Static Metadata

Static export const metadata is tempting for its simplicity, but it cannot be locale-aware, cannot access route params, and cannot fetch data. For any real application, generateMetadata() is the only correct choice:

// app/[locale]/blog/[slug]/page.tsx
import type { Metadata } from 'next';
import { getTranslations } from 'next-intl/server';

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string; locale: string }>;
}): Promise<Metadata> {
  const { slug, locale } = await params;
  const post = await getBlogPost(slug, locale);

  if (!post) return {};

  const locales = ['en', 'zh', 'es', 'ar', 'pt', 'fr', 'de', 'ja', 'tr', 'hi', 'ur'];

  return {
    title: post.title,
    description: post.description,
    alternates: {
      canonical: `https://ecosire.com/${locale === 'en' ? '' : locale + '/'}blog/${slug}`,
      languages: Object.fromEntries(
        locales.map((loc) => [
          loc,
          `https://ecosire.com/${loc === 'en' ? '' : loc + '/'}blog/${slug}`,
        ])
      ),
    },
    openGraph: {
      title: post.title,
      description: post.description,
      images: [`/api/og/blog/${slug}?locale=${locale}`],
      type: 'article',
      publishedTime: post.date,
    },
  };
}

The alternates.languages field generates hreflang tags for every locale — essential for multilingual SEO. Search engines use these to serve the correct language version to each user.

---

Nested Layouts and Shared State

The App Router's nested layout system is powerful but has a non-obvious constraint: layouts cannot pass data to their children via props. The workaround is either React Context (Client Components only) or fetching data independently at each level.

app/
  [locale]/
    layout.tsx          <- Locale layout: fonts, i18n provider, theme
    page.tsx            <- Homepage
    blog/
      layout.tsx        <- Blog layout: sidebar, breadcrumbs
      page.tsx          <- Blog list
      [slug]/
        layout.tsx      <- Post layout: reading progress, TOC
        page.tsx        <- Post content
        loading.tsx     <- Skeleton while post loads
        error.tsx       <- Error boundary for this segment

Each layout.tsx wraps its children independently. Data fetched in a parent layout is not automatically available to children — each component that needs data fetches it independently. Next.js 16 deduplicates identical fetch() calls within a render cycle, so this is not as expensive as it sounds.

// app/[locale]/layout.tsx
import { NextIntlClientProvider } from 'next-intl';
import { getMessages } from 'next-intl/server';

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;
  const messages = await getMessages();

  return (
    <html lang={locale} dir={['ar', 'ur'].includes(locale) ? 'rtl' : 'ltr'}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

---

Caching Strategy: The Four Layers

Next.js 16 has four distinct caching layers. Understanding all four is required to reason about why a page is or isn't updating:

1. Request Memoization — Same fetch() URL within one render cycle is called once. Automatic, no configuration.

2. Data Cache — Persistent across requests. fetch() responses are cached indefinitely by default.

// Force revalidation every hour
const data = await fetch('/api/posts', { next: { revalidate: 3600 } });

// Never cache (equivalent to SSR)
const data = await fetch('/api/posts', { cache: 'no-store' });

3. Full Route Cache — Static HTML and RSC payload cached at build time for static routes.

4. Router Cache — Client-side cache of visited routes. Persists for the browser session.

For database queries (non-fetch), use unstable_cache:

import { unstable_cache } from 'next/cache';

const getCachedBlogPosts = unstable_cache(
  async (locale: string) => {
    return db.select().from(posts).where(eq(posts.locale, locale));
  },
  ['blog-posts'], // Cache key
  {
    revalidate: 3600, // Revalidate hourly
    tags: ['blog'], // Tag for manual invalidation
  }
);

// Invalidate from a Server Action or Route Handler:
import { revalidateTag } from 'next/cache';
revalidateTag('blog'); // All blog-tagged caches cleared

---

Error Boundaries: Two Levels Required

Production applications need two error boundaries: one for locale-aware pages and one global fallback for root-level errors.

// app/[locale]/error.tsx — Locale-level error boundary
'use client';

import { useTranslations } from 'next-intl';
import { useEffect } from 'react';

export default function LocaleError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  const t = useTranslations('errors');

  useEffect(() => {
    // Log to error tracking service
    console.error(error);
  }, [error]);

  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <h2>{t('title')}</h2>
      <p>{t('description')}</p>
      <button onClick={reset}>{t('retry')}</button>
    </div>
  );
}

// app/global-error.tsx — Root fallback (no i18n available here)
'use client';

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  // Cannot use useTranslations here — no NextIntlClientProvider above
  // Use inline styles — no Tailwind in root error boundaries
  return (
    <html>
      <body>
        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', padding: '2rem' }}>
          <h2 style={{ fontSize: '1.5rem', fontWeight: 'bold' }}>Something went wrong</h2>
          <button
            onClick={reset}
            style={{ marginTop: '1rem', padding: '0.5rem 1rem', cursor: 'pointer' }}
          >
            Try again
          </button>
        </div>
      </body>
    </html>
  );
}

The global-error.tsx replaces the root layout.tsx when it fires, so it must include <html> and <body> tags. It cannot access context providers that live in the layout — no i18n, no theme, no auth context.

---

Middleware: proxy.ts vs middleware.ts

Next.js uses middleware.ts (or middleware.js) for edge middleware. In a project using next-intl v4, the middleware setup often gets renamed to proxy.ts and re-exported, creating a critical pitfall: do not create both middleware.ts and proxy.ts. Having both causes a build error.

The correct pattern for combining i18n with auth protection:

// src/proxy.ts — This IS the Next.js middleware
import createMiddleware from 'next-intl/middleware';
import { NextRequest, NextResponse } from 'next/server';
import { routing } from './i18n/routing';

const intlMiddleware = createMiddleware(routing);

const protectedPaths = ['/dashboard', '/portal'];

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

  // Check auth for protected paths
  const isProtected = protectedPaths.some((path) =>
    pathname.includes(path)
  );

  if (isProtected) {
    const token = request.cookies.get('ecosire_auth');
    if (!token) {
      const url = request.nextUrl.clone();
      url.pathname = '/auth/login';
      // Prevent open redirect — never allow // prefix
      const redirect = pathname.startsWith('//') ? '/' : pathname;
      url.searchParams.set('redirect', redirect);
      return NextResponse.redirect(url);
    }
  }

  return intlMiddleware(request);
}

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

This single file handles both i18n locale detection and auth protection. The config.matcher excludes static files, API routes, and Next.js internals.

---

JSON-LD Structured Data Security

JSON-LD scripts are a common XSS vector. If your data contains a closing script tag, it can break out of the script block. The fix is mandatory — encode the less-than character:

// components/seo/JsonLd.tsx
interface JsonLdProps {
  data: Record<string, unknown>;
}

export function JsonLd({ data }: JsonLdProps) {
  // Sanitize script tag breakout attempts by encoding '<' as unicode
  const json = JSON.stringify(data).replace(/</g, '\\u003c');

  return (
    <script
      type="application/ld+json"
      // Safe: content is JSON-serialized and sanitized above
      suppressHydrationWarning
      ref={(el) => { if (el) el.textContent = json; }}
    />
  );
}

Usage in a page:

<JsonLd
  data={{
    '@context': 'https://schema.org',
    '@type': 'BlogPosting',
    headline: post.title,
    description: post.description,
    inLanguage: locale,
    author: {
      '@type': 'Organization',
      name: 'ECOSIRE',
    },
  }}
/>

The inLanguage field is essential for multilingual SEO — it tells AI crawlers and search engines which language the content is in, improving ranking accuracy for non-English queries.

---

Dynamic OG Images

Next.js 16's ImageResponse API generates per-page OG images at the edge. The setup for blog posts:

// app/api/og/blog/[slug]/route.tsx
import { ImageResponse } from 'next/og';

export const runtime = 'edge';

export async function GET(
  request: Request,
  { params }: { params: Promise<{ slug: string }> }
) {
  const { slug } = await params;
  const post = await getPostMeta(slug);

  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          flexDirection: 'column',
          justifyContent: 'flex-end',
          width: '100%',
          height: '100%',
          background: 'linear-gradient(135deg, #0a0a0a 0%, #1a1a2e 100%)',
          padding: '60px',
        }}
      >
        <div style={{ fontSize: 48, fontWeight: 700, color: 'white', lineHeight: 1.2 }}>
          {post.title}
        </div>
        <div style={{ fontSize: 24, color: '#94a3b8', marginTop: 20 }}>
          {post.description}
        </div>
      </div>
    ),
    { width: 1200, height: 630 }
  );
}

---

Common Pitfalls and Solutions

Pitfall 1: Fetching data in Client Components when Server Components would work

If a component only displays data and doesn't need React state or browser APIs, it should be a Server Component. Adding 'use client' forces everything it imports into the client bundle.

Pitfall 2: Missing Suspense boundaries around async Server Components

// Without Suspense — entire page blocks until data loads
export default async function Page() {
  const data = await slowFetch(); // 2 seconds
  return <div>{data}</div>;
}

// With Suspense — page streams, slow part shows skeleton
export default function Page() {
  return (
    <Suspense fallback={<DataSkeleton />}>
      <SlowDataComponent />
    </Suspense>
  );
}

Pitfall 3: Using cookies() or headers() in cached functions

cookies() and headers() are dynamic APIs that opt the route into dynamic rendering. Using them inside an unstable_cache callback silently breaks the cache.

Pitfall 4: Forgetting to await params in Next.js 16

In Next.js 16, params is now a Promise. Forgetting await causes runtime errors:

// Next.js 15 — params was synchronous
export default function Page({ params }: { params: { slug: string } }) {
  const { slug } = params;
}

// Next.js 16 — params is async
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params; // Required
}

---

Frequently Asked Questions

When should I use generateStaticParams() vs. dynamic rendering?

Use generateStaticParams() for content that changes infrequently (blog posts, product pages, documentation). This generates static HTML at build time with zero runtime cost. Use dynamic rendering for personalized content, real-time data, or pages with thousands of variants where build time would be prohibitive. Combine both with ISR (revalidate) for content that changes occasionally.

How do I handle authentication in the App Router?

Store auth tokens in HttpOnly cookies — never localStorage or sessionStorage. Use middleware (proxy.ts) to check cookie presence for protected routes. In Server Components, read cookies with cookies() from next/headers. Pass user data from server to client via props or React Context, never by re-reading the cookie in Client Components.

What's the difference between loading.tsx and Suspense?

loading.tsx is a special file that Next.js automatically wraps in a Suspense boundary for the entire route segment. It shows immediately while the segment's async content loads. Manual Suspense boundaries give you finer control — you can show different skeletons for different parts of a page. Both use the same underlying React Suspense mechanism.

How do I share state between Server and Client Components?

You cannot — Server Components render once and have no runtime state. Pass data from Server to Client via props. For client-side state that needs to persist across navigations, use URL search params (for shareable state), Zustand or Redux (for ephemeral state), or cookies (for user preferences). Never try to import a Client Component's state into a Server Component.

How do I set up Turbopack for development?

Add --turbo to your dev script: "dev": "next dev --turbo". Turbopack is Next.js 16's Rust-based bundler with significantly faster cold starts and HMR. It's production-ready for most projects but has some webpack plugin incompatibilities. Check your specific dependencies against the Turbopack compatibility list before switching.

---

Next Steps

Building a production Next.js 16 application that handles 11 locales, thousands of pages, and enterprise-grade performance requirements is a significant engineering undertaking. ECOSIRE's frontend team has shipped exactly this — a 249-page Next.js 16 platform with multilingual SEO, dynamic OG images, and sub-second response times.

If you're scaling your Next.js application or need enterprise frontend engineering support, explore our development services to see how we can help.