The Astro web framework has a new technique for rendering content into web experiences called Server Islands. Astro already boasts many options and possibilities for developers to choose from when planning their sites and applications, so we’ve created a guide to help understand what this new technique is, how to use it, and when to choose it.
#tl;dr
In this guide, you’ll find a simple example site demonstrating the use of Server Islands and the steps needed for you to create this for yourself. Alternatively you can clone and deploy the example code with a click of the button below if you are happier exploring that way. We’ll also help you understand how this rendering pattern works and when you might want to use it.
Just deploy an example
We’re going to step through some details to add server islands to any Astro site below, but if you’d rather simply clone and deploy this example site right away, and then explore your newly cloned code, you can do that by clicking the button below.
#The state of rendering for complex sites
Since the dawn of CGI scripting languages, web developers have been able to choose whether to serve static HTML pages or enlist an application server to dynamically render and serve HTML for each request.
For many years, dynamic rendering (e.g. Rails, Wordpress, etc.) was the default choice for content-rich sites because of its flexibility, but the advent of static site generators (e.g. Hugo, Jekyll, etc.) shook up this arrangement by introducing a build process that handled templating, routing and rendering, and could even be triggered to run automatically on a build server (hello, Netlify 👋🏼).
These SSGs formed the foundations of the frameworks we use today (e.g. Astro, Remix, Next.js, etc.) and in many cases we can now choose to render statically or dynamically on a per-route basis, rather than letting our choice of technology dictate the rendering strategy for the whole site.
#Why should we choose one over the other?
Simply put, static rendering is more performant because the response can be served at the edge and does not need to be computed on-demand. It’s also more reliable because rendering errors will be surfaced at build time rather than at run time.
On the other hand, dynamic rendering allows for personalised content (based on information available at run time, e.g. location or identity) and for serving information that changes frequently.
#How are server islands different from other techniques?
Astro’s Server Islands allow your choice of rendering strategy to be even more granular, enabling you to choose static or dynamic rendering on a per-component basis.
This means the majority of a page can be statically rendered at build time and served from the edge, while a handful of components (the ‘islands’) can be dynamically rendered per request, thus offering the benefits of both static and dynamic rendering.
Astro implements this technique by leaving ‘slots’ in the statically rendered shell and injecting a small script into the HTML that fetches the dynamic components during the page load and drops them into the slots. This is all handled automatically by Astro and the Netlify deploy adapter.
A richer example
Our example is intentionally very simple, but the nice folks at Astro have made a more illustrative example:
#Astro Islands
It’s worth clarifying that Astro Server Islands are different to standard Astro Islands, which improve performance by allowing you to selectively ‘hydrate’ components, i.e. load JavaScript only for components that need it, instead of making the entire page interactive. In fact, a component can be both an Island and a Server Island!
#Client rendering
There are similarities between Server Islands and client rendering, a form of dynamic rendering leveraged by some frameworks that uses JavaScript to render parts of a page in the browser, sometimes fetching data from a server to do so. However, Server Islands are different because the data fetching and rendering work remains on the server, which avoids exposing data endpoints and is more performant because the component does not need to be hydrated in the browser.
#ISR
Incremental Static Regeneration is a dynamic rendering technique that uses a CDN, such as Netlify, to cache a response for a period of time before triggering a re-render in the background (either time-based or on-demand). It offers some of the benefits of static and dynamic rendering and can be used as an alternative to Server Islands if a page has frequently changing content but does not rely on personalisation or other run time information.
#Middleware
Conversely, if a page has a limited number of variations that should be selected depending on run time information, such as location or language, edge middleware can be used to parse this information and rewrite the request to a specific variant of a statically rendered page.
#Build your islands - exploring an example
The example shows how Server Islands work and you can see it in action by clicking the Deploy to Netlify button.
Alternatively, if you want to add Server Islands to your own site you can follow the simple steps below.
- Install the Netlify adapter with
npx astro add netlifyif you haven’t already done so - Ensure the adapter is defined in your
astro.config.mjsfile, the output method is set to eitherhybridorserverand experimentalserverIslandsare set totrue:
export default defineConfig({ output: "hybrid", adapter: netlify(), experimental: { serverIslands: true, },});- Make any component into a Server Island by including the
server:deferdirective when referencing it, for example, here we have a component called Avatar which we’ll define as a Server Island:
<Avatar server:defer />- Deploy your site! 🚀
In our example we’ve added a 2 second delay to the Quote component, which demonstrates how this technique might be used on a component that fetches data from an API. The static part of the page should load instantly, while the Server Island renders in the background and drops into the page when ready.
#When to use patterns like server islands
Server Islands combine the benefits of static and dynamic rendering and have fewer limitations than alternative approaches such as client rendering, ISR and middleware. They are particularly useful for pages that are mainly static, but have a small number of components that require up-to-the-minute data or high-cardinality personalisation.
A good example is a product detail page on an e-commerce site. The bulk of the content can be statically rendered (or perhaps ISR rendered) alongside a handful of dynamic Server Island components such as the product quantity or account avatar.
#When not to use server islands
It’s best to avoid using Server Islands when there is a high ratio of dynamic content to static content. In cases such as this, e.g. a data dashboard, it’s better to use dynamic rendering for the whole page because of diminishing returns on performance.
Additionally, if your dynamic content doesn’t depend on run time information and doesn’t update very often you might want to consider ISR. Or if your dynamic content doesn’t change but has a limited number of run time permutations then you might want to consider middleware rewrites.
#Netlify’s plan to power patterns we don’t yet know about
This latest rendering pattern being championed excites us at Netlify for a number of reasons.
It’s clever, but it’s not magic. This approach is using some already well established techniques and technologies that are not proprietary or exotic. The team at Astro did smart things to make using them logical and well integrated into their framework. The developer experience is great and remains easy to reason about.
Meanwhile, we at Netlify did not need to build anything new or custom in order for Server Islands to work. Our efforts had been done much earlier in building out the types of platform primitives that could enable all sorts of solid behaviours in the web sites and applications hosted here.
This tallies well with one of our core strategies to providing a healthy home for sites built with different frameworks — provide sensible defaults, and access to powerful primitives.
Many developers will be able to build their sites and applications on Netlify without needing to ever understand some of the deeper power and controls available on the platform. Things should just work. Others building more exotic experiences have access to more control and configurations which can be added progressively as needed. And others still may be in the business of creating frameworks for others. Framework authors are doing wonderful innovation in the web space, and we’re determined to provide them with the platform capabilities that can power this, and the next generation of frameworks and patterns.
Astro is innovating in a number of areas, and we’re excited to be able to help by providing a fertile ground for the framework to do new and interesting things.
#More resources
Any supporting and additional links