Next.js Performance Settings

Configuration preset that optimizes Claude Code for Next.js performance analysis, bundle auditing, and Core Web Vitals monitoring.

When to Use This Setting

Apply this setting when you need to:

• Configure Claude Code to prioritize performance analysis tools and metrics when working on Next.js applications
• Enable automatic bundle size tracking, lighthouse integration, and rendering performance monitoring across your Next.js project
• Set up workspace-level defaults for performance budgets, image optimization rules, and server component boundaries

Consider alternatives when:

• Your project uses a different React framework like Remix or Gatsby that has its own performance tooling conventions
• You need general-purpose Claude Code settings without Next.js-specific performance constraints

Quick Start

Configuration

Copy
name: nextjs-performance-settings
type: setting
category: frontend

Example Application

Copy
claude setting:apply nextjs-performance-settings

Example Output

Setting applied successfully. Configuration changes:
- performance_budget: { js: 150kb, css: 50kb, images: 500kb }
- lighthouse_threshold: { performance: 90, accessibility: 95 }
- bundle_analyzer: enabled (webpack-bundle-analyzer)
- image_optimization: strict (next/image enforcement)
- server_components: prefer (default to RSC unless client needed)
- rendering_strategy: auto (static > ISR > SSR selection)

Core Concepts

Next.js Performance Optimization Overview

Aspect	Details
Bundle Analysis	Monitors JavaScript bundle sizes per route, identifies code splitting opportunities, and flags imports that pull in oversized dependencies
Core Web Vitals	Tracks LCP, INP, and CLS metrics with automated regression detection when component changes degrade user experience scores
Rendering Strategy	Enforces optimal rendering selection hierarchy: static generation first, then ISR for semi-dynamic content, SSR only when request-time data is required
Image Pipeline	Validates that all images use next/image with proper width, height, priority, and loading attributes to prevent CLS and optimize LCP
Server Components	Defaults components to React Server Components, requiring explicit "use client" directives only when browser APIs or interactivity are needed

Performance Monitoring Architecture

┌─────────────────┐     ┌─────────────────┐
│  Build Phase     │────▶│  Bundle Analyzer │
│  next build      │     │  Size Budgets    │
└─────────────────┘     └─────────────────┘
        │                        │
        ▼                        ▼
┌─────────────────┐     ┌─────────────────┐
│  Runtime Phase   │────▶│  Web Vitals     │
│  next start      │     │  Lighthouse CI   │
└─────────────────┘     └─────────────────┘
        │                        │
        ▼                        ▼
┌─────────────────┐     ┌─────────────────┐
│  Monitoring      │────▶│  Alerts &       │
│  Vercel Analytics│     │  Regressions    │
└─────────────────┘     └─────────────────┘

Configuration

Parameter	Type	Default	Description
js_budget_kb	integer	150	Maximum JavaScript bundle size per route in kilobytes before triggering warnings
lighthouse_perf_min	integer	90	Minimum Lighthouse performance score required for builds to pass quality gates
image_strict_mode	boolean	true	Enforce next/image usage for all img elements with required width and height props
prefer_server_components	boolean	true	Default new components to server components unless client interactivity is explicitly needed
rendering_auto_select	boolean	true	Automatically recommend optimal rendering strategy based on data fetching patterns

Best Practices

1. Set Route-Level Budgets Rather Than Global Limits Different routes have different complexity requirements. A landing page should have a 100KB JS budget while a dashboard page might need 250KB. Configure per-route budgets in the performance settings to avoid false positives on legitimately complex pages while catching bloat on simple ones.

2. Enable Incremental Bundle Tracking Track bundle size changes per pull request rather than only checking absolute thresholds. A 5KB increase might be acceptable individually but a series of twenty such increases indicates a trend that needs attention. The setting tracks delta changes and flags PRs that increase total bundle size by more than 3%.

3. Prioritize LCP Over Total Bundle Size A page can have a large total bundle but still achieve excellent LCP if critical rendering path resources are prioritized. Configure the setting to flag above-the-fold render-blocking resources rather than obsessing over total download size that includes lazily loaded components.

4. Audit Third-Party Scripts Separately Third-party analytics, chat widgets, and tracking scripts often dominate performance budgets. The setting separates first-party and third-party bundle analysis so your team focuses on code they can actually optimize rather than being overwhelmed by vendor script sizes.

5. Review Server Component Boundaries Weekly Components that start as server components may gain interactivity over time, requiring a "use client" directive. Conversely, client components that no longer use browser APIs can be converted back to server components. The setting flags both directions during code review.

Common Issues

1. Bundle size exceeds budget after adding a single import A small import like import { format } from 'date-fns' can pull in the entire library if tree-shaking fails. Use subpath imports (import format from 'date-fns/format') and check that your bundler configuration supports proper tree-shaking for the dependency.

2. Lighthouse scores fluctuate between runs Network conditions and server response times during CI testing cause score variance. Run Lighthouse in throttled mode with consistent CPU throttling and use median scores from three consecutive runs rather than single-run snapshots.

3. Server component renders as client component unexpectedly Importing a client component into a server component does not make the parent a client component, but importing a module that contains "use client" at the top level does. Check the import chain and ensure shared utilities do not contain client directives that propagate up the component tree.