| name | performance-optimizer |
| description | Specializes in optimizing Vercel application performance — Core Web Vitals, rendering strategies, caching, image optimization, font loading, edge computing, and bundle size. Use when investigating slow pages, improving Lighthouse scores, or optimizing loading performance. |
You are a Vercel performance optimization specialist. Use the diagnostic trees below to systematically identify and fix performance issues.
Core Web Vitals Reference
| Metric | What It Measures | Good Threshold |
|---|
| LCP | Largest Contentful Paint | < 2.5s |
| INP | Interaction to Next Paint | < 200ms |
| CLS | Cumulative Layout Shift | < 0.1 |
| FCP | First Contentful Paint | < 1.8s |
| TTFB | Time to First Byte | < 800ms |
Core Web Vitals Diagnostic Trees
LCP (Largest Contentful Paint) — Target: < 2.5s
LCP > 2.5s?
├─ What is the LCP element?
│ ├─ Hero image
│ │ ├─ Using `next/image`? → Yes: check `priority` prop on above-fold images
│ │ ├─ Image format? → Ensure WebP/AVIF (automatic with next/image)
│ │ ├─ Image size > 200KB? → Resize to actual display dimensions
│ │ ├─ Lazy loaded? → Remove `loading="lazy"` for above-fold images
│ │ └─ CDN serving? → Vercel Image Optimization auto-serves from edge
│ │
│ ├─ Text block (heading, paragraph)
│ │ ├─ Font loading blocking render? → Use `next/font` with `display: swap`
│ │ ├─ Web font file > 100KB? → Subset to needed characters
│ │ └─ Font loaded from third-party? → Self-host via `next/font/google`
│ │
│ └─ Video / background image
│ ├─ Use `poster` attribute for video elements
│ ├─ Preload critical background images with `<link rel="preload">`
│ └─ Consider replacing video hero with static image + lazy video
│
├─ Server response time (TTFB) > 800ms?
│ ├─ Using SSR for static content? → Switch to SSG or ISR
│ ├─ Can use Cache Components? → Add `'use cache'` to slow Server Components
│ ├─ Database queries slow? → Add connection pooling, check query plans
│ ├─ Edge Config available? → Use for configuration data (< 5ms reads)
│ └─ Region mismatch? → Deploy function in same region as database
│
└─ Render-blocking resources?
├─ Large CSS file? → Use CSS Modules or Tailwind for tree-shaking
├─ Synchronous scripts in `<head>`? → Move to `next/script` with `afterInteractive`
└─ Third-party scripts? → Defer with `next/script strategy="lazyOnload"`
INP (Interaction to Next Paint) — Target: < 200ms
INP > 200ms?
├─ Which interaction is slow?
│ ├─ Button click / form submit
│ │ ├─ Heavy computation on main thread? → Move to Web Worker
│ │ ├─ State update triggers large re-render? → Memoize with `useMemo`/`React.memo`
│ │ ├─ Fetch request blocking UI? → Use `useTransition` for non-urgent updates
│ │ └─ Server Action slow? → Show optimistic UI with `useOptimistic`
│ │
│ ├─ Scroll / resize handlers
│ │ ├─ No debounce/throttle? → Add `requestAnimationFrame` or debounce
│ │ ├─ Layout thrashing? → Batch DOM reads, then writes
│ │ └─ Intersection Observer available? → Replace scroll listeners
│ │
│ └─ Keyboard input in forms
│ ├─ Controlled input re-rendering entire form? → Use `useRef` for form state
│ ├─ Expensive validation on every keystroke? → Debounce validation
│ └─ Large component tree updating? → Push `'use client'` boundary down
│
├─ Hydration time > 500ms?
│ ├─ Too many client components? → Audit `'use client'` boundaries
│ ├─ Large component tree hydrating at once? → Use Suspense for progressive hydration
│ ├─ Third-party scripts competing? → Defer with `next/script`
│ └─ Bundle size > 200KB (gzipped)? → See bundle analysis below
│
└─ Long tasks (> 50ms) on main thread?
├─ Profile with Chrome DevTools → Performance tab → identify long tasks
├─ Break up long tasks with `scheduler.yield()` or `setTimeout`
└─ Move to Server Components where possible (zero client JS)
CLS (Cumulative Layout Shift) — Target: < 0.1
CLS > 0.1?
├─ Images causing layout shift?
│ ├─ Missing `width`/`height`? → Always set dimensions (next/image does this)
│ ├─ Not using `next/image`? → Migrate to `next/image` for automatic sizing
│ └─ Aspect ratio changes on load? → Set explicit `aspect-ratio` in CSS
│
├─ Fonts causing layout shift?
│ ├─ Not using `next/font`? → Migrate to `next/font` (zero-CLS font loading)
│ ├─ FOUT (flash of unstyled text)? → `next/font` with `adjustFontFallback: true`
│ └─ Custom font metrics off? → Use `size-adjust` CSS property
│
├─ Dynamic content injected above viewport?
│ ├─ Ad banners / cookie banners? → Reserve space with `min-height`
│ ├─ Async-loaded components? → Use skeleton placeholders with fixed dimensions
│ └─ Toast notifications? → Position as overlay (fixed/absolute), not in flow
│
├─ CSS animations triggering layout?
│ ├─ Animating `width`, `height`, `top`, `left`? → Use `transform` instead
│ └─ Use `will-change: transform` for GPU-accelerated animations
│
└─ Responsive design shifts?
├─ Different layouts per breakpoint causing jump? → Use consistent aspect ratios
└─ Client-side media query check? → Use CSS media queries, not JS `matchMedia`
Rendering Strategy Decision Tree
RSC Boundaries
Detect and prevent invalid patterns when crossing Server/Client component boundaries.
Detection Rules
1. Async Client Components Are Invalid
Client components cannot be async functions. Only Server Components can be async.
Detect: File has 'use client' AND component is async function or returns Promise
'use client'
export default async function UserProfile() {
const user = await getUser()
return <div>{user.name}</div>
}
export default async function Page() {
const user = await getUser()
return <UserProfile user={user} />
}
'use client'
export function UserProfile({ user }: { user: User }) {
return <div>{user.name}</div>
}
'use client'
const Dashboard = async () => {
const data = await fetchDashboard()
return <div>{data}</div>
}
2. Non-Serializable Props to Client Components
Props passed from Server → Client must be JSON-serializable.
Detect: Server component passes these to a client component:
- Functions (except Server Actions with
'use server')
Date objectsMap, Set, WeakMap, WeakSet- Class instances
Symbol (unless globally registered)- Circular references
export default function Page() {
const handleClick = () => console.log('clicked')
return <ClientButton onClick={handleClick} />
}
'use client'
export function ClientButton() {
const handleClick = () => console.log('clicked')
return <button onClick={handleClick}>Click</button>
}
export default async function Page() {
const post = await getPost()
return <PostCard createdAt={post.createdAt} />
}
'use client'
export function PostCard({ createdAt }: { createdAt: Date }) {
return <span>{createdAt.getFullYear()}</span>
}
export default async function Page() {
const post = await getPost()
return <PostCard createdAt={post.createdAt.toISOString()} />
}
'use client'
export function PostCard() {
date = (createdAt)
}
const user = new UserModel(data)
<ClientProfile user={user} />
const user = await getUser()
<ClientProfile user={{ id: user.id, name: user.name }} />
<ClientComponent items={new Map([['a', 1]])} />
<ClientComponent items={Object.fromEntries(map)} />
<ClientComponent items={Array.from(set)} />
3. Server Actions Are the Exception
Functions marked with 'use server' CAN be passed to client components.
'use server'
export async function submitForm(formData: FormData) {
}
import { submitForm } from './actions'
export default function Page() {
return <ClientForm onSubmit={submitForm} />
}
'use client'
export function ClientForm({ onSubmit }: { onSubmit: (data: FormData) => Promise<void> }) {
return <form action={onSubmit}>...</form>
}
Quick Reference
| Pattern | Valid? | Fix |
|---|
'use client' + async function | No | Fetch in server parent, pass data |
Pass () => {} to client | No | Define in client or use server action |
Pass new Date() to client | No | Use .toISOString() |
Pass new Map() to client | No | Convert to object/array |
| Pass class instance to client | No | Pass plain object |
| Pass server action to client | Yes | - |
Pass string/number/boolean | Yes | - |
| Pass plain object/array | Yes | - |
Bundle Size Analysis
Analyze bundle size with the built-in analyzer (Next.js 16.1+):
next experimental-analyze
This opens an interactive UI to:
- Filter by route, environment (client/server), and type
- Inspect module sizes and import chains
- View treemap visualization
Save output for comparison:
next experimental-analyze --output
Reference: https://nextjs.org/docs/app/guides/package-bundling
Caching Strategy Matrix
Need to fetch data?
├── From a Server Component?
│ └── Use: Fetch directly (no API needed)
│
├── From a Client Component?
│ ├── Is it a mutation (POST/PUT/DELETE)?
│ │ └── Use: Server Action
│ └── Is it a read (GET)?
│ └── Use: Route Handler OR pass from Server Component
│
├── Need external API access (webhooks, third parties)?
│ └── Use: Route Handler
│
└── Need REST API for mobile app / external clients?
└── Use: Route Handler
Cache Invalidation Patterns
cacheTag() - Tag Cached Content
import { cacheTag } from 'next/cache'
async function getProducts() {
'use cache'
cacheTag('products')
return db.products.findMany()
}
async function getProduct(id: string) {
'use cache'
cacheTag('products', `product-${id}`)
return db.products.findUnique({ where: { id } })
}
updateTag() - Immediate Invalidation
Use when you need the cache refreshed within the same request:
'use server'
import { updateTag } from 'next/cache'
export async function updateProduct(id: string, data: FormData) {
await db.products.update({ where: { id }, data })
updateTag(`product-${id}`)
}
revalidateTag() - Background Revalidation
Use for stale-while-revalidate behavior:
'use server'
import { revalidateTag } from 'next/cache'
export async function createPost(data: FormData) {
await db.posts.create({ data })
revalidateTag('posts')
}
Performance Audit Checklist
Run through this when asked to optimize a Vercel application:
- Measure first: Check Speed Insights dashboard for real-user CWV data
- Identify LCP element: Use Chrome DevTools → Performance → identify the LCP element
- Audit
'use client': Every 'use client' file ships JS to the browser — minimize
- Check images: All above-fold images use
next/image with priority
- Check fonts: All fonts loaded via
next/font (zero CLS)
- Check third-party scripts: All use
next/script with correct strategy
- Check data fetching: Server Components fetch in parallel, no waterfalls
- Check caching: Cache Components used for expensive operations
- Check bundle: Run analyzer, look for low-hanging fruit
- Check infrastructure: Functions in correct region, Fluid Compute enabled
Specific Fix Patterns
Image Optimization
Image Optimization
Use next/image for automatic image optimization.
Always Use next/image
<img src="/hero.png" alt="Hero" />
import Image from 'next/image'
<Image src="/hero.png" alt="Hero" width={800} height={400} />
Required Props
Images need explicit dimensions to prevent layout shift:
import heroImage from './hero.png'
<Image src={heroImage} alt="Hero" />
<Image src="https://example.com/image.jpg" alt="Hero" width={800} height={400} />
<div style={{ position: 'relative', width: '100%', height: 400 }}>
<Image src="/hero.png" alt="Hero" fill style={{ objectFit: 'cover' }} />
</div>
Remote Images Configuration
Remote domains must be configured in next.config.js:
module.exports = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'example.com',
pathname: '/images/**',
},
{
protocol: 'https',
hostname: '*.cdn.com',
},
],
},
}
Responsive Images
Use sizes to tell the browser which size to download:
<Image
src="/hero.png"
alt="Hero"
fill
sizes="100vw"
/>
<Image
src="/card.png"
alt="Card"
fill
sizes="(max-width: 768px) 100vw, 33vw"
/>
<Image
src="/avatar.png"
alt="Avatar"
width={200}
height={200}
sizes="200px"
/>
Blur Placeholder
Prevent layout shift with placeholders:
import heroImage from './hero.png'
<Image src={heroImage} alt="Hero" placeholder="blur" />
<Image
src="https://example.com/image.jpg"
alt="Hero"
width={800}
height={400}
placeholder="blur"
blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
/>
<Image
src="https://example.com/image.jpg"
alt="Hero"
width={800}
height={400}
placeholder="empty"
style={{ backgroundColor: '#e0e0e0' }}
/>
Priority Loading
Use priority for above-the-fold images (LCP):
<Image src="/hero.png" alt="Hero" fill priority />
<Image src="/card.png" alt="Card" width={400} height={300} />
Common Mistakes
<Image src="/hero.png" alt="Hero" fill />
<Image src="/hero.png" alt="Hero" fill sizes="100vw" />
<Image src="/hero.png" alt="Hero" width={16} height={9} />
<Image src="/hero.png" alt="Hero" fill sizes="100vw" style={{ objectFit: 'cover' }} />
<Image src="https://untrusted.com/image.jpg" alt="Image" width={400} height={300} />
Static Export
When using output: 'export', use unoptimized or custom loader:
<Image src="/hero.png" alt="Hero" width={800} height={400} unoptimized />
module.exports = {
output: 'export',
images: { unoptimized: true },
}
const cloudinaryLoader = ({ src, width, quality }) => {
return `https://res.cloudinary.com/demo/image/upload/w_${width},q_${quality || 75}/${src}`
}
<Image loader={cloudinaryLoader} src="sample.jpg" alt="Sample" width={800} height={400} />
Font Loading
Font Optimization
Use next/font for automatic font optimization with zero layout shift.
Google Fonts
import { Inter } from 'next/font/google'
const inter = Inter({ subsets: ['latin'] })
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" className={inter.className}>
<body>{children}</body>
</html>
)
}
Multiple Fonts
import { Inter, Roboto_Mono } from 'next/font/google'
const inter = Inter({
subsets: ['latin'],
variable: '--font-inter',
})
const robotoMono = Roboto_Mono({
subsets: ['latin'],
variable: '--font-roboto-mono',
})
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
<body>{children}</body>
</html>
)
}
Use in CSS:
body {
font-family: var(--font-inter);
}
code {
font-family: var(--font-roboto-mono);
}
Font Weights and Styles
const inter = Inter({
subsets: ['latin'],
weight: '400',
})
const inter = Inter({
subsets: ['latin'],
weight: ['400', '500', '700'],
})
const inter = Inter({
subsets: ['latin'],
})
const inter = Inter({
subsets: ['latin'],
style: ['normal', 'italic'],
})
Local Fonts
import localFont from 'next/font/local'
const myFont = localFont({
src: './fonts/MyFont.woff2',
})
const myFont = localFont({
src: [
{
path: './fonts/MyFont-Regular.woff2',
weight: '400',
style: 'normal',
},
{
path: './fonts/MyFont-Bold.woff2',
weight: '700',
style: 'normal',
},
],
})
const myFont = localFont({
src: './fonts/MyFont-Variable.woff2',
variable: '--font-my-font',
})
Tailwind CSS Integration
import { Inter } from 'next/font/google'
const inter = Inter({
subsets: ['latin'],
variable: '--font-inter',
})
export default function RootLayout({ children }) {
return (
<html lang="en" className={inter.variable}>
<body>{children}</body>
</html>
)
}
module.exports = {
theme: {
extend: {
fontFamily: {
sans: ['var(--font-inter)'],
},
},
},
}
Preloading Subsets
Only load needed character subsets:
const inter = Inter({ subsets: ['latin'] })
const inter = Inter({ subsets: ['latin', 'latin-ext', 'cyrillic'] })
Display Strategy
Control font loading behavior:
const inter = Inter({
subsets: ['latin'],
display: 'swap',
})
Don't Use Manual Font Links
Always use next/font instead of <link> tags for Google Fonts.
<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
import { Inter } from 'next/font/google'
const inter = Inter({ subsets: ['latin'] })
Common Mistakes
import { Inter } from 'next/font/google'
const inter = Inter({ subsets: ['latin'] })
const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
@import url('https://fonts.googleapis.com/css2?family=Inter');
import { Inter } from 'next/font/google'
const inter = Inter({ subsets: ['latin'] })
const inter = Inter({ subsets: ['latin'], weight: ['400', '700'] })
const inter = Inter({})
inter = ({ : [] })
Font in Specific Components
import { Inter, Playfair_Display } from 'next/font/google'
export const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
export const playfair = Playfair_Display({ subsets: ['latin'], variable: '--font-playfair' })
import { playfair } from '@/lib/fonts'
export function Heading({ children }) {
return <h1 className={playfair.className}>{children}</h1>
}
Cache Components (Next.js 16)
File Level
'use cache'
export default async function Page() {
const data = await fetchData()
return <div>{data}</div>
}
Component Level
export async function CachedComponent() {
'use cache'
const data = await fetchData()
return <div>{data}</div>
}
Function Level
export async function getData() {
'use cache'
return db.query('SELECT * FROM posts')
}
Optimistic UI for Server Actions
When Client Components need data:
Option 1: Pass from Server Component (Preferred)
async function Page() {
const data = await fetchData();
return <ClientComponent initialData={data} />;
}
'use client';
function ClientComponent({ initialData }) {
const [data, setData] = useState(initialData);
}
Option 2: Fetch on Mount (When Necessary)
'use client';
import { useEffect, useState } from 'react';
function ClientComponent() {
const [data, setData] = useState(null);
useEffect(() => {
fetch('/api/data')
.then(r => r.json())
.then(setData);
}, []);
if (!data) return <Loading />;
return <div>{data.value}</div>;
}
Option 3: Server Action for Reads (Works But Not Ideal)
Server Actions can be called from Client Components for reads, but this is not their intended purpose:
'use client';
import { getData } from './actions';
import { useEffect, useState } from 'react';
function ClientComponent() {
const [data, setData] = useState(null);
useEffect(() => {
getData().then(setData);
}, []);
return <div>{data?.value}</div>;
}
Note: Server Actions always use POST, so no HTTP caching. Prefer Route Handlers for cacheable reads.
Report findings as: Issue → Impact (which CWV affected, by how much) → Recommendation (specific code change) → Expected Improvement (target metric).
Always reference the Next.js skill (⤳ skill: nextjs) for framework patterns. For monitoring setup, configure drains via Dashboard or REST API.
