Server islands

[ascorbic]

Summary

Allow islands within a prerendered page to be server-rendered at runtime.

Background & Motivation

Often a page may be mostly static, but with only parts that need to be rendered on-demand. For example, a product page might need to show stock levels or personalised recommendations. Currently the only option for these is to either render the whole page on demand, or to render the dynamic parts on the client. This proposal introduces the concept of deferred islands, which are not prerendered, but rather server rendered on demand at runtime.

Next.js is working on a solution called partial pre-rendering, which allows most of the page to be prerendered, with individual postponed parts rendered using SSR on-demand. The implementation is quite different from what I propose for Astro, but the concept is similar.

Goals

• Allow the shell to be fully rendered as valid, cacheable, static HTML, with optional placeholders for postponed islands.
• Replace the deferred islands at runtime, using server-rendered HTML
• Require no JavaScript except a very small script to load the data
• Load the deferred islands individually and asynchronously, allowing each to be rendered as soon as it is available
• Allow access to on-demand rendering features in deferred components, such as cookies and the response object
• Allow components to know if they are currently being rendered in deferred mode

Possible goals

• Allow deferred components to be cacheable (see GET vs POST)

Non-goals

• Automatic pre-rendering of deferred components. Only fallback content would be pre-rendered
• Batching of requests for deferred content. At this stage there would be one request per component, with batching as a possible later optimization
• Allowing components to default to deferred rendering. Deferring would be specified at the page level.

Example

A component would be deferred by setting the server:defer directive.

<Like server:defer />

The "fallback" slot can be used to specify a placeholder that is pre-rendered and displayed while the component is loading.

<Avatar server:defer>
    <div slot="fallback">Guest</div>
</Avatar>

The page can pass props to the component like normal, and these are available when rendering the component:

---
import Like from "../components/Like";

export const prerender = true;

const post = await getPost(Astro.params.slug)
---
<Like server:defer post={post.id} />

The component itself does not need to do anything to support deferred rendering, so it should work with any existing component. However deferred components can optionally use special powers, and can detect if they were deferred by checking the Astro.deferred prop. This means that it was deferred at build time but is now being rendered on-demand.

The special powers are because during deferred rendering, a component is rendered like a mini page. This means it can use features such as Astro.cookies, and setting headers on Astro.response. The Astro.url and Astro.request.url are from the original page, and are passed in the request along with the props.

---
// Like.astro

const { post } = Astro.props

let user = { name: "Guest" }

// If this is a deferred render then we may have a user's cookie
if (Astro.deferred) {
    user = await getUser(Astro.cookies.get('session'))
}
---

<div>
    <span class="name">{user?.name}</span>
</div>

Implementation

When rendering the static page, postponed elements would not be rendered, and instead would render an <astro-island> containing any placeholder. The <astro-island> would embed the serialized props, as well as the URL for the deferred endpoint.

When the page has loaded, a request would be made to each deferred endpoint (see "GET vs POST" below for considerations). This request would pass all of the props and other serialized context.

On the server, the component would be rendered effectively in a thin wrapper page that decoded and forwarded the props, and rewrites the Astro global values.

When the browser has loaded the response from the endpoint, it would use it to replace the content of the island.

The runtime for replacing the deferred islands would be in an inline script tag. A simplified version without error handling could look like this:

document.addEventListener("DOMContentLoaded", () => {
    document.querySelectorAll("astro-island[defer]").forEach(async (element) => {
        const props = JSON.parse(element.getAttribute('props'));
        const endpoint = element.getAttribute('component-endpoint');
        const response = await fetch(endpoint, {
            method: "POST",
            body: JSON.stringify({ props, url: document.location.href })
        }).then(res => res.text());
        const range = document.createRange()
        range.selectNodeContents(element)
        const fragment = range.createContextualFragment(response)
        range.deleteContents()
        range.insertNode(fragment)
    })
})

GET vs POST

One of the unanswered questions is whether to use GET or POST requests for the deferred component endpoints. The benefit of the POST is that it can send arbitrarily large request bodies. The benefits of GET are that they are cacheable and can be preloaded in the page head. Some options are:

• always use POST. This is the simplest option, both to use and implement, but does not allow caching or preloading
• use GET, unless the props are too long in which case fallback to POST. This avoids users needing to make choices, but could lead to unexpected results where a component becomes uncacheable when the props get too long
• allow users to opt-in to cacheable contents. This would be more flexible and potentially allow the use of default cache headers. However it could be hard to teach, and would require builds to be failed if the props get too long.
• use POST, but implement local caching. This would be a lot more complex to implement, but would be easier for users. It wouldn't benefit from CDN caching but would help for repeat visits. Might be more useful when pages are personalized.

Why not streaming?

A alternative approach would be to send the postponed components in the same response as the initial shell. This is how Next.js PPR is currently implemented. This has some benefits, but I think they are outweighed by drawbacks in most cases. Astro has always been static-first, and I think that approach is best here too.

Primarily, a prerendered, static page is easily cacheable, both in the browser but also in a CDN. This is not the case when the deferred data is in the same response. The benefits of this are that the static part can be cached at the edge, near to users, with a very fast response time. The deferred content can be rendered and served near to the site's data without blocking rendering of the rest of the page. If you want to stream the deferred content in the same response, you either have to render everything at the origin and take the hit on distance from users, or render it all at the edge and take the hit on distance from your data. In some cases rendering everything at the edge is fine (e.g. if there's no central data source or API access), and Astro already supports that.

