Simple Server Island Example

[JusticeMatthew]

During Talking & Docing on 5/29 it was mentioned by Sarah that the Server Islands page could use a good actual example usage and asked for ideas

I don't have any.

But I'm making this discussion to get input from everyone else 👍

[jp-knj]

1. Create a server component

src/components/ServerTime.astro

---
/* Runs only on the server */
const now = new Date().toLocaleTimeString('en-US', { timeStyle: 'medium' });
---
<p style="font: 1.1rem monospace">

⏰ {now}

</p>

2. Use it with server:defer + a fallback

src/pages/index.astro

---
import ServerTime from '../components/ServerTime.astro';
---
<h1>Hello from Astro 4 🎉</h1>
<p>The current time is:</p>
<ServerTime server:defer>

<!-- renders during the brief fetch round-trip -->

<span slot="fallback">loading…</span>

</ServerTime>

What happens?

1. The page HTML ships immediately; the <span slot="fallback"> is visible.

2. The browser fetches /_server-islands/ServerTime in the background.

3. When that island’s HTML arrives, Astro swaps the fallback for the real clock.

Under the hood this is standard HTML plus a tiny inline script, so the main page can be cached while each island stays dynamic.
Official docs: https://docs.astro.build/en/guides/server-islands/

---

3. Requirements & tips

Needs	Notes
Adapter with on-demand SSR (@astrojs/node, Netlify, Vercel, etc.)	server:defer works in Astro 4.12+
Normal Astro build/deploy commands	Islands respect cache headers—add Cache-Control if you want CDN caching

---

Thanks 🙏

[sarah11918]

I was able to test this example and it works nicely, @jp-knj , thank you!

I'm thinking maybe after "How it works" on the Server Islands page, we could have this as a small "Build your first server island" example. (Before "Caching" and other more technical details.) What would you think about adding this there?

Another alternative (perhaps additionally?) would be to create an actual recipe on its own page with a slightly more involved example, perhaps with a fetch call to an API (e.g. displaying the current weather?)

[jp-knj]

Thanks! at sarah11918

I agree we add the small tutorial there. if readers try code first, they can understand better. I also like the weather-api example, verry useful.

I think, make a PR that puts the simple server island example on the current page.
after that open another PR for the recipe page with the weather example. does that plan sound good?

[sarah11918]

Yes, thank you @jp-knj , that sounds great to me! 🚀

[jp-knj]

Hi!

Here are two small Server Island examples that I could come up with:

• GitHub Repo Stats

  • Data changes often (stars, forks, issues),
  • Keep the token on the server,no leakage in the client bundle.
  • Zero hydration

• Currency-Rate Tile Island (USD → JPY)

  • Shows fast-changing data without exposing API keys.
  • Again, no client JS shipped.

[sarah11918]

Ooh, both sound great, but I do like the GitHub repo stats and think that would fit well for the audience!

[jp-knj]

@JusticeMatthew
Do you have any other ideas you’d like to contribute?
If not, I can create a draft PR to propose one