Add SSR DbClient and live query identity

.changeset/modern-dbs-hydrate.md

@@ -0,0 +1,25 @@
+---
+'@tanstack/db': minor
+'@tanstack/react-db': minor
+'@tanstack/svelte-db': minor
+'@tanstack/react-router-with-db': minor
+'@tanstack/electric-db-collection': minor
+'@tanstack/query-db-collection': patch
+'@tanstack/powersync-db-collection': patch
+'@tanstack/rxdb-db-collection': patch
+'@tanstack/trailbase-db-collection': patch
+'@tanstack/db-sqlite-persistence-core': patch
+---
+
+Add SSR through request-scoped `DbClient` instances, collection descriptors,
+explicit collection-row hydration, live-query result snapshots, adapter sync
+metadata, and React and Svelte descriptor resolution.
+
+React live queries now derive identity from structured query IR. Opaque queries
+can provide `queryKey`; legacy dependency arrays and unkeyed opaque queries keep
+working with development warnings until 1.0.
+
+Add TanStack Router integration that streams live queries discovered during a
+Suspense render as pending promises which resolve to ordered result snapshots.
+The browser starts normal source sync and atomically replaces the snapshot when
+its live result is ready.

.github/SSR_RELEASE_PLAN.md

@@ -0,0 +1,69 @@
+# TanStack DB SSR Release Plan
+
+## Release Goal
+
+Ship TanStack DB SSR as a single coherent story:
+
+- explicit collection-row hydration and live-query result snapshots through
+  `DbClient`
+- React and Svelte provider and descriptor resolution
+- derived live query identity with `queryKey` only when necessary
+- backwards-compatible dependency arrays with dev warnings until 1.0
+- a working TanStack Start demo and E2E proof
+
+## Pre-release Validation
+
+- Run `pnpm --filter @tanstack/db test`.
+- Run `pnpm --filter @tanstack/react-db test`.
+- Run `pnpm --filter @tanstack/svelte-db test`.
+- Run `pnpm --filter @tanstack/react-router-with-db test` (includes type
+  tests).
+- Run `pnpm --filter @tanstack/query-db-collection test`.
+- Run `pnpm --filter @tanstack/db-sqlite-persistence-core test`.
+- Run `pnpm --filter @tanstack/db-example-react-start-ssr-e2e test:e2e`.
+- Run `pnpm --filter @tanstack/db-example-react-next-ssr-e2e test:e2e`.
+- Run `pnpm test:docs`.
+- Run `pnpm test:sherif`.
+- Run `pnpm build`.
+
+## Demo
+
+- Live URL: https://tanstack-db-ssr-demo.netlify.app/ssr-db
+- Deploy `examples/react/start-ssr-e2e` to an SSR-capable host.
+- Verify the deployed `/ssr-db` route serves SSR HTML with hydrated rows.
+- Verify browser hydration succeeds without console/page errors.
+- Verify the streamed collection chunk updates the live query.
+- Verify `/ssr-db-stream` streams a projected result, omits source-only data,
+  and hands off to browser sync.
+- Run `PLAYWRIGHT_BASE_URL=https://tanstack-db-ssr-demo.netlify.app pnpm --filter @tanstack/db-example-react-start-ssr-e2e test:e2e:hosted`.
+- Add the live URL to the PR description and release notes.
+
+## Docs
+
+- Publish the [SSR and Hydration guide](../docs/guides/ssr.md).
+- Link the guide from overview, quick start, live queries, and React overview.
+- Regenerate API reference docs in a dedicated docs-maintenance pass if broad
+  TypeDoc output churn is acceptable.
+- Confirm docs explain when `queryKey` is necessary and when it should be
+  omitted.
+- Confirm docs say dependency arrays warn now and are removed in 1.0.
+
+## Migration Messaging
+
+- Lead with: explicit collection preloads transport normalized rows; live-query
+  preloads transport only their result snapshot.
+- Emphasize that existing apps keep working.
+- State that `createCollection(...)` remains available, but SSR apps should use
+  `collectionOptions(...)` plus `DbClient`.
+- Explain that React dependency arrays are deprecated with a 1.0 removal path.
+- Show `queryKey` only for opaque functional query logic or hot render paths.
+
+## Announcement Checklist
+
+- PR description includes high-level summary, migration cheat sheet, and test
+  commands.
+- Release notes include a "No removals in this release" compatibility section.
+- Discord announcement links the SSR guide and live demo.
+- Example migration diff is available from the Start SSR demo.
+- Follow-up issues are filed for the remaining framework adapters and API
+  reference generation if they are not part of the shipping PR.