You can work around this with logic at the edge to combine a local cached shell and a stream of the updates from the origin, and edge middleware to do this could be a helpful option. It still prevents the use of the browser cache though, because it can't make conditional requests for the prerendered page - the whole things needs to be sent on every request in case the deferred data has changed.

[matthewp]

Very cool, I don't know if you saw it but there's an old similar idea here: #116

[ascorbic]

server:dynamic is maybe a better name. Still nt sure of the best syntax for the placeholder though

[natemoo-re]

I'd like to see use:server, personally! But we can bikeshed later 😂

[ascorbic]

No, it's vitally important that we start by choosing the attribute name 😁

[bholmesdev]

Bikeshedding: I see the appeal if server: as the prefix to match our client: directive. The trouble is we don't have a qualifier like load or idle. It's just server:. That's likely where Nate's use:server suggestion comes from. Still, I worry about the parallel to the React community, since they adopted a "use server" pragma for a different purpose.

Perhaps we could keep the server: prefix and set ourselves up for qualifiers in the future. I could imagine:

• server:all - use server for all requests to this component
• server:cached="DURATION" - use server and cache for a specified duration

[ascorbic]

I thiink you're right that use:server could cause confusion. It would also imply that there was a use:client, instead of client:*.

[matthewp]

Very much thinking out loud so don't take this comment to mean a whole like:

• I like that only a small script is needed, but why did you choose SSE? Is there an issue with using using HTTP? Given that Astro components all stream I would think there wouldn't be an advantage to SSE unless I'm missing something.
• If you used something like an Edge Middleware could you avoid the script all together? Middleware fetches the prerendered HTML, streams chunks until it encounters the data-deferred attribute, then fetches deferred content and streams it, then keeps going with the prerendered HTML until the next deferred etc (kind of complicated but cool that it would be possible).
• Given that these are "server islands" I don't think we need the template approach. Can't we just say that the server:deferred directive makes the whole component an island just like client:load etc do?
  • This would be tough if the island is passed a slot though. I could imagine the slot being rendered inside of <template> (we do this for client islands when a slot is unused already) and then passed back to the server island some how (probably would have to be a POST though?).

I still like this idea a lot, it "fits" with Astro in a clean way architecturally and I think would make sense to users.

[ascorbic]

• Yeah, I am pretty agnostic about SSE vs plain streaming. I just used it in the example because the code is a bit simpler.
• The combined stream part is kinda how Next.js does it, and it does have benefits. My main issue with that is that it means the shell isn't cacheable.
• What would be displayed while the island is loading, or would you leave that to the user to handle manually? It feels like somethign that would be common enough to justify first-party handling.

[ascorbic]

Note: this comment was on the older version, and no longer applies to the current design.

[natemoo-re]

Love this proposal! Would be awesome to enable this.

Fallbacks are tricky with the way Astro currently works, but we do control the DSL and could add support for components passed as props if that would be the best possible syntax. We also (quietly) support slot="fallback" for client:only placeholders right now and might be able to re-use that same pattern.

[ascorbic]

I've updated the proposal, based on our discussion in Discord.

[kurtextrem]

I wasn't part of the discord discussion, could you please add a section for why an additional network request is preferred over streaming the server islands in?
I think one of the PPR advantages are it's faster than additional network requests as it doesn't need to do another request. I assume the reason here is caching, but currently the explainer doesn't really elaborate why cachability is to be preferred over streaming (or why there aren't two modes, like streaming PPR and fetch-PPR).

[ascorbic]

I'll add a bit in the doc. I'm not opposed to having streaming as an option, but for caching reasons I don't think it should be the default. If it's purely streaming, there's no way to serve the shell from the edge without using edge SSR or extra edge logic. If it's static then any CDN can easily cache it and serve it quickly, and the dynamic part can be rendered anywhere without affecting the time to render the shell. There was some discussion of optionally using edge middleware as a way to handle streaming, which I think could be a good way of doing it.

[ascorbic]

I've added a new section on this.

[kurtextrem]

Thank you! Sounds good to me

[FredKSchott]

I wonder if export const prerender = true; makes more sense as a better default for output: 'server' if this feature were to land, and asking the user to opt-in to fully-dynamic pages instead. The reason is that we do value a seamless transition from static to server, and the shift in default behavior when you move between the two is pretty jarring, leads to bugs, etc. output: 'hybrid' exists, but asking the user to choose between the three is a bit annoying and hybrid is often considered the "transition" stage between the two.

Speaking of the component, would it make sense for a component to declare itself server-deferred? Is there ever a component that would break unless it was deferred? I don't think there would be, aside from some of our current error messages might be confusing vs. "hey, you forgot to server defer this"

[matthewp]

If output: 'server' and output: 'hybrid' are the same, shouldn't one of them be removed? And if so, is this about the word server being preferred to hybrid?

From my perspective, it would make sense to encourage people to use hybrid, maybe even put it into the templates, and then at a later time deprecate / remove server and static as it sounds like hybrid becomes what Astro always is.

[FredKSchott]

+1, I think I'm on board with everything you're saying here

[matthewp]

This proposal has been accepted as is now stage 2: #945

Please continue the discussion there.

[hckhanh]

Can I use deferred with React component?

[ascorbic]

This RFC is now complete. Can you ask questions in Discord? https://astro.build/chat