SvelteKit 3 Ideas and Discussions

[AlbertMarashi]

I'd like to come here to suggest some changes to SvelteKit which I believe would benefit everyone.

I think almost everyone can agree that we use Svelte because we like writing code that is:

• Clean
• Easy to write and read
• Less verbose
• Maintainable
• Performant

And we all love to use a framework that:

• Cares about developer ergonomics
• Abstracts away complexities
• Uses magic where necessary
• Works with the developer and not against them

---

First... AsyncLocalStorage

An amazing feature has been released in the javascript server ecosystem - notably, the AsyncLocalStorage primitive which I believe meaningfully changes the game for how frameworks are built and implemented on the server-side.

Is AsyncLocalStorage widely supported?

AsyncLocalStorage appears to be supported by all server runtimes, but feel free to let me know if anything is missing from the list or is not supported.

• Cloudflare as node:async_hooks
• Node as node:async_hooks
• Bun as node:async_hooks
• Vercel as node:async_hooks
• Deno as node:async_hooks

What does this change?

AsyncLocalStorage is a major enabler for SSR frameworks because it finally makes truly isolated, request-level states and storage simple to implement:

• No More Global Leaks
  In traditional server-side applications, it’s hard to store data that only belongs to a single request. If you naively put it in a module-scoped variable, updates to it can leak across multiple concurrent requests because everything in JS runs via a single process. With AsyncLocalStorage, each request can have its own “sandbox” so that data never collides or leaks.

• Native built-in primitive
  Since AsyncLocalStorage is a built-in primitive of server-side runtime APIs, it removes the need for complicated hacks to manage and maintain state. Available across all major server runtimes as far as I am aware.

• Improved Developer Experience
  For SSR applications, especially those with reactivity you often need to attach data or context to a user’s session or request.

  Previously, you had to manually pass that data through each level of your application code or rely on less-reliable and unsafe global objects. AsyncLocalStorage eliminates the repeated boilerplate by letting you write once at the top level, and then access that request-level data anywhere else in your code—even deep in nested components or modules.

• Safer & More Performant
  Because each request automatically could get its own isolated “storage” context, concurrency issues can be drastically reduced by eliminating waterfalls from await parent()'s that load things like database resources. At the same time, you don’t need to verbosely pass down contexts and data down deeply to maintain isolation, helping you maintain and manage code in ways that are cleaner and less verbose.

• Bridging Client and Server States
  AsyncLocalStorage can help us unify how we handle state on the server with how you handle it in the client. Rather than worrying about whether some state is safe to update, we can write request-aware state stores that automatically maintain uniqueness across concurrent SSR calls. This opens the door to more natural, universal reactivity—mirroring the client’s store mechanism while preserving security and correctness on the server side.

  Writing server-side code should feel much like writing client-side code where possible.

Related discussions and issues:

• Sharing a global variable across multiple requests is unsafe in SSR #4339
• Using a Svelte store in the load function causes weird behavior #2213
• Proposal for Svelte 5: Universal Reactivity & Safe SSR Global State? svelte#12947

Tip

All of these benefits—no global leaks, built-in support, improved DX, safer concurrency, and better bridging between client and server—make AsyncLocalStorage a game-changer for SSR applications like those written with SvelteKit.

Examples

Note

In the following section, I'll run through some examples and scenarios that run through the changes these features might allow

Less boilerplate, more parallelization

Before

SvelteKit encourages passing data from one load function to another (await parent() chaining). This sometimes leads to waterfalls if multiple sub-layouts must wait on each other because they all rely on some root layout defined modules.

src/routes/+layout.ts - initialize the user-authenticated database at the top layer

import { Database } from "$lib/db_store.ts"
export async function load({ data: { token } }) {
   const db = new Database({ token })
   await db.connect()
   // all sub load functions need to wait for this request
   // to finish to get access to the database
   const [user] = await db.query("SELECT ONLY * FROM $auth")
   
   return {
     db,
     user,
   }
}

src/routes/app/+layout.ts - make some data available to all sub-pages and layouts of dashboard

