Next.js 16 App Router Performance Patterns: Server Actions, Streaming & Turbopack Deep Dive

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

const nextConfig: NextConfig = {
  // Enables the `use cache` model + PPR semantics
  cacheComponents: true,

  // React Compiler 1.x — trades build time for fewer client re-renders
  reactCompiler: true,

  experimental: {
    // Warm restarts across dev-server process boundaries
    turbopackFileSystemCacheForDev: true,
  },

  turbopack: {
    resolveAlias: {
      '@': './src',
    },
    rules: {
      // Turbopack's loader rule shape (unchanged from `experimental.turbo`)
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },

  serverActions: {
    bodySizeLimit: '2mb',
    allowedOrigins: ['app.example.com'],
  },

  images: {
    qualities: [60, 75, 90],
    minimumCacheTTL: 14400,
  },

  logging: { fetches: { fullUrl: true } },
};

export default nextConfig;

#!/usr/bin/env bash
set -euo pipefail

for i in 1 2 3; do
  rm -rf .next node_modules/.cache
  start=$(date +%s%3N)
  pnpm next build > /tmp/build-$i.log 2>&1
  end=$(date +%s%3N)
  echo "run $i: $((end - start)) ms"
done

# Route-level cost breakdown (Next.js 16 build output)
grep -E '^[├└┌│ ]+[○ƒ●]' /tmp/build-1.log | head -n 40

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

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

const CreateComment = z.object({
  postId: z.string().uuid(),
  body: z.string().min(1).max(2_000),
});

export type ActionState =
  | { status: 'idle' }
  | { status: 'error'; message: string }
  | { status: 'success'; id: string };

export async function createComment(
  _prev: ActionState,
  formData: FormData,
): Promise<ActionState> {
  const session = await auth();
  if (!session?.user) return { status: 'error', message: 'Unauthorized' };

  const parsed = CreateComment.safeParse({
    postId: formData.get('postId'),
    body: formData.get('body'),
  });

  if (!parsed.success) {
    return { status: 'error', message: parsed.error.issues[0]?.message ?? 'Invalid input' };
  }

  try {
    const comment = await db.comment.create({
      data: { ...parsed.data, authorId: session.user.id },
      select: { id: true },
    });

    // Surgical invalidation: only this post's cached slices are dropped.
    // Prefer updateTag in actions when the user must read their own write;
    // revalidateTag remains the choice for deferred, staleness-tolerant data.
    updateTag(`post:${parsed.data.postId}`);

    return { status: 'success', id: comment.id };
  } catch (err) {
    console.error('createComment failed', err);
    return { status: 'error', message: 'Could not save comment' };
  }
}

// app/posts/[slug]/comment-form.tsx
'use client';

import { useActionState, useOptimistic, useRef, startTransition } from 'react';
import { createComment, type ActionState } from '@/app/actions/comments';

const initialState: ActionState = { status: 'idle' };

type OptimisticComment = { id: string; body: string; pending: true };

export function CommentForm({
  postId,
  comments,
}: {
  postId: string;
  comments: Array<{ id: string; body: string }>;
}) {
  const formRef = useRef<HTMLFormElement>(null);
  const [state, formAction, isPending] = useActionState(createComment, initialState);
  const [optimistic, addOptimistic] = useOptimistic(
    comments,
    (current, next: OptimisticComment) => [...current, next],
  );

  return (
    <section>
      <ul>
        {optimistic.map((c) => (
          <li key={c.id} style={{ opacity: 'pending' in c ? 0.6 : 1 }}>
            {c.body}
          </li>
        ))}
      </ul>

      <form
        ref={formRef}
        action={(formData) => {
          // Render the optimistic row before the network round trip begins.
          startTransition(() => {
            addOptimistic({
              id: `optimistic-${Date.now()}`,
              body: String(formData.get('body') ?? ''),
              pending: true,
            });
          });
          formAction(formData);
          formRef.current?.reset();
        }}
      >
        <input type="hidden" name="postId" value={postId} />
        <textarea name="body" required maxLength={2000} aria-label="Comment" />
        <button type="submit" disabled={isPending}>
          {isPending ? 'Posting…' : 'Post'}
        </button>
        {state.status === 'error' && <p role="alert">{state.message}</p>}
      </form>
    </section>
  );
}

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

import { after } from 'next/server';
import { auth } from '@/lib/auth';
import { db } from '@/lib/db';
import { analytics } from '@/lib/analytics';

export async function placeOrder(cartId: string) {
  const session = await auth();
  if (!session?.user) throw new Error('Unauthorized');

  const order = await db.order.create({
    data: { cartId, userId: session.user.id },
    select: { id: true, totalCents: true },
  });

  // Runs after the response is flushed — does not inflate action latency.
  after(async () => {
    await analytics.track('order_placed', {
      orderId: order.id,
      totalCents: order.totalCents,
    });
  });

  return { orderId: order.id };
}

// app/posts/[slug]/page.tsx
import { Suspense } from 'react';
import { notFound } from 'next/navigation';
import { getPost, getComments, getRelated } from '@/lib/data';

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  // `params` is a Promise in Next.js 16 — no sync access.
  const { slug } = await params;
  const post = await getPost(slug);
  if (!post) notFound();

  return (
    <article>
      {/* LCP candidates render in the shell, never behind a fallback */}
      <h1>{post.title}</h1>
      <p>{post.excerpt}</p>

      {/* Secondary content streams in as it resolves */}
      <Suspense fallback={<CommentsSkeleton rows={3} />}>
        <Comments postId={post.id} />
      </Suspense>
      <Suspense fallback={<RelatedSkeleton />}>
        <Related postId={post.id} />
      </Suspense>
    </article>
  );
}

