Add serverSnapshot fallback to useSyncExternalStore

[daveycodez]

Introduces a serverSnapshot object and passes it as the server snapshot function to useSyncExternalStore in useLiveQuery. This improves compatibility with server-side rendering by providing a default snapshot value.

🎯 Changes

Fixes getServerSnapshot error on Next.js "use client" components without needing dynamic import.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 671c1e6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[pkg-pr-new]

More templates

• todos
• 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@688

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/electric-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

@tanstack/rxdb-db-collection

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: 671c1e6

[KyleAMathews]

Is this useful? I'm not sure I understand the point? You can't disable SSR in next.js?

[daveycodez]

Disabling SSR in Next.js results in slower page loads, and dynamic imports requires a lot of DX overhead that is unnecessary.

This also negatively impacts static export builds, since it prevents entire components from being rendered during the build phase if you put a dynamic client only import wrapper around it.

[daveycodez]

The main purpose is to be able to have SSR rendered skeletons or initialData during the !isReady & isLoading state, so we can serve the pages from edge cache. Having to put a dynamic wrapper around every useLiveQuery will make the hook unmaintainable in the majority of Next.js projects. I'm already testing my variant of this hook and I no longer have to use dynamic imports for it. It would be extremely useful for all of my projects to have this line of code added to the official package.

[samwillis]

I'm slightly nervous of this change as it suggested DB is safe to use on SSR routes, but I fear that collection.preload() in a route loader is currently unsafe with a global collection. We need to check this though as is only a suspicion, it may just slow things down and not leak data.

useLiveQuery being broken in SSR acts as a safeguard against this at the moment, until we fix SSR properly.

[daveycodez]

@samwillis

I'm testing this right now with SSR on TanStack Start, with collections created during SSR, and no issues using my patch. My patch eliminates the error entirely and you get perfect functionality.

The only thing is you need to check isReady && isLoading to determine whether to show loaders.

If we could merge this it would be extremely helpful to support static SSR pages with loaders and fallbackData.

Also if we could add isPending === isLoading || !isReady to more easily determine whether to show loaders.

This would be a huge add if we can merge this fix, there are no downsides that I have seen in any of my testing across Next.js and TanStack Start.

[KyleAMathews]

I appreciate your efforts but this isn't what we want. We are planning on shipping actual SSR support so stay tuned for that. See #709

[daveycodez]

Will we be able to useLiveQuery on SSR routes without needing a HydrationBoundary? I noticed in the PR that serverSnapshot is still omitted in useSyncExternalStore. Not sure if it's addressed somewhere else though.

Should be able to useLiveQuery without needing a HydrationBoundary without needing to disable SSR for the component that is using that hook, same as useQuery, useSWR, etc

[daveycodez]

It's very common to include the 3rd parameter for useSyncExternalStore for great DX across environments, including pre-rendered SSR routes, without requiring complex HydrationBoundary setups. Both can be supported easily with 1-2 lines of code.

https://github.com/TanStack/query/blob/40b296b43fc8f8ff3d8a4ea4d5a64ebc779bdbc9/packages/react-query/src/useBaseQuery.ts#L96

https://github.com/vercel/swr/blob/0b3c2c757d9ce4f7e386a925f695adf93cf9065c/src/index/use-swr.ts#L247

https://github.com/instantdb/instant/blob/f102c4e9625d7f3ac174ccd772f0a553b9e1830b/client/packages/react-common/src/useQuery.ts#L91

https://github.com/aspen-cloud/triplit/blob/d3029ee13e747abeeab8cf5bf64427f77a142e1f/packages/react/src/use-query.ts#L98

https://github.com/nanostores/react/blob/a6ad745cc307881916944ee4d6ba04bdda978dc6/index.js#L23

Without the empty serverSnapshot parameter, I won't be able to useLiveQuery from the official package in my projects.

[daveycodez]

@KyleAMathews

https://react.dev/reference/react/useSyncExternalStore#adding-support-for-server-rendering

You can see here how the React team recommends the 3rd parameter is used with default data to enable SSR to generate the HTML.

[KyleAMathews]

Those all get actual data.

Feel free to use your fork until we get proper SSR support in.

[daveycodez]

They by default, cannot access any data since there is no data by default during an SSR render. They may "attempt" to load initial data if it is provided, but the 3rd serverSnapshot parameter is never omitted. This is done in order to prevent the missing server snapshot error from occurring in SSR. They always default to empty data.