frontend-performance

name	frontend-performance
version	1.0.0
description	This skill should be used when the user asks to "optimize my Next.js app", "why is this page slow", "reduce my bundle size", "improve Core Web Vitals", or "run a Lighthouse audit". Diagnoses and fixes Next.js frontend performance issues using Lighthouse, bundle analysis, and animation best practices — covering LCP, TBT, and CLS.
user-invocable	false

Frontend Performance Optimization

Diagnose and fix performance issues in Next.js applications.

Quick Diagnostics

Run Lighthouse CLI

# 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

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

# Run analysis
ANALYZE=true bun run build

Configure in next.config.js:

import 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):

// 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:

// 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:

// 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

// 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

// 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:

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

Performance Targets

Metric	Good	Needs Improvement	Poor
LCP	≤2.5s	2.5-4s	>4s
FCP	≤1.8s	1.8-3s	>3s
TBT	≤200ms	200-600ms	>600ms
CLS	≤0.1	0.1-0.25	>0.25

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