async function Comments({ postId }: { postId: string }) {
  const comments = await getComments(postId);
  return (
    <ul>
      {comments.map((c) => (
        <li key={c.id}>{c.body}</li>
      ))}
    </ul>
  );
}

// lib/data.ts
import { cacheLife, cacheTag } from 'next/cache';
import { db } from '@/lib/db';

export async function getPost(slug: string) {
  'use cache';
  cacheLife('minutes');      // named profile: revalidate window + stale-while-revalidate
  cacheTag(`post:${slug}`);  // coordinates with updateTag / revalidateTag

  return db.post.findUnique({
    where: { slug },
    include: { author: true },
  });
}

// components/nav-link.tsx
'use client';

import Link, { useLinkStatus } from 'next/link';
import type { ReactNode } from 'react';

function PendingIndicator() {
  const { pending } = useLinkStatus();
  return pending ? <span className="spinner" aria-hidden="true" /> : null;
}

export function NavLink({ href, children }: { href: string; children: ReactNode }) {
  return (
    <Link href={href} prefetch>
      {children}
      <PendingIndicator />
    </Link>
  );
}

// app/_components/web-vitals.tsx
'use client';

import { useReportWebVitals } from 'next/web-vitals';

export function WebVitals() {
  useReportWebVitals((metric) => {
    const payload = JSON.stringify({
      id: metric.id,
      name: metric.name,
      value: metric.value,
      rating: metric.rating,
      delta: metric.delta,
      path: window.location.pathname,
      navigationType: metric.navigationType,
    });

    // sendBeacon survives page unload — critical for LCP/CLS on exits
    navigator.sendBeacon('/api/vitals', payload);
  });

  return null;
}

// app/api/vitals/route.ts
import { NextResponse, type NextRequest } from 'next/server';

export async function POST(req: NextRequest) {
  const raw = await req.text();
  if (raw.length > 4_096) return new NextResponse(null, { status: 413 });

  try {
    const metric = JSON.parse(raw) as { name: string; value: number; rating: string };
    if (typeof metric.value !== 'number' || !Number.isFinite(metric.value)) {
      return new NextResponse(null, { status: 400 });
    }
    // Ship to your RUM sink (BigQuery, ClickHouse, Datadog, …)
    console.log('vital', JSON.stringify(metric));
  } catch {
    return new NextResponse(null, { status: 400 });
  }

  return new NextResponse(null, { status: 204 });
}