[RTK Query Migration] Fill out remaining not-yet-covered RTKQ docs content

[markerikson]

Depends on #963 .

Once the RTKQ source/docs content is in this repo, we need to update the RTK docs to include that info. My plan is:

• New RTK Query subcategory under "API Reference", with createApi and friends
• New "RTK Query" subcategory under "Usage Guide", containing the content previously in the RTKQ "Concepts" section

Could also argue it should be its own top-level section in some way (maybe just the "Concepts" material, but not the API reference?)

We'll need to emphasize that this is all exported by the new "@reduxjs/toolkit/query" and "@reduxjs/toolkit/query/react" entry points, not the main "@reduxjs/toolkit" entry point.

This should probably be done on a 1.6 integration branch so that we don't publish it too early.

[markerikson]

Primary migration work was done in #1015 .

Going to leave this open to cover fleshing out the rest of the missing content.

[markerikson]

Missing pieces from discussion:

• Could use an "RTK Overview" page in addition to the Tutorial and Usage Guide areas
• "Comparison" page
• Explanation of why we don't do normalization (put that on "Comparison", maybe?)
• I think some of the hooks aren't fully documented yet
• No TypeScript usage guide and insufficient types docs for the APIs
• Need to cover how to use a custom base query
• Show switching from existing thunk-based fetching logic to RTKQ
• Describe the queryFn option and usage
• Using transformResponse
• split up cache page (Docs - split up cache pages #1092)
• write some kind of 'usage without hooks' content
• possibly re-title the 'Cache Management' page that's under API Reference/Generated API Slices/Cache Management to something that makes it easier to find when looking for the api.util stuff, and fill out missing content on it (Docs - split up cache pages #1092, 📝 Tweak cache management utils page #1113)

[Shrugsy]

Just so it doesn't get missed:

The 'bailing out of errors' section on 'Error Handling' is still TODO also: https://deploy-preview-1016--redux-starter-kit-docs.netlify.app/usage/rtk-query/error-handling#bailing-out-of-errors

[markerikson]

Per a user:

It might be worth adding at least a one-line explanation of "reducerPath" in the Getting Started introduction, because it wasn't immediately clear to me what it does and I questioned if it was really even necessary. This section is more helpful, although it could also maybe add just a little bit more detail: https://rtk-query-docs.netlify.app/api/createapi/#reducerpath

[Shrugsy]

Both the "bailing out of errors" section & "Need to cover how to use a custom base query" are intended to be covered by #1057

[Shrugsy]

Show switching from existing thunk-based fetching logic to RTKQ

Intended to be covered by #1060

[Shrugsy]

Could use an "RTK Overview" page in addition to the Tutorial and Usage Guide areas

This is intended to be covered by #1066
@markerikson let me know if you had something different in mind as an 'overview'

[markerikson]

I don't see any information on how the cached data lifetime + subscriptions behavior works. I wrote up a Reddit comment describing it:

https://www.reddit.com/r/reactjs/comments/nej4sv/redux_to_store_a_lot_of_data/gykyzms/

[Shrugsy]

Navigating to RTK Query Usage & API Reference pages is a little tedious due to the multiple levels of nesting.

For example, if looking for what the generated react hooks return (IMO likely to be one of the higher traffic sections), you need to:

• Click API Reference
• scroll all the way down to the bottom past the expanded sections
• Click RTK Query right at the bottom
• scroll all the way down to the bottom
• Click Generated API Slices
• scroll all the way down to the bottom
• click React Hooks

React Hooks link location in sidebar

@markerikson what are your thoughts on shifting them out somewhere higher to reduce nesting?
e.g. something like 'Using RTK Query' and 'API Reference - RTK Query' at the top level:

[Shrugsy]

I don't see any information on how the cached data lifetime + subscriptions behavior works. I wrote up a Reddit comment describing it:

@markerikson we have this currently: https://deploy-preview-1016--redux-starter-kit-docs.netlify.app/usage/rtk-query/cached-data#default-cache-handling-behaviour

But I think your explanation was very handy, so I've merged it together with the existing description under #1071

[markerikson]

Obligatory Twitter poll to get feedback on the docs organization:

https://twitter.com/acemarke/status/1395023250212655105

[akursat]

@markerikson Perhaps by ignoring the type definitions, the documentation can be made more readable.
You can group all type definitions under API reference and give a link from sections.
I think showing all type definitions in similar sections will increase consistency.
For example, the Mutations section contains the mutation endpoint type definition, while the Queries section does not.
The Queries section contains the hook type definition, while the Mutations section does not.

[markerikson]

Yeah, if we do have typedefs in the "Usage" pages, those need to be moved to the relevant API ref pages (and the "Usage" pages should probably link over to the API refs as appropriate).

[Shrugsy]

Regarding typedefs in the usage pages, please see the proposed updated version from #1074

the changes would still keep the 'Query hook return types' in the Queries usage page, and 'Mutation Hook Trigger Type' in the Mutations usage page, as they are the most relevant parts of the type signatures for each hook respectively.

Each of the two pages is proposed to also include a line linking to their respective API pages like:

See useQuery for the hook signature and additional details.
See useMutation for the hook signature and additional details.

Please let me know your thoughts if you think this is still too much type information for the 'Usage' pages

https://deploy-preview-1074--redux-starter-kit-docs.netlify.app/usage/rtk-query/queries#query-hook-return-types
https://deploy-preview-1074--redux-starter-kit-docs.netlify.app/usage/rtk-query/mutations#mutation-hook-trigger-type

[markerikson]

Hmm. Just out of curiosity, could we limit it to the 5-ish most frequently used fields just to keep it short here?

Also, would it be easier to read the descriptions if they were bullet points after the code block, instead of inline comments?

[markerikson]

FWIW, the Twitter poll is leaning towards having a single top-level "RTK Query" section. (Small sample size, etc, but FYI.)

[markerikson]

We need to actually describe how to use queryFn :) Added that to the checklist.

[markerikson]

Also some examples of transformResponse, including at least a mention of using createEntityAdapter with that.

[Shrugsy]

• Describe the queryFn option and usage
• Using transformResponse

Both of the above are intended to be covered by #1081

[Shrugsy]

write some kind of 'usage without hooks' content

Intended to be covered by #1119

[markerikson]

Final bits of cleanup work:

• Grammar/text editing pass
• 1.6 release notes
• Ought to list bundle size info in either "Overview" or "Comparison
• TS type visibility
• Update old RTKQ incubator repo to point to new docs
• Additional new exports
  • miniSerializeError
  • copyWithStructuralSharing
• Clarify isLoading vs isFetching ("lagged queries"?)

[markerikson]

Gonna say this is good to go :)