SSR docs rewrite #5966

Ephem · 2023-09-06T09:24:34Z

Most of this content is applicable in v4 as well, except for naming of useSuspenseQuery etc, but I've written and targeted this to the v5 branch.

There are four guides that progressively builds knowledge:

Performance & Request Waterfalls (new)
- This is just about Request Waterfalls performance today, and that's reflected by the slug. We could add other performance tips later or split that to it's own page. This is mostly a background/foundation page, but does include practical tips too.
Prefetching & Router Integration
- Client focused, but lays the foundation for the server parts.
- Mostly kept the old content around at the top of the page for quick reference.
Server Rendering & Hydration
Advanced Server Rendering (new)

I'm open to suggestions on naming for the pages.

There are two existing doc pages that are related to these:

I'm not sure what to do with these. While there is some duplicate content there, they are also short and practical so I think I'm leaning towards keeping them around for discoverability. It's also good that these are mentioned early/high up in the guide pages navigation, while these 4 guides are more in depth and makes sense to have further down in the navigation.

I removed some content related to setting up React Query with custom SSR solutions. I don't think that's relevant to a majority of people, and the step by step instructions are still there so people can figure it out. If we want this I think it would fit better as an example, but I wont include that in this PR. Other than that, I don't think I removed any information, just added, rewrote or restructured.

Also includes initial scaffold for new prefetch/SSR docs structure

vercel · 2023-09-06T09:24:37Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

1 Ignored Deployment

Name	Status	Preview	Comments	Updated (UTC)
query	⬜️ Ignored (Inspect)	Visit Preview		Sep 25, 2023 5:54pm

nx-cloud · 2023-09-06T09:25:39Z

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 0c846b9. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this branch

⌛ The following target is in progress

nx affected --targets=test:eslint,test:lib,test:types,test:build,test:bundle

Sent with 💌 from NxCloud.

codesandbox-ci · 2023-09-06T09:27:04Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 0c846b9:

Sandbox	Source
@tanstack/query-example-react-basic-typescript	Configuration
@tanstack/query-example-solid-basic-typescript	Configuration
@tanstack/query-example-svelte-basic	Configuration
@tanstack/query-example-vue-basic	Configuration

TkDodo

awesome work so far @Ephem 👏

TkDodo · 2023-09-11T09:43:52Z

docs/react/guides/prefetching.md

+
+Before jumping into the different specific prefetch patterns, let's look at the `prefetchQuery` and `prefetchInfiniteQuery` functions. First a few basics:
+
+- If **fresh** data for this query is already in the cache, the data will not be fetched


That's technically true, but can be quite confusing. For this to work, React Query needs to know about "freshness" / "staleness", but that is a property of Observers, not the Query itself. If you call queryClient.prefetchQuery({ queryKey, queryFn }) without explicitly passing staleTime, the default one will be taken. If you haven't set a global default staleTime, the default of zero will always trigger a new fetch with prefetchQuery, even if there is data in the cache.

When we prefetch, we usually don't have an active Observer via useQuery. So even if we set staleTime on our useQuery call, by the time we call prefetchQuery, the default is still used. I think this is worth pointing out.

Excellent point! I copied this from the old docs and didn't think much about it, should be fixed now.

TkDodo · 2023-09-11T09:44:51Z

docs/react/guides/prefetching.md

