Async SSR

[elliott-with-the-longest-name-on-github]

The Svelte team has been hard at work on asynchronous rendering, with client-side support and remote functions as our first two efforts. It’s time for the third: SSR.

Background

There are three core pieces to the async problem:

1. Server-side rendering (the process of running code on the server and creating HTML/JS/CSS from that code)
2. Hydration (the process of taking server-rendered code and attaching interactive JavaScript processes to it)
3. Client-side rendering (the ongoing process of state management and DOM coordination after hydration)

The interplay between these creates a number of challenges for anyone seeking to create a seamless end-to-end experience.

Design

When asynchronously rendering on the server, any await expressions not contained in a svelte:boundary with a pending snippet will block until their associated promise resolves. Await expressions behind a svelte:boundary with a pending snippet will not be reached — but more on that later. This means that if you write the following:

<div>{await delayed("Hey y'all!", 1000)</div>

The resulting HTML output will look like this:

<div>Hey y'all!</div>

…and if you had a boundary with a pending snippet:

<div>{await delayed("Hey y'all!", 1000)</div>
<svelte:boundary>
  <div>{await delayed("What's up?", 1000)</div>
  {#snippet pending()}
    <div>Loading...</div>
  {/snippet}
</svelte:boundary>

…the output would look like this:

<div>Hey y'all!</div>
<div>Loading...</div>

Because we have cool compiler superpowers, we can also optimize your code. The following would take one second to render, not two:

<div>{await delayed("Hey y'all!", 1000)</div>
<div>{await delayed("What's up?", 1000)</div>

You can use await everywhere — in component <script> blocks, in $derived expressions, in templates, and in normal modules and async functions.

What about hydration?

When you render asynchronous content on the server, then send it to the client and hydrate it, one of two things will happen:

• If you rendered a pending snippet on the server, the client will kick off the asynchronous work, replacing the pending snippet when the asynchronous work is done
  • This is… fine… but it means you have to make two server round-trips to finish rendering your content. The first trip gets your SSRed page, the second gets the asynchronous stuff behind the boundary. See the next section for our answer to this.
• If you rendered blocking asynchronous content (anything not behind a pending boundary), that content will be “normally” hydrated

The latter behavior might raise some eyebrows. What it means, practically, is that this:

<div>I slept for {await sleep(Math.random() * 1000)} milliseconds!</div>

Would output something like this on the server:

<div>I slept for 567 milliseconds!</div>

…and then, on the client during hydration, we’d wait for another random amount of time and you’d see it change to:

<div>I slept for 243 milliseconds!</div>

This really isn’t very desirable behavior. During hydration, you typically want to stick with the stuff you rendered on the server unless it actually needs to change! What we need to be able to do is render something asynchronously on the server, then hydrate it synchronously on the client based on what we rendered on the server. This requires serialization at some point. Somehow, we have to get the data you’ve rendered over the wire in such a way that we can retrieve it on the client and hydrate it into reactive JavaScript.

React solves this problem by making the serialization boundary be the client component. Data passed from a server component to a client component has to be serializable so that it can be sent over the wire and used in hydration. The downside of this approach is that React has to live in two worlds, where some of your components are server components (and therefore only run on the server) and some of them are client components (and therefore run on both the server, for initial renders, and the client for subsequent client-side ones). Svelte has always been a very isomorphic framework — we believe the Svelte code you write should be able to run equally well on the server and the client. Keeping to these roots, we think the more logical place to put this serialization boundary is at the resource level — at the actual place you’re fetching the data.

Thankfully, we’ve already taken care of this problem for you with remote functions in SvelteKit. Given a setup like this:

export const getUser = query(v.string(), (id) => getUserFromDatabase(id))

<script>
  import { getUser } from './get-user.remote.js';
  import { page } from '$app/state';
</script>

<h1>Hi, {(await getUser(page.params.userId).name}</h1>

…when server rendering, the result of getUser will be inlined into the resulting HTML, and during hydration, getUser will simply return the data synchronously — no delays or additional requests involved.

“But Elliott, I don’t want to use SvelteKit!” That’s fine! Remote functions have been our exploration into what the best possible version of data-fetching in SvelteKit could be. Now that we’ve had that exploration, we’re working on bringing some of that goodness into Svelte core, so that other framework authors can build similar solutions, or you can make your own.

But what about pending snippets?

The above behavior could be kind of annoying! It means that you have to send your server-rendered content to the browser, then kick off whatever asynchronous work needs to happen to render the non-pending contents of your boundary. We plan to fix this with streaming. In the future, this:

<div>{await delayed("Hey y'all!", 1000)</div>
<svelte:boundary>
  <div>{await delayed("What's up?", 1000)</div>
  {#snippet pending()}
    <div>Loading...</div>
  {/snippet}
</svelte:boundary>

will immediately render the pending snippet, but start rendering the non-pending content in the background. This non-pending content can then be sent to the browser after the initial response. This is the best of both worlds, where you can de-prioritize nonessential content by rendering a skeleton without needing multiple server round trips to fully hydrate your application.

Okay, how do I try it?

It’s out in the latest version of svelte! Just set experimental.async: true in your Svelte compile options. Once you’ve done this, awaiting or calling .then on the result of render will render your component asynchronously. If you’re using a framework, that framework will have to implement support. In the very near future, we’ll release an update to SvelteKit to pick up your compileOptions and automatically use async server rendering if you’ve turned the experimental compile option on.

[Thiagolino8]

What happens if a promise awaited outside a boundary results in an error only on the client?

[elliott-with-the-longest-name-on-github]

Same thing that happens during normal hydration when something throws only on the client -- hydration fails. If you want to catch that error, you can wrap your app in a boundary with an onerror handler or failed snippet.

[Thiagolino8]

It's at times like these that svelte:boundary serving as both a suspense and an error boundary is a weak spot
Having to give up error handling to opt for async SSR doesn't seem like a good trade-off

[elliott-with-the-longest-name-on-github]

You... don't have to? Error boundaries aren't suspense boundaries. This will not block:

<svelte:boundary onerror={() => {}}>
  <div>{await greeting()}</div>
</svelte:boundary>

...would still SSR to this output:

<div>Hello!</div>

A boundary only causes suspense if it has a pending snippet.

[Thiagolino8]

I didn't know that the restriction that required a boundary containing a awaited promise to have a pending snippet had been removed, that's great

[elliott-with-the-longest-name-on-github]

Yeah! Basically everything before hitting a boundary with a pending snippet is what will resolve on the server before being sent to the client.

[BastiDood]

What's the plan for interoperability with the already existing {#await} syntax?

The way I see it: there isn't any reason (syntactically) why {#await} blocks and await expressions shouldn't desugar to the same behavior.

import { browser } from '$app/environment';
export async function work() {
  const value = Math.random();
  console.log({ browser, value });
  return value;
}

{#await work()}
  Pending...
{:then output}
  {output}
{/await}

<svelte:boundary>
  {await work()}
  {#snippet pending()}
    Pending...
  {/snippet}
</svelte:boundary>

Note

In both cases, work executes in the server and the client.

However, in reality, we will see some mismatch in behavior (and thus a breaking change!). In the former example, the work result gets thrown away during SSR and re-executes during hydration in the client. Meanwhile, the latter result gets streamed into the client post-SSR.

For our contrived example of returning Math.random, we will observe two different values if we maintain the "legacy" behavior specifically only for {#await} blocks. But if we want to make the results consistent, we have to accept the downside of breaking changes for the {#await} block (that will now essentially be syntactic sugar over an inlined <svelte:boundary> + pending snippet + await expression).

More generally, what will be the fate of the {#await} block in Svelte 6? Do we maintain the legacy behavior in Svelte 5, deprecate in Svelte 6, and remove in Svelte 7? Or do we bite the bullet and introduce the breaking changes right off the bat in Svelte 6?

[Rich-Harris]

No firm decisions here yet but I'd expect us to deprecate {#await ...} in 6 and remove in 7. Changing the behaviour in the way you describe would be a breaking change (people don't expect it to run on the server), and since it's less powerful/composable than the other async tools in our arsenal (and out of place next to them) I think it makes more sense to get rid of it than to evolve it.

[elliott-with-the-longest-name-on-github]

Just a thought, but for most cases we could probably auto-migrate await blocks to boundaries.

[AndreasHald]

One thing you can do today with load functions is server side rendering the page on initial page load (awaiting a promise in the load function)

But when doing client side navigation streaming the promise with a loading state.

Can this pattern be achieved in this new paradigm?

We don't really use it anywhere so it may not matter. I was just curious because I couldn't think how it would work? A conditional pending snippet?

[elliott-with-the-longest-name-on-github]

Yeah, this is what streaming SSR will buy us.

[Azarattum]

How would this all work with adapter-static? There obviously couldn't be any streaming there... Would it just block once during build and re-execute every-time on the client? Could there be a way to run server-only (build-only) async work and just hydrate the result with whatever we got during that build (like what you've described with remote functions, but at static build time)?

[elliott-with-the-longest-name-on-github]

Yeah, this is a problem your framework is going to have to solve (and, conveniently, one that SvelteKit has solved). In our case, we have prerender remote functions: https://svelte.dev/docs/kit/remote-functions#prerender

[firatciftci]

As someone who converted from years of Next.js-based development, a significant feature that I have been missing from the dark side is streamingMetadata in SSR; basically, in Svelte/SvelteKit, I would love to be able to:

1. Define my <svelte:head> with the async keyword
2. Have the option to set up streaming for SEO so that it does not block page render

Given that we will be able to have both SSR and streaming of async data for regular page render, how possible are these two features above?

[elliott-with-the-longest-name-on-github]

Streaming isn't something we've completely cracked yet, so take this all with a grain of salt. But I don't see why this couldn't work:

<svelte:head>
  <svelte:boundary pending={noop}>
    <title>{await getTitle()}</title>
  </svelte:boundary>
</svelte:head>

There are some things we would have to figure out, for example, how to do the whole "still block your render for bot requests" thing. (That would probably have to be solved by something like SvelteKit.)

[ixxie]

In the Supabase docs for SvelteKit w/ SSR they show how to initialize a client in +layout.ts:

import { createBrowserClient, createServerClient, isBrowser } from '@supabase/ssr'
import { PUBLIC_SUPABASE_PUBLISHABLE_KEY, PUBLIC_SUPABASE_URL } from '$env/static/public'
import type { LayoutLoad } from './$types'

export const load: LayoutLoad = async ({ data, depends, fetch }) => {
  depends('supabase:auth')

  const supabase = isBrowser()
    ? createBrowserClient(PUBLIC_SUPABASE_URL, PUBLIC_SUPABASE_PUBLISHABLE_KEY, {
        global: {
          fetch,
        },
      })
    : createServerClient(PUBLIC_SUPABASE_URL, PUBLIC_SUPABASE_PUBLISHABLE_KEY, {
        global: {
          fetch,
        },
        cookies: {
          getAll() {
            return data.cookies
          },
        },
      })
  const { data: { session } } = await supabase.auth.getSession()

  const { data: { user } } = await supabase.auth.getUser()

  return { session, supabase, user }
}

And then load it into +layout.svelte to ensure auth state is updated:

<script>
  import { invalidate } from '$app/navigation'
  import { onMount } from 'svelte'

  let { data, children } = $props()
  let { session, supabase } = $derived(data)

  onMount(() => {
    const { data } = supabase.auth.onAuthStateChange((_, newSession) => {
      if (newSession?.expires_at !== session?.expires_at) {
        invalidate('supabase:auth')
      }
    })

    return () => data.subscription.unsubscribe()
  })
</script>

{@render children()}

This also has the effect of injecting a Supabase client to your pages, which is conditionally browser or server variant depending on where the environment where the code is run.

How would I do this with remote functions?

[ixxie]

Related Discord thread for broader context: Supabase Remote Function Architecture

[KTibow]

The SvelteKit docs will be updated to work differently - likely to make a function to get the client instead of treating it like data - hope fully soon.

[RuthgerD]

Keeping to these roots, we think the more logical place to put this serialization boundary is at the resource level — at the actual place you’re fetching the data.

Could you elaborate a bit on this? I'm trying to understand how you would implement this yourself.

From what I gather, in sveltekit, the data cache is embedded in the initial html and then the client side code of remote functions acts as if the cache is already populated?.

Thanks :)

[elliott-with-the-longest-name-on-github]

Yeah, so imagine this:

<script>
  // just imagine you're getting the slug from somewhere, and that it could change
  const post = resource(() => getPostFromCMS(page.url.params.slug));
</script>

{@html (await post).html}

Without resources of some sort, you would:

• Make a request to your CMS to get the post
• Render the contents of that post
• Send the response to the client
• The client, during hydration, would make another request to your CMS to get the post again
• The client would overwrite the SSRed post with the new (identical) post that it wastefully got

With resources, whatever is returned from the callback function would be serialized (using some configurable method) and sent along with the SSRed HTML. When it runs on the client during hydration, the resource would say "ah, cool, my results have been sent with the server render", so it would pull them from there and return them immediately instead of running getPostFromCMS again.

This is what SvelteKit already does with fetch results in load functions and with the results of query calls anywhere.

It could be we end up having to make resource a rune, as it could need something like a compile-time-generated ID associated with it to avoid the whole TanStack/SWR thing where you have to come up with a key for all of your resources.

There's a lot still up in the air here, but the overall point is that we'll be shipping some mechanism by which you can render data on the server and stash it so that it's synchronously available during hydration. This has the added benefit of giving you fine-grained control of where the serialization boundaries for your data are, as well.