Specialist Next.js Ally

Optimizes Next.js applications for production through bundle analysis, caching strategies, and Core Web Vitals tuning.

When to Use This Agent

Choose this agent when you need to:

• Analyze and reduce Next.js bundle sizes with tree shaking audits and code splitting
• Optimize Core Web Vitals (LCP, FID, CLS) within Next.js rendering pipelines
• Configure production caching including ISR timing, CDN edge, and revalidation strategies

Consider alternatives when:

• You need general Next.js development guidance rather than optimization of existing apps
• Performance bottlenecks are in backend API response times rather than frontend delivery

Quick Start

Configuration

Copy
name: specialist-nextjs-ally
type: agent
category: web-tools

Example Invocation

Copy
claude agent:invoke specialist-nextjs-ally "Audit my Next.js app for Core Web Vitals and bundle optimization"

Example Output

Next.js Performance Audit
==========================
BUNDLE (487KB -> target 300KB):
  - vendors-lodash.js: 72KB -> lodash-es (-58KB)
  - chart-library.js: 94KB -> lazy load (-94KB initial)
  - moment.js: 67KB -> date-fns (-52KB)

CORE WEB VITALS:
  LCP: 3.2s -> Add priority to hero image, preconnect API
  FID: 120ms -> Defer analytics, split hydration
  CLS: 0.18 -> Add dimensions to 4 images

CACHING: 5 uncached API routes need Cache-Control headers

Core Concepts

Performance Dimensions

Aspect	Details
Bundle Optimization	Tree shaking, code splitting, dynamic imports, chunk analysis
Rendering Strategy	Static Generation, ISR, SSR, and PPR selection per route
Image Pipeline	next/image with format negotiation (WebP/AVIF) and blur placeholders
Font Loading	next/font with self-hosted subsets, display swap, and preload
Caching Layers	Browser, CDN edge, ISR, fetch cache, and route cache coordination

Performance Architecture

+-------------------+     +-------------------+     +------------------+
|  Client Bundle    |     |  Edge/CDN         |     |  Origin Server   |
|  Analysis         |     |  Cache Layer      |     |  (ISR/SSR)       |
+-------------------+     +-------------------+     +------------------+
       |                         |                         |
       v                         v                         v
+-------------------+     +-------------------+     +------------------+
|  Code Splitting   |     |  Cache-Control    |     |  Data Fetching   |
|  Tree Shaking     |     |  Revalidation     |     |  Streaming       |
+-------------------+     +-------------------+     +------------------+

Configuration

Parameter	Type	Default	Description
audit_scope	string	"full"	Focus: "bundle", "vitals", "caching", "images", or "full"
target_bundle_kb	number	300	Maximum acceptable client JS bundle in kilobytes
lcp_target_ms	number	2500	Target LCP in milliseconds (Good threshold)
cls_target	number	0.1	Target CLS score (Good threshold)
deployment_platform	string	"vercel"	Platform for caching and edge optimization

Best Practices

1. Audit Bundle Before Optimizing - Run @next/bundle-analyzer to visualize client JS before changes. A single unused dependency often outweighs all application code in bundle weight.

2. Match Rendering to Data Freshness - Static pages with infrequent changes use Static Generation. Hourly updates use ISR. Reserve SSR for personalized or real-time pages. Mismatched strategies waste compute or serve stale content.

3. Prioritize LCP Images - Add the priority prop to hero images on next/image. Without it, the LCP element waits for hydration before the browser fetches it, adding hundreds of milliseconds.

4. Reserve Space for Dynamic Content - Set explicit width/height on images, min-height on ad slots, and use skeleton components matching loaded dimensions to prevent CLS from page reflows.

5. Layer Caching Edge to Browser - Configure Cache-Control on API handlers, ISR intervals on pages, and CDN caching for assets. Each layer reduces origin load, but misconfiguration can serve stale data.

Common Issues

1. Dynamic Imports Breaking Hydration - React.lazy() without Suspense causes hydration mismatches. Always pair with <Suspense> and use next/dynamic with ssr: false when the component cannot render server-side.

2. Third-Party Scripts Blocking Main Thread - Analytics and chat widgets via <script> block FID. Use next/script with strategy="lazyOnload" to defer non-essential scripts.

3. ISR Revalidation Stampede - Multiple simultaneous requests triggering regeneration on popular expired pages. Use on-demand revalidation via webhook revalidateTag calls to regenerate proactively.