.github/workflows/e2e-tests.yml

@@ -45,6 +45,7 @@ jobs:
         run: |
           pnpm --filter @tanstack/db-ivm build
           pnpm --filter @tanstack/db build
+          pnpm --filter @tanstack/react-db build
           pnpm --filter @tanstack/electric-db-collection build
           pnpm --filter @tanstack/offline-transactions build
           pnpm --filter @tanstack/query-db-collection build
@@ -68,6 +69,21 @@ jobs:
         env:
           ELECTRIC_URL: http://localhost:3000
 
+      - name: Install Playwright browsers
+        run: |
+          cd examples/react/start-ssr-e2e
+          pnpm exec playwright install --with-deps chromium
+
+      - name: Run React Start SSR E2E tests
+        run: |
+          cd examples/react/start-ssr-e2e
+          pnpm test:e2e
+
+      - name: Run Next.js SSR E2E tests
+        run: |
+          cd examples/react/next-ssr-e2e
+          pnpm test:e2e
+
       - name: Run Node SQLite persisted collection E2E tests
         run: |
           cd packages/node-db-sqlite-persistence

.gitignore

@@ -10,6 +10,8 @@ yarn.lock
 build
 coverage
 dist
+playwright-report
+test-results
 
 # misc
 .DS_Store
@@ -19,6 +21,7 @@ dist
 .env.test.local
 .env.production.local
 .next
+next-env.d.ts
 
 npm-debug.log*
 yarn-debug.log*

docs/collections/local-only-collection.md

@@ -192,10 +192,12 @@ export const modalStateCollection = createCollection(
 
 // Use in component
 function UserProfileModal() {
-  const { data: modals } = useLiveQuery((q) =>
-    q.from({ modal: modalStateCollection })
-      .where(({ modal }) => eq(modal.id, 'user-profile'))
-  )
+  const { data: modals } = useLiveQuery({
+    query: (q) =>
+      q
+        .from({ modal: modalStateCollection })
+        .where(({ modal }) => eq(modal.id, 'user-profile')),
+  })
 
   const modalState = modals[0]
 
@@ -248,10 +250,12 @@ export const formDraftsCollection = createCollection(
 
 // Use in component
 function CreatePostForm() {
-  const { data: drafts } = useLiveQuery((q) =>
-    q.from({ draft: formDraftsCollection })
-      .where(({ draft }) => eq(draft.id, 'new-post'))
-  )
+  const { data: drafts } = useLiveQuery({
+    query: (q) =>
+      q
+        .from({ draft: formDraftsCollection })
+        .where(({ draft }) => eq(draft.id, 'new-post')),
+  })
 
   const currentDraft = drafts[0]
 

docs/collections/local-storage-collection.md

@@ -263,10 +263,12 @@ export const userPreferencesCollection = createCollection(
 
 // Use in component
 function SettingsPanel() {
-  const { data: prefs } = useLiveQuery((q) =>
-    q.from({ pref: userPreferencesCollection })
-      .where(({ pref }) => eq(pref.id, 'current-user'))
-  )
+  const { data: prefs } = useLiveQuery({
+    query: (q) =>
+      q
+        .from({ pref: userPreferencesCollection })
+        .where(({ pref }) => eq(pref.id, 'current-user')),
+  })
 
   const currentPrefs = prefs[0]