VitePress Core Web Vitals Checklist (Production Audit)

Tested on: VitePress 1.6.3, PageSpeed Insights + CrUX, 28-day field data Starting point: 68% URLs "Good" → 91% after checklist.

LCP (target < 2.5s)

• Hero image WebP, fetchpriority="high" on home only
• Font: use system stack OR font-display: swap

.vitepress/config.mts:

head: [
  ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }],
]

I removed Google Fonts entirely — LCP -0.4s.

• prefetchLinks: false on 300+ page sites (reduces contention)

INP (target < 200ms)

• Defer third-party scripts (analytics, ads)
• Local search OK — miniSearch runs on input; debounce:

// custom theme wrapper — optional 100ms debounce on search input

• Avoid heavy onMounted in custom components

Measured INP 185ms → 95ms after deferring Plausible + ads.

CLS (target < 0.1)

• Width/height on images
• min-height on ad slots
• Code blocks: overflow: hidden + stable line-number gutter

div[class*='language-'] { contain: layout; }

TTFB

Static on Cloudflare Pages — not a VitePress issue. Ensure cache-control on HTML reasonable (1h).

docs/public/_headers (copied to dist):

/*
  Cache-Control: public, max-age=3600, must-revalidate
/assets/*
  Cache-Control: public, max-age=31536000, immutable

Audit commands

npm run docs:build && npm run docs:preview
npx lighthouse http://localhost:4173/guide/performance-test/ \
  --only-categories=performance,accessibility,seo \
  --preset=desktop

Field data: GSC → Experience → Core Web Vitals.

Common VitePress-specific failures

Issue	Fix
LCP = logo SVG tiny	Not a problem; real LCP is text block
CLS on font swap	System fonts
INP spike on mobile menu	Default theme OK; check custom JS
Large JS bundle	Analyze dist/assets — Shiki chunks

Verify checklist run monthly

npx unlighthouse --site https://docs.myproduct.com --budget 90

Result

CrUX "Good" URLs 68% → 91%. Organic traffic +6% (correlation, not sole cause).