Nextjs Performance

Next.js Performance

Real performance optimization for Next.js App Router. Not "add lazy loading" — actual diagnosis workflows, rendering-strategy decisions, and production caching patterns.

Version baseline (as of Jun 2026): Next.js 16.x is current (16.2.x LTS); examples target Next.js 15/16. Where 15 and 16 diverge (image priority→preload, minimumCacheTTL default, unstable_cache→'use cache', removed NextRequest.geo), both are called out. Verify versions/APIs at https://nextjs.org/docs and release notes at https://nextjs.org/blog. For SEO/metadata performance see the sibling seo-geo skill.

---

1. Core Web Vitals — What Actually Causes Problems

LCP (Largest Contentful Paint) — Target: `

1. Slow TTFB (> 800ms means LCP can't hit 2.5s)
2. LCP image not preloaded (Next 16 preload / Next 15 priority)
3. Client-side data fetching delaying content

// Fix 1: Preload the LCP hero image
import Image from 'next/image';

export function Hero() {
  return (
     into  so the
      // browser fetches from the first HTML chunk. It does NOT set fetchpriority;
      // pass `fetchPriority="high"` separately if you need it (don't combine with
      // `loading`). Next.js 15 still uses `priority` (deprecated in 16) — same idea.
      preload
      fetchPriority="high"
      sizes="100vw"   // Don't serve a 3840px source to a 390px phone
      quality={85}    // Good quality/size tradeoff for photos
    />
  );
}
// ONE LCP image per route. Preloading several images competes for bandwidth and
// can regress LCP. Confirm the real LCP element first (see §8, "Confirm the LCP element").

// Fix 2: Stream server components — don't block on slow data
import { Suspense } from 'react';

export default function Page() {
  return (
    <>
        {/* Renders immediately */}
      }>
          {/* Streams when ready */}
      
    
  );
}

INP (Interaction to Next Paint) — Target: {

setQuery(value); // Urgent: update input startTransition(() => { setFiltered(items.filter(i => i.name.includes(value))); // Deferred }); };

return ( <> handleSearch(e.target.value)} />

{filtered.map(item => )}

); }

// Fix 2: Virtualize long lists import { useVirtualizer } from '@tanstack/react-virtual'; import { useRef } from 'react';

function VirtualList({ items }: { items: Item[] }) { const parentRef = useRef(null); const virtualizer = useVirtualizer({ count: items.length, getScrollElement: () => parentRef.current, estimateSize: () => 60, overscan: 5, });

return (

{virtualizer.getVirtualItems().map(vi => (

))}

); }

### CLS (Cumulative Layout Shift) — Target: 

// Reserve space for dynamic content
function AdBanner() {
  return (
    
      }>
        
      
    
  );
}

// Font: use next/font with size adjustment
import localFont from 'next/font/local';
const brand = localFont({
  src: './fonts/Brand.woff2',
  display: 'swap',
  adjustFontFallback: 'Arial',  // Matches metrics, prevents shift
});

---

2. Rendering Strategy Decision Matrix

| Strategy | TTFB | LCP | Freshness | Use When | |----------|------|-----|-----------|----------| | SSG | ~50ms | Excellent | Build-time | Marketing, docs, blog | | ISR | ~50ms | Excellent | Seconds-hours | Product pages, listings | | SSR | 200-1000ms | Good | Real-time | Dashboards, personalized | | Client | Fast shell | Poor | Real-time | Admin panels, interactive | | Streaming | ~100ms | Good | Real-time | Mix of fast + slow data |

ISR in Practice

// app/products/[slug]/page.tsx
export const revalidate = 60;  // Revalidate every 60s

export async function generateStaticParams() {
  const products = await db.product.findMany({
    orderBy: { views: 'desc' }, take: 1000, select: { slug: true },
  });
  return products.map(p => ({ slug: p.slug }));
}

export default async function ProductPage({ params }: { params: Promise }) {
  const { slug } = await params;
  const product = await db.product.findUnique({ where: { slug } });
  if (!product) notFound();
  return ;
}

On-Demand Revalidation

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

export async function POST(req: NextRequest) {
  const token = req.headers.get('x-revalidation-token');
  if (token !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const { path, tag } = await req.json();
  if (tag) revalidateTag(tag);
  else if (path) revalidatePath(path);

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

// Tag your fetches:
async function getProduct(slug: string) {
  return fetch(`${API}/products/${slug}`, {
    next: { tags: [`product-${slug}`, 'products'], revalidate: 3600 },
  }).then(r => r.json());
}
// Invalidate: POST /api/revalidate { "tag": "product-cool-shoes" }

---

3. Image Optimization

// next.config.ts  (Next.js 13.1+ supports TS config; .js/ESM also fine)
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  images: {
    // AVIF is usually smaller than WebP, but the gain varies a lot (photos
    // benefit most; flat illustrations/PNGs less so) and AVIF costs more CPU to
    // encode/decode. List AVIF first so the optimizer prefers it, WebP as fallback.
    // Measure transfer size on YOUR images (DevTools Network) before assuming a ratio.
    formats: ['image/avif', 'image/webp'],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920],
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
    // Floor for how long the OPTIMIZED variant is cached when the upstream sends
    // no/weak Cache-Control. Next.js 16 default is 14400 (4h); v15 default was 60s.
    // Do NOT hardcode a year for REMOTE images — the remote URL is the cache key,
    // not a content hash, so remote content can change yet you'd serve a stale,
    // year-old optimization. Let the origin's Cache-Control win, or use a modest
    // floor. Long immutable caching belongs on hashed /_next/static assets (see §7).
    minimumCacheTTL: 14400,
    remotePatterns: [
      { protocol: 'https', hostname: 'cdn.example.com', pathname: '/images/**' },
    ],
  },
};

export default nextConfig;

Blur placeholders at build time

// lib/image-utils.ts
import { getPlaiceholder } from 'plaiceholder';

export async function getBlurDataURL(src: string): Promise {
  const buffer = await fetch(src).then(r => r.arrayBuffer());
  const { base64 } = await getPlaiceholder(Buffer.from(buffer), { size: 10 });
  return base64;
}

// Usage:
const blur = await getBlurDataURL(product.imageUrl);

Responsive art direction

function HeroBanner() {
  return (
    
      
      
      
      {/* `preload` (Next 16) / `priority` (Next 15) — pick one, this is the LCP image */}
      
    
  );
}

---

4. Bundle Analysis & Tree Shaking

npm install -D @next/bundle-analyzer

// next.config.ts (ESM/TS). For CommonJS next.config.js use require()/module.exports.
import type { NextConfig } from 'next';
import bundleAnalyzer from '@next/bundle-analyzer';

const withBundleAnalyzer = bundleAnalyzer({ enabled: process.env.ANALYZE === 'true' });

const nextConfig: NextConfig = { /* ... */ };
export default withBundleAnalyzer(nextConfig);

ANALYZE=true npm run build   # opens treemaps for client + server bundles

Dynamic imports

// BAD: imports entire library for everyone
import { Chart } from 'chart.js/auto';

// GOOD: load only when needed
import dynamic from 'next/dynamic';
const Chart = dynamic(() => import('@/components/chart'), {
  loading: () => ,
  ssr: false,
});

Tree shaking traps

// BAD: barrel import pulls everything
import { Button, Input } from '@/components/ui';

// GOOD: direct imports
import { Button } from '@/components/ui/button';

// BAD: full lodash (71KB)
import _ from 'lodash';

// GOOD: specific import (1KB)
import debounce from 'lodash/debounce';

// Heavy lib alternatives:
// moment (300KB) → dayjs (2KB) or date-fns
// axios (29KB) → native fetch
// uuid (12KB) → crypto.randomUUID()
// classnames (1KB) → clsx (228B)

---

5. Edge Functions & Middleware

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { geolocation } from '@vercel/functions'; // npm i @vercel/functions

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

  // Geo-routing. NOTE: `request.geo`/`request.ip` were REMOVED from core
  // Next.js in v15 — reading them now is undefined. Geo data is provider-supplied:
  //   - Vercel:      geolocation(request).country  (from @vercel/functions)
  //   - Cloudflare:  request.headers.get('cf-ipcountry')
  //   - Other CDNs:  a header like 'x-vercel-ip-country' / 'x-geo-country'
  // Self-hosted (node/standalone) gets NO geo unless your proxy injects a header.
  const country = geolocation(request).country ?? 'US';
  if (pathname === '/' && country === 'DE' && !request.cookies.has('geo-override')) {
    return NextResponse.redirect(new URL('/de', request.url));
  }

  // A/B testing at the edge — no client flicker
  if (pathname === '/pricing') {
    const bucket = request.cookies.get('ab-pricing')?.value
      ?? (Math.random()  r.json());

  return NextResponse.json(results, {
    headers: { 'Cache-Control': 's-maxage=60, stale-while-revalidate=300' },
  });
}

---

6. Font Loading

// app/layout.tsx
import { Inter, JetBrains_Mono } from 'next/font/google';
import localFont from 'next/font/local';

const inter = Inter({ subsets: ['latin'], display: 'swap', variable: '--font-inter' });
const mono = JetBrains_Mono({ subsets: ['latin'], display: 'swap', variable: '--font-mono' });

const brand = localFont({
  src: [
    { path: './fonts/Brand-Regular.woff2', weight: '400' },
    { path: './fonts/Brand-Bold.woff2', weight: '700' },
  ],
  display: 'swap',
  variable: '--font-brand',
  adjustFontFallback: 'Arial',
});

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    
      {children}
    
  );
}

/* globals.css */
:root {
  --font-sans: var(--font-inter), system-ui, sans-serif;
  --font-mono: var(--font-mono), 'Courier New', monospace;
}
body { font-family: var(--font-sans); }
code { font-family: var(--font-mono); }

---

7. Caching Strategies

The big shift (Next.js 16): App Router caching is now opt-in via Cache Components and the 'use cache' directive. With cacheComponents: true, all page/layout/route code runs at request time by default; you explicitly mark what to cache. cacheLife/cacheTag are now stable (no unstable_ prefix). Prefer this on new Next.js 16 code; keep unstable_cache only for Next.js 15-and-earlier projects.

Server-side caching — 'use cache' (Next.js 16, preferred)

// next.config.ts
import type { NextConfig } from 'next';
const nextConfig: NextConfig = { cacheComponents: true };
export default nextConfig;

// Cache a data function. The compiler derives the cache key from the args.
import { cacheTag, cacheLife } from 'next/cache';

export async function getProducts(category: string) {
  'use cache';
  cacheTag('products', `category-${category}`); // invalidate via revalidateTag(...)
  cacheLife('minutes'); // preset (seconds|minutes|hours|days|weeks|max) OR { stale, revalidate, expire } in seconds
  return db.product.findMany({ where: { category }, orderBy: { createdAt: 'desc' } });
}

// Variants (Next.js 16):
//   'use cache'          → shared, persisted across deploys/instances
//   'use cache: remote'  → shared, cached at runtime in the remote/data cache
//   'use cache: private' → per-user (keyed by cookies/headers), never shared across users

Server-side caching — unstable_cache (Next.js 15 and earlier)

import { unstable_cache } from 'next/cache';

// Still works in 16 but is the legacy path; migrate to 'use cache' when you adopt
// cacheComponents. Args become part of the key; the second arg is an extra key prefix.
export const getProducts = unstable_cache(
  async (category: string) => {
    return db.product.findMany({ where: { category }, orderBy: { createdAt: 'desc' } });
  },
  ['products'],
  { revalidate: 300, tags: ['products', 'category'] }
);

> Invalidate either style from a Server Action or the /api/revalidate route above with revalidateTag('products') / revalidatePath('/products').

CDN headers

// Public content
return NextResponse.json(data, {
  headers: { 'Cache-Control': 'public, s-maxage=60, stale-while-revalidate=300' },
});

// Personalized content
return NextResponse.json(data, {
  headers: { 'Cache-Control': 'private, no-store, max-age=0' },
});

next.config headers (long-cache hashed assets)

// next.config.ts (CommonJS next.config.js: `module.exports = { async headers() {...} }`)
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  async headers() {
    return [
      // /_next/static/* is content-hashed → safe to cache immutably for a year.
      { source: '/_next/static/:path*',
        headers: [{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' }] },
      // Only mark /fonts immutable if the filenames are hashed/versioned.
      { source: '/fonts/:path*',
        headers: [{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' }] },
    ];
  },
};
export default nextConfig;

---

8. Performance Audit Workflow

Step 1: Measure baseline + confirm the metrics, don't guess

npx @lhci/cli autorun --collect.url=https://your-site.com   # lab numbers

Then make each metric measurable, not vibes:

• Confirm the LCP element (lab ≠ what you assume): in DevTools → Performance, record a load and click the LCP marker in the Timings track — it highlights the actual element. Or in console: new PerformanceObserver(l => l.getEntries().forEach(e => console.log(e.element, e.startTime))).observe({ type: 'largest-contentful-paint', buffered: true });. Only THAT element should preload.
• TTFB: curl -o /dev/null -s -w 'ttfb=%{time_starttransfer}s total=%{time_total}s\n' https://your-site.com. If TTFB > ~800ms, LCP can't hit 2.5s — fix the server/render path (static/ISR, faster DB, edge) before touching the client.
• Image transfer size: DevTools → Network, filter Img, check the Transferred column and whether the served Content-Type is image/avif/image/webp. A 400×300 image shipping 800KB means a missing/oversized sizes or an unoptimized ``.
• JS execution time: DevTools → Performance → Bottom-Up, group by script; or Lighthouse "Total Blocking Time" + "JS execution time" audits. This is what INP/TBT actually measure.

Step 2: Bundle size

ANALYZE=true npm run build
# Triage in the treemap: any single package > 50KB gzip, duplicate copies of the same
# lib (multiple versions), and SERVER-only code leaking into a client bundle
# ("use client" file importing a server util / a DB driver).

Step 3: Rendering strategy (read the build legend)

npm run build
# Per-route symbols (legend printed under the table):
#   ○ Static       /about              prerendered, no server work
#   ● SSG          /blog/[slug]        prerendered via generateStaticParams
#   ◐ Partial      /product/[id]       partial prerender: static shell + streamed dynamic
#   ƒ Dynamic      /dashboard          rendered per request
# Question every ƒ Dynamic route: can it be SSG/ISR, or kept static with the dynamic
# parts behind ? With cacheComponents (Next 16) routes are dynamic by DEFAULT,
# so "static" now means you explicitly cached it ('use cache') — verify inte

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [san-npm](https://github.com/san-npm)
- **Source:** [san-npm/skills-ws](https://github.com/san-npm/skills-ws)
- **License:** MIT
- **Homepage:** https://skills-ws.vercel.app

Install and usage instructions live in the source repository linked above.