+- If a `staleTime` is passed eg. `prefetchQuery({ queryKey: ['todos'], queryFn: fn, staleTime: 5000 })` and the data is older than the specified `staleTime`, the query will be fetched
+  - (If you want to ignore `staleTime` and instead always return data if it's available in the cache, you can use the `ensureQueryData` function.)
+- If no instances of `useQuery` appear for a prefetched query, it will be deleted and garbage collected after the time specified in `gcTime`
+- These functions does not return the query data. If that's something you need, use `fetchQuery`/`fetchInfiniteQuery` instead.


Suggested change

- These functions does not return the query data. If that's something you need, use `fetchQuery`/`fetchInfiniteQuery` instead.

- These functions do not return the query data. If that's something you need, use `fetchQuery`/`fetchInfiniteQuery` instead.

I would also point out that a Promise<void> is returned so that it can be awaited, but it will never throw errors (so you don't need try/catch).

Oh yeah! The error one has bit even me in the past, glad you pointed it out. Fixed.

TkDodo · 2023-09-11T09:47:43Z

docs/react/guides/prefetching.md

+  const prefetch = useCallback(() => {
+    queryClient.prefetchQuery({
+      queryKey: ['details'],
+      queryFn: getDetailsData,
+      // Prefetch only fires when data is older than the staleTime,
+      // so in a case like this you definitely want to set one
+      staleTime: 60000,
+    })
+  }, [queryClient])


can we skip the wrapping in useCallback ? Having it in the docs feels like its required to do it, but it's not. We pass that event handler to a built-in <button> component, so it doesn't matter if it's a new function on every render.

Good point, fixed!

docs/react/guides/prefetching.md

TkDodo · 2023-09-11T09:52:11Z

docs/react/guides/prefetching.md

+  // Prefetch
+  useQuery({
+    queryKey: ['article-comments', id],
+    queryFn: getArticleCommentsById,
+  })


another optimization we could point out that even if we ignore the result of useQuery, we still have an active observer that is subscribed to all changes of that query, so we will get a bunch of re-renders of this component even though it's not really necessary.

This is a technical limitation of how property tracking works: If you "use" no property during rendering, you "use" all of them because you could potentially access them in effects or event handlers.

To avoid this, we can pass notifyOnChangeProps: [] to this useQuery:

// Prefetch useQuery({ queryKey: ['article-comments', id], queryFn: getArticleCommentsById, notifyOnChangeProps: [] })

This might even be a valid enough use-case to have a usePrefetchQuery hook that returns nothing 🤔 ?

Nice one, added! Didn't know about that myself actually.

Yeah, I think there is a strong argument for adding that, it also encourages prefetching which is nice. If we add it, let's make sure it matches any fetch/read API for the suspense side of things. We could probably have just one common prefetch hook for both.

docs/react/guides/prefetching.md

Ephem · 2023-09-22T18:27:28Z

Phew, I need to re-read this during the weekend, but it should be ready for review now. It might not be perfect, but I hope it's better than the current docs at least.

I'd love high level feedback as well. Are the pages too long/verbose/tries to cover too much? Are there sections we could skip or are there sections we should add? Also, I've made a few "official recommendations" in there, do you agree with them? I am biased towards prefetching, does that shine through too much? What about the naming of the guides, specifically, should we call the "Advanced Server Rendering" guide "Server Components & Streaming" instead?

Finally, this messes up the Vue docs for prefetching since those are just copied from the React docs, and there are now React specific things in there. I wont have time to fix this properly right now, do you want me to just copy the old doc over into the Vue docs folder in this PR?

TkDodo

wonderfully written ❤️

docs/react/guides/prefetching.md

docs/react/guides/ssr.md

docs/react/guides/advanced-ssr.md

Ephem

Super valuable feedback @TkDodo, thanks so much! I'll tackle it right away.

docs/react/guides/prefetching.md

docs/react/guides/ssr.md

docs/react/guides/advanced-ssr.md

Ephem · 2023-09-25T13:58:54Z

I think I managed to fix all your feedback @TkDodo, I resolved the minor stuff directly but left the comments about clarifications/reformulations open for you to look at. 😄

docs/react/guides/advanced-ssr.md

Ephem added 2 commits September 6, 2023 10:47

docs(react-query): add Request Waterfalls guide

41262c5

Also includes initial scaffold for new prefetch/SSR docs structure

docs(react-query): update prefetching guide

4546e2b

TkDodo reviewed Sep 11, 2023

View reviewed changes

Ephem added 4 commits September 20, 2023 09:59

docs(migration-guide): add more hydration api changes to migration guide

c9e9315

docs(prefetching): polish prefetching docs

e9b03d4

docs(react-query): rewrite ssr doc page

50d6faa

docs(react-query): add advanced server rendering guide

c947c7d

Ephem marked this pull request as ready for review September 22, 2023 18:16

Ephem changed the title ~~WIP: SSR docs rewrite~~ SSR docs rewrite Sep 22, 2023

Merge branch 'beta' into ssr-docs-rewrite

93851df

TkDodo reviewed Sep 25, 2023

View reviewed changes

Merge branch 'beta' into ssr-docs-rewrite

fe1f103

TkDodo changed the base branch from beta to rc September 25, 2023 08:27

Ephem commented Sep 25, 2023

View reviewed changes

docs(react-query): add clarifications to ssr docs

39c182b

Merge branch 'rc' into ssr-docs-rewrite

e71a018

TkDodo reviewed Sep 25, 2023

View reviewed changes

docs/react/guides/advanced-ssr.md Show resolved Hide resolved

docs(react-query): add note about Suspense for streaming ssr plugin

0c846b9

TkDodo merged commit 6e238af into TanStack:rc Sep 26, 2023
6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

SSR docs rewrite #5966

SSR docs rewrite #5966

Ephem commented Sep 6, 2023 •

edited

Loading

vercel bot commented Sep 6, 2023 •

edited

Loading

nx-cloud bot commented Sep 6, 2023 •

edited

Loading

codesandbox-ci bot commented Sep 6, 2023 •

edited

Loading

TkDodo left a comment

TkDodo Sep 11, 2023

Ephem Sep 20, 2023

TkDodo Sep 11, 2023

Ephem Sep 20, 2023

TkDodo Sep 11, 2023

Ephem Sep 20, 2023

TkDodo Sep 11, 2023

Ephem Sep 20, 2023

Ephem commented Sep 22, 2023

TkDodo left a comment

Ephem left a comment

Ephem commented Sep 25, 2023


		Before jumping into the different specific prefetch patterns, let's look at the `prefetchQuery` and `prefetchInfiniteQuery` functions. First a few basics:

		- If fresh data for this query is already in the cache, the data will not be fetched

	- These functions does not return the query data. If that's something you need, use `fetchQuery`/`fetchInfiniteQuery` instead.
	- These functions do not return the query data. If that's something you need, use `fetchQuery`/`fetchInfiniteQuery` instead.

SSR docs rewrite #5966

SSR docs rewrite #5966

Conversation

Ephem commented Sep 6, 2023 • edited Loading

vercel bot commented Sep 6, 2023 • edited Loading

nx-cloud bot commented Sep 6, 2023 • edited Loading

☁️ Nx Cloud Report

codesandbox-ci bot commented Sep 6, 2023 • edited Loading

TkDodo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Ephem commented Sep 22, 2023

TkDodo left a comment

Choose a reason for hiding this comment

Ephem left a comment

Choose a reason for hiding this comment

Ephem commented Sep 25, 2023

Ephem commented Sep 6, 2023 •

edited

Loading

vercel bot commented Sep 6, 2023 •

edited

Loading

nx-cloud bot commented Sep 6, 2023 •

edited

Loading

codesandbox-ci bot commented Sep 6, 2023 •

edited

Loading