Confession: I spent about three months last summer telling myself that my marketing site’s 340 KB React bundle was fine. It wasn’t fine. The page had a hero, a pricing table, and one dropdown menu, and it was shipping enough JavaScript to run a small SaaS dashboard. I was hydrating a completely static header on a page whose only interactive element was a mobile menu that half the visitors never opened.<\/p>\n
I finally rewrote it in Astro over a weekend. The bundle dropped to 29 KB. Lighthouse went from a yellow 71 to a green 98, and nobody complained about the loss of the shimmering React overhead. What convinced me was Astro islands, specifically the idea that hydration isn’t a page-level decision. It’s a component-level one.<\/p>\n
This post is what I actually ship now, six months in. Not the marketing pitch. The parts I still reach for, the parts I got wrong, and the couple of places I still keep Next.js around.<\/p>\n
Astro’s default is to render everything on the server, ship pure HTML, and send zero JavaScript to the browser. An island is a component you explicitly opt into hydrating. That’s it. The rest of the page stays as static markup and never boots a framework runtime.<\/p>\n
Here’s the pattern I use most. My page is a Compare this to the equivalent in Next.js App Router, where any client component in the tree drags along the React runtime whether you like it or not:<\/p>\n You can split this into server and client components in Next, and I do, but the boundary is easier to forget. Astro forces the boundary to be explicit, one component at a time. The official islands documentation<\/a> has a solid explanation of how the compiler handles this if you want the deeper dive.<\/p>\n The client directives sound like they’d overlap. They don’t. My rough rules after six months:<\/p>\n The one I got wrong at first was Server islands landed properly in Astro 5<\/a> and they’re the feature that convinced me to migrate the rest of the site, not just the marketing pages. The idea is that parts of a page needing fresh data (a user’s cart badge, a personalized greeting) can render as separate async chunks after<\/em> the main HTML ships.<\/p>\n The syntax is a single prop:<\/p>\n The static parts stream instantly. The This is what Next.js Partial Prerendering promises, and Astro’s version is simpler to reason about. There’s no I’d be lying if I said this was a clean migration. A few things I’ve hit.<\/p>\n Shared state between islands is annoying. If my The framework boundary can leak. I have one component that imports a utility from a React library that imports another React library, which pulls in Testing islands is still awkward. Vitest works for the React component itself, but integration tests that verify a component actually hydrated when it scrolled into view are painful. I’ve mostly given up and rely on Playwright for that layer.<\/p>\n And there’s still no clean story for interactive form validation across an entire page without either pulling a form library into an island or falling back to progressive enhancement with a server endpoint. I do the latter, and it’s fine, but it’s more code than a Next.js server action.<\/p>\n If you’ve got a Next.js marketing site sitting on a bloated bundle, here’s the fifteen-minute experiment I’d run. Spin up .astro<\/code> file (HTML plus a bit of frontmatter for the server-side bits), and I import React components only where I actually need interactivity:<\/p>\n---\n\/\/ src\/pages\/pricing.astro\nimport Layout from '..\/layouts\/Layout.astro';\nimport PricingTable from '..\/components\/PricingTable.astro';\nimport CurrencyToggle from '..\/components\/CurrencyToggle.tsx';\n---\n\n<Layout title="Pricing">\n <h1>Pick a plan<\/h1>\n <CurrencyToggle client:idle \/>\n <PricingTable \/>\n<\/Layout>\n<\/code><\/pre>\nPricingTable.astro<\/code> renders on the server and ships as HTML. CurrencyToggle.tsx<\/code> is a React component, but it only gets hydrated because I added client:idle<\/code>. Without a client:*<\/code> directive, the React would render server-side and then ship as HTML with no runtime.<\/p>\n\/\/ app\/pricing\/page.tsx\n'use client';\nimport { useState } from 'react';\nimport PricingTable from '.\/PricingTable';\nimport CurrencyToggle from '.\/CurrencyToggle';\n\nexport default function Page() {\n const [currency, setCurrency] = useState('USD');\n return (\n <>\n <h1>Pick a plan<\/h1>\n <CurrencyToggle value={currency} onChange={setCurrency} \/>\n <PricingTable currency={currency} \/>\n <\/>\n );\n}\n<\/code><\/pre>\nWhen I reach for
client:idle<\/code> vs client:visible<\/code> vs client:only<\/code><\/h2>\nclient:load<\/code> hydrates immediately when the page loads. I use it almost nowhere because it defeats the point of islands. If a component needs to be interactive before the browser is idle, I usually rewrite it to not need to be.<\/p>\nclient:idle<\/code> hydrates during the browser’s requestIdleCallback<\/code>. This is my default for anything above the fold that isn’t critical for first paint. A currency toggle. A login button that opens a modal on click. A dropdown that shows when you tap the avatar.<\/p>\nclient:visible<\/code> hydrates when the component scrolls into view, using IntersectionObserver under the hood. My default for anything below the fold: comment sections, related-post carousels, testimonial sliders that nobody scrolls to on a mobile viewport.<\/p>\nclient:only=\"react\"<\/code> skips server rendering entirely and renders only on the client. I reach for this when a component depends on window<\/code> or a client-side store like localStorage<\/code> that would throw during SSR.<\/p>\nclient:load<\/code>. I was using it out of caution, and it was quietly killing my TTI numbers. Switching those to client:idle<\/code> was a five-minute change that shaved 200 ms off my interactive time on a mid-tier Android device. That’s the kind of change I’d have hated to make in a Next.js codebase, where hydration is more or less all-or-nothing per route.<\/p>\nServer islands: the async chunk I didn’t know I wanted<\/h2>\n
---\n\/\/ src\/pages\/index.astro\nimport Layout from '..\/layouts\/Layout.astro';\nimport Hero from '..\/components\/Hero.astro';\nimport CartBadge from '..\/components\/CartBadge.astro';\n---\n\n<Layout title="Home">\n <Hero \/>\n <CartBadge server:defer>\n <span slot="fallback">Cart<\/span>\n <\/CartBadge>\n<\/Layout>\n<\/code><\/pre>\nCartBadge<\/code> renders on the server in a second pass, with a fallback shown until the deferred HTML arrives. No client-side fetch, no useEffect, no loading spinner I had to hand-write. The cart count comes from the same database call it always did, but it doesn’t block the initial paint.<\/p>\nunstable_<\/code> prefix and no debate about which components can and can’t be dynamic. If Astro server islands sound like the same architecture I keep coming back to when I wrote about when I actually reach for HTMX instead of React<\/a>, that’s not a coincidence. The whole trend is toward shipping less JavaScript and being explicit about what runs where.<\/p>\nWhere islands still bite me<\/h2>\n
CurrencyToggle<\/code> needs to talk to my PricingTable<\/code>, they can’t share React state, because they’re separate hydration boundaries. I ended up using Nano Stores<\/a> as a shared client-side store, which the Astro docs actively recommend. It works, but it’s a mental gear-shift after years of just passing props.<\/p>\nreact-dom<\/code> at the top level. Even with client:only<\/code>, the initial static render can end up with a giant <script><\/code> block if you’re not careful. I audit my dist\/_astro<\/code> folder after every deploy for anything suspicious.<\/p>\nWhat to try this week<\/h2>\n
npm create astro@latest my-site<\/code>, drop your hero and pricing HTML in as a single .astro<\/code> file, and reimport your one truly interactive component with client:idle<\/code>. Run astro build<\/code>, then check dist\/_astro\/<\/code>. If the total JavaScript is under 40 KB, you’ve got a candidate for migration. If it’s still over 200 KB, chase down the import that’s dragging in the React runtime and either delete it or gate it behind client:only<\/code>.<\/p>\n