# Core Web Vitals
> Optimize Next.js Core Web Vitals (LCP, CLS, INP/FID) and Lighthouse scores. Triggers on: LCP, CLS, INP, Lighthouse score, Core Web Vitals, next/image, font optimization, layout shift, performance budget.
- Skill: `ultroncore/core-web-vitals` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ultroncore/core-web-vitals`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ultroncore/core-web-vitals/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: UltronCore (https://skillmd.com/u/ultroncore)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ultroncore/core-web-vitals
---
# Core Web Vitals Optimization (Next.js)
## When to Use
Use this skill when diagnosing or fixing performance issues in Next.js production sites: poor Lighthouse scores, slow LCP, layout shifts, janky interactions, or failing Core Web Vitals thresholds in Google Search Console.
---
## Target Thresholds
| Metric | Good | Needs Work | Poor |
|--------|------|------------|------|
| LCP (Largest Contentful Paint) | ≤ 2.5s | 2.5–4s | > 4s |
| CLS (Cumulative Layout Shift) | ≤ 0.1 | 0.1–0.25 | > 0.25 |
| INP (Interaction to Next Paint) | ≤ 200ms | 200–500ms | > 500ms |
---
## LCP Optimization
### 1. Hero Images — `next/image` with `priority`
```typescript
// app/page.tsx — hero image above the fold
import Image from 'next/image'
// ✓ priority tells Next.js to preload this image (removes lazy loading)
// ✓ sizes helps browser pick the right srcset entry
// ✓ fill with a sized container avoids CLS
export default function HeroSection() {
return (
in
sizes="100vw" // full width on all screens
quality={85} // balance quality vs size
className="object-cover"
placeholder="blur" // prevents CLS while loading
blurDataURL="data:image/jpeg;base64,..." // tiny base64 placeholder
/>
)
}
// For non-fill images — always provide width/height
```
### 2. Preload Critical Resources
```typescript
// app/layout.tsx — preload LCP image when src is dynamic/CDN
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{/* Preload LCP image — use when next/image priority isn't enough */}
{/* Preconnect to critical third parties */}
{children}
)
}
```
### 3. Server-Side Rendering for LCP Content
```typescript
// ✓ LCP content should be in initial HTML — not client-fetched
// Use RSC (React Server Components) or generateStaticParams for LCP sections
// app/products/[slug]/page.tsx — static generation
export async function generateStaticParams() {
const products = await db.product.findMany({ select: { slug: true } })
return products.map(p => ({ slug: p.slug }))
}
// Product image is in initial HTML — fast LCP
export default async function ProductPage({ params }: { params: { slug: string } }) {
const product = await db.product.findUnique({ where: { slug: params.slug } })
return (
{product.name}
)
}
```
---
## CLS Prevention
### 1. Always Specify Image Dimensions
```typescript
// ✗ No dimensions — browser can't reserve space → layout shift when image loads
// ✓ Explicit dimensions — browser reserves space before image loads
// ✓ Fill with sized container
{/* aspect-video = 16:9 */}
// ✓ CSS aspect-ratio for responsive images
```
### 2. Skeleton Loaders — Reserve Space
```typescript
// Reserve exact space with skeleton that matches content dimensions
function ProductCardSkeleton() {
return (
{/* Match the 4:3 aspect ratio of the real image */}
)
}
// Use with Suspense
}>
```
### 3. Font Display — Prevent Font Flash Shift
```typescript
// next/font — zero CLS, self-hosted, preloaded automatically
import { Inter, Playfair_Display } from 'next/font/google'
import localFont from 'next/font/local'
const inter = Inter({
subsets: ['latin'],
display: 'swap', // show fallback font until Inter loads
variable: '--font-inter',
preload: true, // default true — preloads on first page with this font
})
const playfair = Playfair_Display({
subsets: ['latin'],
weight: ['400', '700'],
variable: '--font-playfair',
})
// Local font (best performance — zero network request)
const myFont = localFont({
src: [
{ path: '../public/fonts/MyFont-Regular.woff2', weight: '400' },
{ path: '../public/fonts/MyFont-Bold.woff2', weight: '700' },
],
variable: '--font-myfont',
display: 'swap',
})
// Apply in layout
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
)
}
```
### 4. Avoid Dynamic Content Above Existing Content
```typescript
// ✗ Cookie banner inserts above page — everything shifts down
function CookieBanner() {
return
Accept cookies?
}
// ✓ Fixed position — doesn't affect document flow
function CookieBanner() {
return (
We use cookies...
)
}
// ✓ Reserve space in layout if you must show it inline
{/* reserved — no shift when banner appears */}
{showBanner && }
```
---
## INP (Interaction to Next Paint) Optimization
### 1. Code Splitting with `dynamic`
```typescript
import dynamic from 'next/dynamic'
// Heavy components — defer loading until needed
const RichTextEditor = dynamic(() => import('@/components/rich-text-editor'), {
loading: () => ,
ssr: false, // editor requires browser APIs
})
const HeavyChart = dynamic(() => import('@/components/analytics-chart'), {
loading: () => ,
})
// Only load when user interacts
function BlogPost() {
const [showEditor, setShowEditor] = useState(false)
return (
<>
{showEditor && }
)
}
```
### 2. Deferred Rendering for Heavy Components
```typescript
import { useDeferredValue, useTransition, startTransition } from 'react'
// useDeferredValue — defer re-rendering of slow list during typing
function SearchResults({ query }: { query: string }) {
const deferredQuery = useDeferredValue(query) // lags behind input — keeps input responsive
const isStale = query !== deferredQuery // show loading state during transition
const results = useHeavyFilter(deferredQuery)
return (
{results.map(r => )}
)
}
// useTransition — mark state updates as non-urgent
function DataTable() {
const [isPending, startTransition] = useTransition()
const [filter, setFilter] = useState('all')
function handleFilterChange(newFilter: string) {
startTransition(() => {
setFilter(newFilter) // this update is non-urgent — won't block input
})
}
return (
<>
{isPending ? : }
)
}
```
### 3. Debounce Expensive Event Handlers
```typescript
import { useMemo, useCallback } from 'react'
function useDebounce(value: T, delay: number): T {
const [debounced, setDebounced] = useState(value)
useEffect(() => {
const timer = setTimeout(() => setDebounced(value), delay)
return () => clearTimeout(timer)
}, [value, delay])
return debounced
}
// Debounce search to avoid hammering API on every keystroke
function SearchBar({ onSearch }: { onSearch: (q: string) => void }) {
const [query, setQuery] = useState('')
const debouncedQuery = useDebounce(query, 300)
useEffect(() => {
if (debouncedQuery) onSearch(debouncedQuery)
}, [debouncedQuery, onSearch])
return (
setQuery(e.target.value)} // instant — updates input immediately
placeholder="Search..."
/>
)
}
```
### 4. Virtualize Long Lists
```typescript
// Use react-virtual or @tanstack/react-virtual for large lists
import { useVirtualizer } from '@tanstack/react-virtual'
import { useRef } from 'react'
function VirtualList({ items }: { items: Item[] }) {
const parentRef = useRef(null)
const virtualizer = useVirtualizer({
count: items.length,
getScrollElement: () => parentRef.current,
estimateSize: () => 72, // estimated row height in px
overscan: 5, // extra rows rendered above/below viewport
})
return (
// ✓ Explicit dimensions — browser reserves space before image loads