/nextjs-performance

name: nextjs-performance
description: Expert Next.js performance optimization skill covering Core Web Vitals, image/font optimization, caching strategies, streaming, bundle optimization, and Server Components best practices. Use when optimizing Next.js applications for Core Web Vitals (LCP, INP, CLS), implementing next/image and next/font, configuring caching with unstable_cache and revalidateTag, converting Client Components to Server Components, implementing Suspense streaming, or analyzing and reducing bundle size. Supports Next.js 16 + React 19 patterns.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep

Next.js Performance Optimization

Expert guidance for optimizing Next.js applications with focus on Core Web Vitals, modern patterns, and best practices.

Overview

This skill provides comprehensive guidance for optimizing Next.js applications. It covers Core Web Vitals optimization (LCP, INP, CLS), modern React patterns, Server Components, caching strategies, and bundle optimization techniques. Designed for developers already familiar with React/Next.js who want to implement production-grade optimizations.

When to Use

Use this skill when working on Next.js applications and need to:

• Optimize Core Web Vitals (LCP, INP, CLS) for better performance and SEO
• Implement image optimization with `next/image` for faster loading
• Configure font optimization with `next/font` to eliminate layout shift
• Set up caching strategies using `unstable_cache`, `revalidateTag`, or ISR
• Convert Client Components to Server Components for reduced bundle size
• Implement Suspense streaming for progressive page loading
• Analyze and reduce bundle size with code splitting and dynamic imports
• Configure metadata and SEO for better search engine visibility
• Optimize API route handlers for better performance
• Apply Next.js 16 and React 19 modern patterns

Coverage Areas

• **Core Web Vitals optimization** (LCP, INP, CLS)
• **Image optimization** with `next/image`
• **Font optimization** with `next/font`
• **Caching strategies** (`unstable_cache`, `revalidateTag`, ISR)
• **Server Components** patterns and Client-to-Server conversion
• **Streaming and Suspense** for progressive loading
• **Bundle optimization** and code splitting
• **Metadata and SEO** configuration
• **Route handlers** optimization
• **Next.js 16 + React 19** patterns

Instructions

Before Starting

1. **Analyze current performance** with Lighthouse 2. **Identify bottlenecks** - check Core Web Vitals in Chrome DevTools or PageSpeed Insights 3. **Determine optimization priority**:

• LCP issues → Focus on images, fonts
• INP issues → Reduce JS, use Server Components
• CLS issues → Add dimensions, use next/font

How to Use This Skill

1. **Load relevant reference files** based on the area you're optimizing:

• Image issues → `references/image-optimization.md`
• Font/layout shift → `references/font-optimization.md`
• Caching → `references/caching-strategies.md`
• Component architecture → `references/server-components.md`

2. **Follow the quick patterns** for common optimizations 3. **Apply before/after conversions** to improve existing code 4. **Verify improvements** with Lighthouse after changes

Core Principles

1. **Prefer Server Components** - Only use 'use client' when necessary (browser APIs, interactivity) 2. **Load components as low as possible** - Keep Client Components at leaf nodes 3. **Use Suspense boundaries** - Enable streaming and progressive loading 4. **Cache appropriately** - Use tags for granular revalidation 5. **Measure before/after** - Always verify improvements with real metrics

Examples

Example 1: Convert Client Component to Server Component

**BEFORE (Client Component with useEffect):**

'use client'
import { useEffect, useState } from 'react'

export default function ProductList() {
  const [products, setProducts] = useState([])

  useEffect(() => {
    fetch('/api/products').then(r => r.json()).then(setProducts)
  }, [])

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

**AFTER (Server Component with direct data access):**

import { db } from '@/lib/db'

export default async function ProductList() {
  const products = await db.product.findMany()
  return <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul>
}

Example 2: Optimize Images for LCP

import Image from 'next/image'

export function Hero() {
  return (
    <div className="relative w-full h-[600px]">
      <Image
        src="/hero.jpg"
        alt="Hero"
        fill
        priority          // Disable lazy loading for LCP
        sizes="100vw"
        className="object-cover"
      />
    </div>
  )
}

Example 3: Implement Caching Strategy

import { unstable_cache, revalidateTag } from 'next/cache'

// Cached data function
const getProducts = unstable_cache(
  async () => db.product.findMany(),
  ['products'],
  { revalidate: 3600, tags: ['products'] }
)

// Revalidate on mutation
export async function createProduct(data: FormData) {
  'use server'
  await db.product.create({ data })
  revalidateTag('products')
}

Example 4: Setup Optimized Fonts

import { Inter } from 'next/font/google'

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

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

Example 5: Implement Suspense Streaming

import { Suspense } from 'react'

export default function Page() {
  return (
    <>
      <header>Static content (immediate)</header>

      <Suspense fallback={<ProductSkeleton />}>
        <ProductList />  {/* Streamed when ready */}
      </Suspense>

      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews />      {/* Independent streaming *