feat(svelte-db): add SSR and hydration support for SvelteKit

[elohmeier]

Summary

Add SSR and hydration support for @tanstack/svelte-db following the patterns established in #709 for React.

This enables prefetching data on the server and seamlessly hydrating it on the client without a loading flash.

New APIs

Server-side (@tanstack/svelte-db/server):

• createServerContext() - creates context to collect prefetched queries
• prefetchLiveQuery() - prefetches data server-side without starting sync
• dehydrate() - serializes context for JSON transport

Client-side:

• HydrationBoundary - component that provides hydration context to children
• setHydrationContext / getHydrationContext - Svelte context utilities

Changes to useLiveQuery:

• Pass an id in the config object to match with server-prefetched data
• Hydrated data is returned immediately while the collection syncs in background
• isReady returns true when using hydrated data
• Dev warning when HydrationBoundary exists but no matching hydrated data

Usage Example

// +page.server.ts
import { createServerContext, prefetchLiveQuery, dehydrate } from '@tanstack/svelte-db/server'

export const load = async () => {
  const serverContext = createServerContext()
  await prefetchLiveQuery(serverContext, {
    id: 'todos',
    query: (q) => q.from({ todos: todosCollection }),
    transform: (rows) => rows.map(r => ({ ...r, createdAt: r.createdAt.toISOString() }))
  })
  return { dehydratedState: dehydrate(serverContext) }
}

<!-- +page.svelte -->
<script>
  import { HydrationBoundary, useLiveQuery } from '@tanstack/svelte-db'
  let { data } = $props()

  const query = useLiveQuery({
    id: 'todos',
    query: (q) => q.from({ todos: todosCollection })
  })
</script>

<HydrationBoundary state={data.dehydratedState}>
  {#each query.data as todo}...{/each}
</HydrationBoundary>

Test plan

• Existing useLiveQuery tests pass (30/30)
• Build succeeds
• Manual testing with SvelteKit app

Related

• feat: Add SSR/RSC support for live queries in @tanstack/react-db #709 - React SSR/hydration implementation (this PR follows the same patterns)

[changeset-bot]

🦋 Changeset detected

Latest commit: 15cdfba

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@tanstack/svelte-db	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

More templates

• todos
• tanstack-start-example-basic
• @tanstack/db-example-paced-mutations-demo
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• @tanstack/db-example-solid-todo

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@1118

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@1118

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@1118

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@1118

@tanstack/offline-transactions

npm i https://pkg.pr.new/@tanstack/offline-transactions@1118

@tanstack/powersync-db-collection

npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1118

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@1118

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@1118

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1118

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@1118

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@1118

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1118

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@1118

commit: a87a6e3