Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท Performance and Deployment

Astro Performance and Core Web Vitals

Keep Astro sites fast: measure LCP, CLS and INP, control JavaScript with islands, optimise images, fonts and third-party scripts, and set a budget.

Astro starts fast: pages are HTML with no JavaScript unless you ask for it. But "fast by default" is not "fast forever". A single heavy island, an unoptimised hero image, or an analytics tag can undo the advantage. This lesson shows what to measure, what usually goes wrong, and how to fix it.

The three Core Web Vitals

Google's field metrics for real users:

Metric Measures Good
LCP (Largest Contentful Paint) When the biggest visible element (hero image, headline) appears 2.5 s or less
CLS (Cumulative Layout Shift) How much content jumps around 0.1 or less
INP (Interaction to Next Paint) How quickly the page responds to clicks and taps 200 ms or less

Static HTML from a CDN usually gives excellent LCP. CLS comes from missing image dimensions, late fonts and injected banners. INP depends on JavaScript: the more you hydrate, the worse it can get.

Measure first

  • Lighthouse (Chrome DevTools) for lab tests of one page. Run it in an incognito window on the production build (astro build && astro preview), never the dev server.
  • PageSpeed Insights adds real-user data (CrUX) when the site has enough traffic.
  • WebPageTest for detailed waterfalls on slow networks.
  • The browser Network tab: sort by size, filter by JS. If you see 300 KB of framework code on a content page, find out which island pulled it in.

Test on a throttled mobile profile; your laptop is the best case, not the typical one.

Control JavaScript

  1. Default to no directive. Render components to HTML. Only add client:* where interaction is required.
  2. Choose the lightest directive. client:visible for below-the-fold; client:idle for non-essential; client:media for mobile-only; client:load rarely.
  3. Prefer an Astro component or inline script when a small interaction (toggle a menu, copy a code block) can use 10 lines of plain JavaScript instead of a framework island.
  4. Use one framework, not three, so you ship one runtime.
  5. Watch dependencies. One import of a big date or chart library can add tens of KB. Check with a bundle visualiser (rollup-plugin-visualizer as a Vite plugin).
ASTRO
---
// A date-heavy widget that nobody sees until the footer
import Calendar from '../components/Calendar.jsx';
---
<Calendar client:visible />

A rough budget many teams use: under 100-150 KB of JavaScript (compressed) on a typical page, and far less for content pages.

Images and fonts

Images are the usual LCP element:

  • Use <Image />/<Picture /> so you get modern formats and correct sizes.
  • Mark the LCP image loading="eager" and fetchpriority="high"; keep everything else lazy.
  • Always have width and height, which <Image /> supplies.
  • Fonts: self-host, WOFF2, font-display: swap, preload one critical font, or use a system stack.

CSS

Astro bundles CSS per page and by default may inline small stylesheets. You can tune it:

JavaScript
export default defineConfig({
  build: {
    inlineStylesheets: 'auto', // 'always' | 'never' | 'auto'
  },
});

auto inlines stylesheets under a size threshold to save a request. Unused CSS from a global import is the larger risk: avoid importing entire UI kits when you use two components.

Third-party scripts

Analytics, chat widgets and ads are frequent INP killers. Options:

  • Load them late: <script defer> or after requestIdleCallback.
  • Move them off the main thread with Partytown (@astrojs/partytown) and type="text/partytown".
  • Question each one: a lightweight privacy-friendly analytics script may be enough.

Caching and delivery

  • Put the site behind a CDN. Static HTML and /_astro/* assets travel from the nearest edge.
  • Give /_astro/* a one-year immutable cache (the file names contain hashes).
  • Compress responses (Brotli) and use HTTP/2 or HTTP/3, which most hosts do for you.
  • For SSR pages, send Cache-Control: s-maxage=... with stale-while-revalidate so the CDN absorbs traffic, and consider server islands for personalised parts.
ASTRO
---
Astro.response.headers.set(
  'Cache-Control',
  'public, max-age=0, s-maxage=300, stale-while-revalidate=600',
);
---

A performance checklist

  1. Build with astro build, serve with astro preview, run Lighthouse on mobile.
  2. Hero image is optimised, eager and sized.
  3. Fonts self-hosted and limited to what is needed.
  4. Each island has a justification and the lightest directive.
  5. No third-party script on the critical path.
  6. Static assets have immutable caching; HTML revalidates.
  7. Re-test after each new dependency.

Try it: a JavaScript budget

This stand-in sums the compressed size of the scripts a page ships, based on which islands it uses, and compares against a budget. Adjust the numbers to see how quickly a runtime adds up.

JS JS budget calculator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try it: a layout-shift score

CLS adds up each shift as impact fraction * distance fraction. This stand-in computes it for a few events, showing why banners injected above content hurt.

JS Calculate CLS

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which metric is most affected by hydrating many large islands?

    More JavaScript on the main thread makes the page slower to respond to input, which INP measures.
  2. 2. What is the best first step before optimising?

    Optimise what you measured. The dev server and a fast laptop hide the real problems.
  3. 3. Which image should be eager with high fetch priority?

    The LCP element should start loading immediately; everything below the fold should stay lazy.
  4. 4. How can analytics scripts be kept off the main thread?

    Partytown runs third-party scripts in a web worker so they cannot block interaction.

Summary

  • Track LCP, CLS and INP; test the production build on throttled mobile.
  • Ship as little JavaScript as possible: no directive by default, lightest directive otherwise, one framework.
  • Optimise the LCP image, fonts and CSS; keep third-party scripts off the critical path.
  • Cache hashed assets for a year; let the CDN absorb HTML traffic.

Next: View Transitions