---

name: frontend-performance description: Optimize Next.js frontend performance using Lighthouse, bundle analysis, and animation best practices. Use when diagnosing slow pages, optimizing bundle size, or improving Core Web Vitals (LCP, TBT, CLS).

Frontend Performance Optimization

Diagnose and fix performance issues in Next.js applications.

Quick Diagnostics

Run Lighthouse CLI

Copy# Performance audit (headless)
npx lighthouse http://localhost:3000 --output=json --output-path=./lighthouse.json --chrome-flags="--headless" --only-categories=performance

# Parse key metrics
cat lighthouse.json | jq '{
  score: .categories.performance.score,
  FCP: .audits["first-contentful-paint"].displayValue,
  LCP: .audits["largest-contentful-paint"].displayValue,
  TBT: .audits["total-blocking-time"].displayValue,
  CLS: .audits["cumulative-layout-shift"].displayValue
}'

# Find slow scripts
cat lighthouse.json | jq '.audits["bootup-time"].details.items | .[0:8]'

# Main thread breakdown
cat lighthouse.json | jq '.audits["mainthread-work-breakdown"].details.items'

Important: Always test production builds (next build && next start), not dev mode. Dev mode has 2-10x overhead from HMR, source maps, and no optimizations.

Bundle Analysis

Copy# Install
bun add -d @next/bundle-analyzer

# Run analysis
ANALYZE=true bun run build

Configure in next.config.js:

Copyimport bundleAnalyzer from '@next/bundle-analyzer'

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

export default withBundleAnalyzer(nextConfig)

Common Fixes

1. optimizePackageImports

For libraries with many exports (icons, utilities, animation libraries):

Copy// next.config.js
const nextConfig = {
  experimental: {
    optimizePackageImports: [
      'framer-motion',
      'lucide-react',
      '@phosphor-icons/react',
      'lodash',
      'date-fns',
      '@heroicons/react',
    ],
  },
}

This ensures tree-shaking works correctly - only imports you use get bundled.

2. Framer Motion - Variants Pattern

WRONG - Creates N animation controllers:

Copy// Each element has its own animation state - expensive!
{items.map((item, i) => (
  <motion.div
    key={i}
    initial={{ opacity: 0, y: 20 }}
    animate={{ opacity: 1, y: 0 }}
    transition={{ delay: i * 0.05 }}  // Individual delays
  >
    {item}
  </motion.div>
))}

RIGHT - Single controller with staggerChildren:

Copy// Parent controls all children - efficient!
const containerVariants = {
  hidden: {},
  visible: {
    transition: {
      staggerChildren: 0.05,
    },
  },
}

const itemVariants = {
  hidden: { opacity: 0, y: 20 },
  visible: {
    opacity: 1,
    y: 0,
    transition: { type: 'spring' as const, damping: 15 }
  },
}

<motion.div
  variants={containerVariants}
  initial="hidden"
  animate="visible"
>
  {items.map((item, i) => (
    <motion.div key={i} variants={itemVariants}>
      {item}
    </motion.div>
  ))}
</motion.div>

Also avoid:

• filter: blur() in animations - very expensive
• Too many infinite animations (reduce or use CSS)
• Individual transition props on children when using variants

3. Move Heavy Computation Server-Side

Keep these out of client bundles:

• Syntax highlighting: use shiki server-side, not prism-react-renderer
• Markdown parsing: render on server
• Date formatting libraries: consider Intl.DateTimeFormat
• Large data transformations: API routes or server components

4. Image Optimization

Copy// Always use next/image
import Image from 'next/image'

<Image
  src="/hero.jpg"
  alt="Hero"
  width={1200}
  height={600}
  priority  // For LCP images
  placeholder="blur"  // Reduces CLS
/>

5. Font Optimization

Copy// app/layout.tsx
import { Inter } from 'next/font/google'

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',  // Prevents FOIT
  preload: true,
})

6. External Packages (Server Only)

Prevent server-only packages from being bundled:

Copy// next.config.js
const nextConfig = {
  serverExternalPackages: ['sharp', 'canvas'],
}

Performance Targets

Debugging Workflow

1. Run production Lighthouse - Get baseline metrics
2. Check bootup-time audit - Find slow scripts
3. Run bundle analyzer - Identify large chunks
4. Fix largest issues first - Usually 1-2 packages cause most problems
5. Re-test - Verify improvements

Quick Wins Checklist

• Test production build, not dev
• Add optimizePackageImports for icon/utility libraries
• Use Framer Motion variants pattern
• Remove filter: blur() from animations
• Add priority to LCP images
• Use next/font with display: swap
• Move heavy libraries to server components