# Astro Performance > Core Web Vitals and performance optimization for Astro sites. LCP preloading, font strategy, image patterns, critical path, third-party scripts, Cloudflare Tag Gateway. Use for performance tuning. - Skill: `soborbo/astro-performance` (Agent Skill, multi-file: 11 files) - Install (CLI): `npx skillmds@latest add soborbo/astro-performance` - Raw SKILL.md: https://api.skillmd.com/api/skills/soborbo/astro-performance/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: Soborbo (https://skillmd.com/u/soborbo) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/soborbo/astro-performance --- # Astro Performance Skill ## Purpose Achieve 90+ Lighthouse mobile scores and pass Core Web Vitals on every page. Direct impact on SEO rankings, crawl priority, and conversion rates. ## Core Web Vitals Targets | Metric | Good | Needs Improvement | Poor | |--------|------|-------------------|------| | **LCP** (Largest Contentful Paint) | ≤2.5s | 2.5–4s | >4s | | **INP** (Interaction to Next Paint) | ≤200ms | 200–500ms | >500ms | | **CLS** (Cumulative Layout Shift) | ≤0.1 | 0.1–0.25 | >0.25 | ## Critical Path Rule **The critical rendering path must be max 3 hops:** HTML → CSS → LCP image. Anything that adds a 4th hop (font in CSS chain, extra CSS file, unpreloaded image) adds 150–500ms to LCP on mobile. This is the #1 cause of poor mobile scores. ``` GOOD: HTML (150ms) → Layout.css (150ms) → Hero image (preloaded, parallel) Total: ~300ms to FCP, ~500ms to LCP BAD: HTML (150ms) → Layout.css (150ms) → italic font (350ms) → Hero image (discovered late) Total: ~650ms to FCP, ~2000ms+ to LCP ``` ## Core Rules ### 1. LCP Preloading (Biggest Impact) **Every page MUST pass its hero image to BaseLayout for preloading:** ```astro ``` BaseLayout renders: `` - The `preloadImage` prop auto-detects MIME type from extension - Each page passes its OWN hero image — never hardcode a single image for all pages - Only ONE `fetchpriority="high"` per page (the preload + the `` tag) ### 2. Font Strategy **Primary fonts (body, headings):** `font-display: swap` + preload in `` **Non-critical variants (italic, display, decorative):** `font-display: optional` + lazy CSS ```html ``` **Why:** A font in the main CSS adds it to the critical path chain (HTML → CSS → font = +300–500ms). Moving non-critical fonts to lazy CSS removes them from the chain entirely. **Never preload non-critical fonts** — that defeats the lazy loading. ### 3. Images **Use the `` component from astro-images skill** with pattern-based srcset. See [images reference](references/images.md) for details. Key rules: - Three formats always: AVIF → WebP → JPG (never PNG fallback for photos) - 480w variant in every pattern - `loading="eager"` on hero and above-fold only - `loading="lazy"` on everything below-fold - Never `loading="lazy"` on hero. Never `loading="eager"` on below-fold. - Explicit `width`/`height` on ALL images including SVGs - `width`/`height` must match delivered dimensions, not original source ### 4. Third-Party Scripts **Defer everything that isn't essential for first render.** ```astro ``` See [third-party scripts reference](references/third-party-scripts.md) for Cloudflare Tag Gateway details. ### 5. CSS Strategy - ONE main CSS file (Layout.css) — this is the only render-blocking CSS allowed - Component CSS that's only used below-fold: use `