How to Use Server Islands in Astro

A server island lets one part of a page be made fresh on each visit. The rest of the page stays static. Here is how to set one up, with the adapter it needs.

By the AstroBeginner team. Reviewed by Blaise Kavai, VP of ProductPublished November 6, 20266 minute readSome basics

Most of a page can be built once, ahead of time. Sometimes one piece can’t. A greeting with the visitor’s name. A stock count. The price right now. A server island makes just that piece on each visit. The rest of the page stays fast, and it can be saved in a cache.

What you need

A server island is made on demand. That means the server makes it when someone asks for it. So your project needs an adapter. An adapter is a small add-on that teaches Astro how to run on a certain host. This guide uses the Node.js adapter. It is the simplest to test with. Cloudflare, Netlify and Vercel have adapters too.

npx astro add node

Say yes to the changes. The command adds the adapter to astro.config.mjs.

Step 1: Write the island

Make a file called src/components/ServerTime.astro. It is a normal Astro component. The only difference is when it runs:

---
// This runs on the server when the island is requested, not at build time.
const now = new Date().toLocaleTimeString('en-US', { timeZone: 'UTC' });
---
<p>Server time right now: {now} UTC</p>

Inside a server island you can do anything an on-demand page can do. Read cookies. Fetch data. Check a session.

Step 2: Add it to a page with server:defer

---
import Layout from '../layouts/Layout.astro';
import ServerTime from '../components/ServerTime.astro';
---
<Layout title="Live">
  <h1>A mostly static page</h1>
  <p>This part was built ahead of time.</p>
  <ServerTime server:defer>
    <p slot="fallback">Loading the time...</p>
  </ServerTime>
</Layout>

The server:defer tag turns the component into a server island. The fallback slot shows while the real words are fetched.

Step 3: Build and look

Run npm run build. The page is still made ahead of time. Its HTML holds “Loading the time…” plus a small script. The script asks for the island from a /_server-islands/ address. When you run the site, that request returns the fresh time. The script swaps it in.

That is the whole trick. The static page can be cached anywhere. Only the island hits the server.

Passing props

Props are values you hand to a component. They travel in the island’s request. So they must be simple values. Strings, numbers, arrays, plain objects, dates. You can’t pass functions. Keep props small. Astro sends them in the address. If they get long, it switches to a slower request.

Two things to know

The island doesn’t know the page’s address. Inside it, Astro.url points at the island’s own request. Need the page’s query parameters? Pass them in as props.
Putting the site on several servers? Props are encrypted with a key made at build time. Encrypted means scrambled so only the server can read them. Do you use rolling deployments or more than one region? Then run astro create-key. Set the result as the ASTRO_KEY environment variable. Then every server uses the same key.

When to use one

Use a server island when a small part of a page must be fresh or personal, and the rest does not. Does the whole page change for every visitor? Then make the whole page on demand instead. Does nothing change? Then you need neither.

For the browser-side kind of island, see what are Astro islands.

Frequently asked questions

Do server islands work on a static host like GitHub Pages?

No. A server makes the island when someone visits. So you need a host that runs your adapter, such as Node.js, Cloudflare, Netlify or Vercel.

What's the difference between a server island and a client island?

A client island runs JavaScript in the visitor's browser. A server island runs code on your server and sends back HTML. The visitor gets no extra JavaScript from a server island, apart from the small loader.

Keep reading