astro-performance

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.
• NEVER use .map() to spawn dozens of client:* islands in a loop. If you have a list of items that each get a client:visible or client:load directive, you are creating N separate island instances. Instead, render list items as static HTML and hydrate a single controller or filter component that manages the entire list.

When you find hydration storms, apply these fixes:

1. Audit every client:* directive in the project. For each one, ask: does this component need interactivity on page load, or can it wait?
2. Replace client:load with client:visible for components below the fold. Replace with client:idle for components that need interactivity but not immediately.
3. Break large interactive sections into small, granular islands. Extract the interactive parts (buttons, forms, toggles) into their own island components, and leave surrounding content as static Astro markup.