export async function load({ parent }) {
   const { db } = await parent() // had to wait for user query
   // load the organisations list that are needed for the layout header
   // even though this data won't be needed for sub-pages
   const organisations = await db.query("SELECT id, name FROM orgs")
   return { organisations }
}

src/routes/app/org/[org]/+layout.ts

export async function load({ parent, params: { org } }) {
   // had to wait for
   // - user query
   // - organisations query
   // plus anything else that might've been needed from `org/+layout.ts`
   const { db } = await parent()
   const [organisation] = await db.query("SELECT * FROM orgs WHERE id = $org", { org }
   return { organisation}
}

After

src/routes/+layout.ts - initialize the user-authenticated database at the top layer

import { database } from "$lib/database.svelte.ts"
export async function load() {
   const db = await database() // parallel with every other load function
   const [user] = await db.query("SELECT ONLY * FROM $auth")
   return { user }
}

src/routes/app/+layout.ts - make some data available to all sub-pages and layouts of dashboard

import { database } from "$lib/database.svelte.ts"
export async function load() {
   const db = await database() // parallel with every other load function
   const organisations = await db.query("SELECT id, name FROM orgs")
   return { organisations }
}

src/routes/app/org/[org]/+layout.ts

import { database } from "$lib/database.svelte.ts"
export async function load({ params: { org } }) {
   const db = await database() // parallel with every other load function
   const [organisation] = await db.query("SELECT * FROM orgs WHERE id = $org", { org })
   return { organisation }
}

src/lib/database.svelte.ts

import { Database } from "@db/client"
import { cookies, isolate } from "@svelte/kit"

export const database = isolate(async () => {
   const db = new Database({ token: cookies.get("auth_token" })
   await db.connect()
   return db
})

Better and easier to use global states

You have a typical authentication system that gets a session cookie. During SSR, you need to figure out which user is logged in and pass that info to your routes and components.

Before

• You rely on handle in src/hooks.server.ts to validate the user session.
• You attach the user to event.locals.user
• Declare the user type it in the App namespace in src/app.d.ts
• Every route that needs user data must either call parent() or look up event.locals in a +(page|layout).server.ts file

After

• You rely on handle in src/hooks.server.ts to validate the user session.
• import it from anywhere (.ts, .svelte.ts, .svelte)

hooks.server.ts

import { user_store } from "$lib/user.svelte.ts"

export const handle = sequence(
  authenticate_user
)

const authenticate_user: Handle = async ({ cookies, resolve }) => {
   // ...
   let user = $state(...)
   user_store.value = user // sets the user for this request
   // hooks, load functions and components beyond this point will have access to user
   return await resolve()
}

src/lib/user.svelte.ts

import type { Handle, IsolatedStore } from "@svelte/kit"

export type User = { ... }

export const user_store = new IsolatedStore<User>()
export const user = $state.isolate(() => store.value)

Internals

// this `symbol` contains a `get current()` method that retrieves the request's current unique symbol
// eg: symbol: { get current(): symbol { ... }
import { request_symbol } from "./internals/request_symbol"

export class IsolatedStore<T> {
  // we use weakmap, so that the server-side user can be deleted after
  // all references to the symbol is garbage collected
  store: WeakMap<symbol, T> = new WeakMap()

  get value() {
     return this.store.get(request_symbol.current)
  }
  set value() {
     return this.store.set(request_symbol.current)
  }
}

Better load functions

Building upon my proposal within the following issue, @giacomoran's issue and Hugo's proposal:

• Teleport data from server to client in universal load functions #9160 (comment)
• Teleport data from server to client in universal load functions #9160 (comment)
• Feature request: Partial load/invalidation #11500

Before

• load functions in SvelteKit run twice, once for server-side load, and once during mount.
• caches fetch request/responses via URL's which are serialized to the client
  • Doesn't cache data from WebSocket's connections (eg: SurrealDB)
  • Doesn't work if you include things like tracking/tracing IDs in request bodies
  • Caches and serializes the entire request/response, even if only part of the data was needed.
  • Can contain inconsistent results that change on hydration (eg: Math.random())
• load functions mutating state in .svelte.ts files leads to race-conditions that can leak state between requests.
• Cannot invalidate part or parts of specific load functions

After

• load functions run once on initial server-side load, with all states transferred to the client
• works for most if not all use-cases (fetch, WebSockets, ServiceWorker hooks, etc)
  • Serializes exactly the data we need and nothing more
• Uses the newly added Transport API for serializing non-pojos
• load functions can safely mutate isolated states in .svelte.ts files thanks to request-aware state/stores.
• Partial invalidates are allowed.

Tip

• Easier to reason about
• Less security footguns
• Serializes only necessary data instead of entire reqs/responses
• More deterministic mounting behavior
• Improved partial invalidation (see below)

invalidate, parent and dependency improvements

Building upon Hugo's proposal, see his issue for more context:

• Feature request: Partial load/invalidation #11500

Whenever having 2 data fetches in a load function and want to for example only invalidate the first you cannot do that

Using typescript module augmentation features, we can enforce the type-safety of Svelte's invalidate functions, ensuring code refactors don't accidentally break things, and enabling amazing features and functionality previously not possible.

/products/+page.ts

// exporting an object-based `const load` makes the individual loaders run and resolve in parallel
// and automatically get unique invalidation IDs from the compiler
// no need to declare `depends("app:foo")` across your load functions which
// is error-prone, untyped and subject to surface area for bugs during refactors...

// invalidate id: "/products/+page.ts`
export const load = {
  // invalidate id: "/products/+page.ts:load_products"
  load_products: () => ({ products: [{ id: 123 }] }),
  // invalidate id: "/products/+page.ts:load_profile"
  load_profile: () => ({ profile: { name: "John Doe" } }),
}

/checkout/+page.ts

// invalidate id: "/checkout/page.ts`
export async function load() {
  return {
    cart: [{ id: 123, qty: 2 }]
  }
}

Typed invalidate functions

namespace App {
  interface LoadType {}
  type LoadTypeID = keyof LoadType
}

function invalidate(resource: App.LoadTypeId): Promise<void>

Generated types

// Default declared by svelte namespace
declare namespace App {
  interface LoadType {}

  type LoadTypeID = keyof LoadType
}

// Generated `./$types` for `/products/+page.ts`
declare namespace App {
  interface LoadType {
    "/products/+page.ts:load_profile": { profile: { name: "John Doe" } }
    "/products/+page.ts:load_products": { products: [{ id: 123 }] }
    "/products/+page.ts": LoadType["/products/+page.ts:load_profile"] & LoadType["/products/+page.ts:load_products"]
  } 
}

// Generated `./$types` for `/checkout/+page.ts`
declare namespace App {
  interface LoadType {
    "/checkout/+page.ts": [{ id: 123, qty: 2 }]
  }
}

type X = App.LoadTypeId
// equivalent to:
type X = 
 | "/checkout/+layout.ts"
 | "/products/+page.ts"
 | "/products/+page.ts:load_profile"
 | "/products/+page.ts:load_products"

let x: App.LoadType["/app/+page.ts"]
// equivalent to
let x: {
  profile: { name: "John Doe" }
  products: [{ id: 123 }]
}

• User's could also ensure/be forced to declare any other depends(...) IDs in their App.LoadType interface (but, almost nobody would ever need to use this)

loadDependency(dep: App.LoadTypeId) thingy

Why not just bin parent() all together? we almost always want some specific data from parent load and layout functions.

Explicitly declaring dependencies in this way allows us to be a lot more explicit and correct in regards to module dependencies

/+layout.ts

export const load = {
  async init_db() {
      //...
      return { db }
  },
  get_user() {
     return { user: { name: "John Doe" } }
  }
}

/app/dashboard/+page.ts

// alternative by importing from `$app/request` module
import { dependency } from "$app/request"

export const load = {
  async orgs({ dependency /** could declare directly in here too **/ }) {
    const [{ db }, { user }] = await dependency("/+layout.ts:init_db", "/+layout.ts:get_user")
    // or:
    const [{ db, user }] = await dependency("/+layout.ts")

    // do something with db and user
    return { orgs } // or `{ orgs, db, user }` possibly
  }
}

/app/dashboard/+page.svelte

<script lang="ts">
import { dependency, route } from "$app/request"

let [{ orgs }] = await dependency(route)
// or:
let orgs = await dependency({ route, key: "orgs" })
// or, for async rendering:
let orgs_promise = dependency({ route, key: "orgs" })
</script>
{#await orgs_promise}
  Loading orgs...
{:then orgs}
   <!-- render the orgs, SSR will wait for promise to resolve -->
{:catch err}
Oops { err.code} 
{/await}

Asynchronous components and asynchronous server-side rendering

Related issue:

• Async/streaming SSR renderer svelte#958

The Current Limitation

Right now, Svelte’s SSR is designed to run synchronously. That is:

• When the server renders a .svelte component, it doesn’t expect to wait on any promises inside of <script> code or the template itself.
• {#await promise}{...}{/await} blocks are typically meant for client-side logic, so that the server doesn’t block or fork the SSR pipeline.
• Whilst {#await promise} can work on the server-side with streaming promises, as far as I'm aware, this will result in the data not appearing on the first render, which can negatively impact SEO, as asynchronous indexing is delayed with most search engines...

While this design works, it leads to some awkward patterns:

• Load Functions Everywhere – We end up using SvelteKit’s load functions (or +page.ts, +layout.ts) to handle all async data fetching. If a component itself needs data, it’s forced to rely on the load function or pass props down.
• Immediate Return of SSR: On the server, the output must be rendered in one synchronous go, meaning any sub-component that tries to do await in its <script> code is out of luck.

Key reason for these constraints (I believe): SSR concurrency is complicated when multiple components each do asynchronous tasks at once — especially if they each use, and mutate state during rendering operations...

Eliminating the Synchronous Requirement

If we trust that each SSR request is isolated, SvelteKit (or a future version) could allow a “root-level async render,” meaning:

• Render could start immediately, but for each async boundary (like {#await promise}{...}{/await} or a top-level await in a <script> block), the rendering engine can pause, wait for the promise, and then resume/continue generating HTML.
• In other words, we no longer strictly require a single synchronous pass to produce the final HTML. Instead, SvelteKit can orchestrate an async rendering pass in a single request context.

How it might look in code

src/routes/app/org/[org]/members/+page.svelte

<script lang="ts">
import { database } from "$lib/database.svelte.ts"
import { params } from "$app/page"

const db = await database()
</script>
<h1>Organisation Members</h1>
{#await database.query("SELECT * FROM members WHERE org = $org", { org: params.org }) }
  <!--
  Instead of the server rendering this, we'll just wait for the promise

  but will render/appear during client-side routing, since the page
  immediately renders upon navigation (or if the `params.org` changes)
  instead of waiting for the `load` function equivalent to return
  -->
  <p>Loading organisation members...</p>
{:then members}
  <members>
    {#each members as member}
       ... 
    {/each}
  </members>
{:catch error}
  <p>Failed to get organisation members.</p>
{/await}
{#await database.query("SELECT * FROM pending_invites WHERE org = $org", { org: params.org }) }
  <p>Loading pending invites...</p>
{:then invites}
  <invites>
    {#each invites as invite}
       ... 
    {/each}
  </invites>
{:catch error}
  <p>Failed to get organisation member invites.</p>
{/await}

Tip

Why this matters

Less reliance on load functions

• Instead of “I must do all async logic in +page.ts or +layout.ts”, you can place async fetching directly in component <script>s.
• This can reduce the ceremony of passing props around just to get data into a subcomponent that’s solely responsible for displaying it.
• Saves us from having to write verbose load functions for most +page.svelte files for when only simple async data may be needed for a specific component

More ergonomic, maintainable code

• Many developers find it intuitive to call await exactly where they need the data.
• You can co-locate fetch logic with the component that uses it, simplifying code organization.

Cleaner parallelization

• With concurrency, multiple sub-components could asynchronously perform operations, appended/merged together into the streaming HTTP response
• This can cut down on the "waterfall" effect that sometimes occurs when everything goes through a single load chain (no need to do things like await Promise.all(get_user_promise, get_member_promise) or etc in your load functions)

Universal code and faster client-side navigation

• Clients don't need to wait for a client-side navigation to retrieve all the data from load functions before rendering everything - instead, they can immediately start rendering the page with whatever data becomes available
• No more “Wait, that’s a SSR or load-only concern.” Instead, you can write code in your components that “just works” on both server and client, without extra dancing around how to handle async data fetching.
• Thanks to AsyncLocalStorage, mutating and accessing state in different modules can be safely isolated on the server-side.

Parallel {#await ...}s on server-side

If multiple components are each doing their own await calls, SvelteKit’s SSR engine could:

• Start rendering at the top-level.
• For each component that hits an async boundary, fork an async sub-routine that fetches the needed data.
• Once that sub-routine finishes, it merges the rendered output into the final HTML stream, with returned data serialized into as a hydration comment (or something like that) for client-side mounting.
• Because each SSR run is safely contained in an AsyncLocalStorage context, we avoid mixing up states from concurrent requests.

Putting it all together

With request-level isolation courtesy of AsyncLocalStorage and an asynchronous SSR pipeline, SvelteKit (or a future Svelte version) could allow truly async components in SSR

• <script> can have await statements.
• {#await promise} blocks can fully resolve server-side.
• Data fetching becomes more direct, letting you co-locate logic in the component that needs it.
• Parallel data loading and mutation across multiple subcomponents is safer because each SSR request is sandboxed.
• Cleaner overall developer experience—code that naturally reads “fetch data and then show it” can remain the same whether you’re SSR or client-side.

This new paradigm would bring SvelteKit closer to a world where the boundary between server and client is simpler, more consistent, and more powerful—without giving up the hallmark performance and simplicity Svelte is known for.

Cleaner, simpler server code and APIs

In SvelteKit today, when you create a +server.ts file (an API endpoint), you typically have this signature:

+server.ts

export const GET = async ({ request, cookies, fetch, params, locals, ... }) => {
  // do something
}

Or maybe you have a function in $lib/whatever.ts that needs the same references passed in:

+server.ts

import { do_whatever } from "$lib/whatever.ts"

export async function GET(event) {
  return do_whatever(event.fetch, event.cookies, event.locals.db, ...);
}

And in every module that needs request-specific details — like user authentication, cookies, database instances, or svelte's specialized fetch function — you must pass them as parameters.

This leads to:

• Repetitive and verbose boilerplate
• Harder to maintain complex dependencies
• Painful refactorings

The solution

$lib/whatever.ts - Inside do_whatever (or any deeper library call), we just call the getters available under the "$app/request" module:

import { cookies, params, fetch } from "$app/request"
import { database } from "$lib/database.svelte.ts"
import { track } from "$lib/analytics.ts"

export async function do_whatever() {
   cookies.set("foo", "bar", { path: "/" })
   const device_id = cookies.get("device_id")
   const db = await database

   const external = await fetch("https://api.example.com");
   const some_data = await db.query("SELECT ...")

   return {
     some_data,
     external: await external.json()
   }
}

$app/request module

• $app/request a module that can be imported from any (component).svelte +server.ts, +(page|layout).ts files.
  • cookies - a universal cookies module for setting and getting cookies (available on the client side too, except for httpOnly cookies)
  • symbol - low level access to the symbol primitive, which returns null for client-side code.
  • fetch - a global svelte fetch wrapper, so you don't need to pass it down everywhere in your app
  • url - a global, reactive request-aware URL
  • route - a global reactive { id: RouteId }
  • params - global request parameters object (eg: /app/blog/[post] => { post: string })

Plus more ideas...

• feat: typed +server.ts responses with fetch #11108

[seantiz]

I like the global invalidate function (besides the internal one) but it's a small enough piece of code that I could just implement it myself.

The rest doesn't seem like it affects me either way, except for the idea of "async subroutines" which sounds like the kind of thing that took down Python's async library into an abstraction headache. More than one layer on top of async is too many in my honest view.

[JonathonRP]

I like the async components and renders and top level await