astro-performancelisted

# Astro Performance Optimization ## Core Mental Model: HTML First, JavaScript Only When Necessary Astro ships ZERO JavaScript by default. This is the primary performance advantage of the framework. Treat every `client:*` directive as a conscious decision to add JavaScript payload to the page. Your goal is to maintain the zero-JS baseline and add interactivity only where it is surgically necessary. Target these Core Web Vitals thresholds on every page: - **LCP** (Largest Contentful Paint): under 2.5 seconds - **CLS** (Cumulative Layout Shift): under 0.1 - **INP** (Interaction to Next Paint): under 200 milliseconds When reviewing or building Astro pages, start from the assumption that zero client-side JavaScript is correct, then justify each addition. ## The Hydration Storm Anti-Pattern (CRITICAL) A "hydration storm" occurs when multiple `client:load` directives cause the browser to download, parse, and execute multiple framework runtimes simultaneously on page load. This is the single most common performance mistake in Astro projects. Watch for these patterns and flag them immediately: - NEVER use `client:load` on multiple components without explicit justification for each one. Every `client:load` fires on page load and competes for the main thread. - NEVER wrap entire page layouts or large sections in a single framework component (React, Vue, Svelte) with `client:load`. This hydrates EVERYTHING inside that component, defeating Astro's island architecture entirely. - NE