Skip to content

docs(example): batching#11008

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TkDodo merged 8 commits into from
Aug 20, 2026
Merged

docs(example): batching #11008

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
87b017c
docs(example): dataloader
TkDodo Jun 30, 2026
1bb965a
use tanstack pacer instead of dataloader
TkDodo Jun 30, 2026
63c5eb5
add staleTime
TkDodo Jun 30, 2026
4d408da
switch to useAsyncBatchedCallback
TkDodo Jun 30, 2026
abec47d
Revert "switch to useAsyncBatchedCallback"
TkDodo Jun 30, 2026
cef22bb
fix: use PromiseWithResolvers
TkDodo Jun 30, 2026
ac1bbe2
Merge remote-tracking branch 'origin/main' into feature/dataloader-ex…
TkDodo Aug 20, 2026
0957544
add batching example to docs
TkDodo Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/config.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -1637,6 +1637,10 @@
{
"label": "Chat example (streaming)",
"to": "framework/react/examples/chat"
},
{
"label": "Batching",
"to": "framework/react/examples/batching"
}
]
},
Expand Down
27 changes: 27 additions & 0 deletions examples/react/batching/.gitignore
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.

# dependencies
/node_modules
/.pnp
.pnp.js

# testing
/coverage

# production
/build

Comment on lines +11 to +13

@coderabbitaicoderabbitaiBotJun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Ignore Vite’s actual build output directory.

Lines 11-13 ignore /build, but examples/react/batching/vite.config.ts does not override Vite’s default outDir, so this example will emit dist/ instead. As written, generated artifacts can be committed accidentally.

Suggested fix
 # production
-/build+/dist
📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# production
/build
# production
/dist
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@examples/react/batching/.gitignore` around lines 11 - 13, The batching
example is ignoring the wrong Vite build output directory, so generated
artifacts can still be committed. Update the ignore entry in this example’s
.gitignore to match the actual default output from the Vite setup used by
batching, and verify it aligns with vite.config.ts and the example’s build
output path rather than /build.

pnpm-lock.yaml
yarn.lock
package-lock.json

# misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*
6 changes: 6 additions & 0 deletions examples/react/batching/README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
# Example

To run this example:

- `npm install`
- `npm run dev`
9 changes: 9 additions & 0 deletions examples/react/batching/eslint.config.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
import { tanstackConfig } from '@tanstack/eslint-config'
import pluginQuery from '@tanstack/eslint-plugin-query'
import pluginReact from '@eslint-react/eslint-plugin'

export default [
...tanstackConfig,
...pluginQuery.configs['flat/recommended'],
pluginReact.configs.recommended,
]
16 changes: 16 additions & 0 deletions examples/react/batching/index.html
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<link rel="shortcut icon" type="image/svg+xml" href="/emblem-light.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="theme-color" content="#000000" />

<title>TanStack Query React Basic Example App</title>

@coderabbitaicoderabbitaiBotJun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Update the document title to match the batching example.

Line 9 still says “Basic Example App”, which looks copied from another example and makes the browser tab misleading for this demo.

Suggested fix
- <title>TanStack Query React Basic Example App</title>+ <title>TanStack Query React Batching Example App</title>
📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
<title>TanStack Query React Basic Example App</title>
<title>TanStack Query React Batching Example App</title>
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@examples/react/batching/index.html` at line 9, The document title for the
batching demo is still using the generic Basic Example App text, which makes the
browser tab misleading. Update the title in the HTML document’s title element so
it matches the batching example naming used by this demo, keeping the change
localized to the example’s main HTML entry point.

</head>
<body>
<noscript>You need to enable JavaScript to run this app.</noscript>
<div id="root"></div>
<script type="module" src="/src/index.tsx"></script>
</body>
</html>
35 changes: 35 additions & 0 deletions examples/react/batching/package.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
{
"name": "@tanstack/query-example-react-batching",
"private": true,
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview",
"test:eslint": "eslint ./src"
},
"dependencies": {
"@tanstack/react-pacer": "^0.22.1",
"@tanstack/react-query": "^5.101.4",
"@tanstack/react-query-devtools": "^5.101.4",
"react": "^19.0.0",
"react-dom": "^19.0.0"
},
"devDependencies": {
"@tanstack/eslint-plugin-query": "^5.101.4",
"@types/react": "^18.2.79",
"@types/react-dom": "^18.2.25",
"@vitejs/plugin-react": "^4.3.4",
"typescript": "5.8.3",
"vite": "^6.4.1"
},
"nx": {
"targets": {
"test:eslint": {
"dependsOn": [
"^build"
]
}
}
}
}
13 changes: 13 additions & 0 deletions examples/react/batching/public/emblem-light.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
60 changes: 60 additions & 0 deletions examples/react/batching/src/character-loader.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
import { AsyncBatcher } from '@tanstack/react-pacer/async-batcher'

interface CharacterT {
id: number
name: string
status: string
species: string
type: string
gender: string
image: string
}

type CharacterRequest = {
deferred: PromiseWithResolvers<CharacterT | null>
id: number
}

// fetch function that returns characters by id
const fetchCharacters = async (ids: ReadonlyArray<number>) => {
console.log(`Fetching characters: ${ids.join(', ')}`)

const res = await fetch(
`https://rickandmortyapi.com/api/character/[${ids.join(',')}]`,
)
const characters = (await res.json()) as Array<CharacterT> | CharacterT

const characterMap = new Map<number, CharacterT>()
for (const character of Array.isArray(characters)
? characters
: [characters]) {
characterMap.set(character.id, character)
}

return characterMap
}

const characterBatcher = new AsyncBatcher<CharacterRequest>(
(requests) => fetchCharacters([...new Set(requests.map(({ id }) => id))]),
{
wait: 0,
onSuccess: (charactersById, requests) => {
for (const { deferred, id } of requests) {
deferred.resolve(charactersById.get(id) ?? null)
}
},
onError: (error, requests) => {
for (const { deferred } of requests) {
deferred.reject(error)
}
},
},
)

export const loadCharacter = (id: number) => {
const deferred = Promise.withResolvers<CharacterT | null>()

characterBatcher.addItem({ deferred, id })

return deferred.promise
}
132 changes: 132 additions & 0 deletions examples/react/batching/src/index.tsx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
import ReactDOM from 'react-dom/client'
import {
QueryClient,
QueryClientProvider,
queryOptions,
useQueries,
} from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { useState } from 'react'
import { loadCharacter } from './character-loader'

const queryClient = new QueryClient({
defaultOptions: {
queries: {
retry: 0,
},
},
})

const characterQueryOptions = (id: number) =>
queryOptions({
queryKey: ['character', id],
queryFn: () => loadCharacter(id),
staleTime: 60 * 1000,
})

function Characters({ ids }: { ids: Array<number> }) {
const characters = useQueries({
queries: ids.map((id) => characterQueryOptions(id)),
})

return characters.map((character, index) => {
if (character.status === 'pending') {
return 'Loading...'
}
if (character.status === 'error') {
return 'Error...'
}
if (character.data === null) {
return 'Not found ...'
}

return (
<div key={String(index)} style={{ display: 'flex' }}>
<img
width={100}
height={100}
alt={character.data.image}
src={character.data.image}
/>
<div style={{ paddingLeft: 10, textAlign: 'left' }}>
<h5 style={{ marginTop: 0, marginBottom: 5 }}>
{character.data.name} (#{character.data.id})
</h5>
<p style={{ marginTop: 0, marginBottom: 2 }}>
Status: {character.status}
Comment thread
coderabbitai[bot] marked this conversation as resolved.
</p>
<p style={{ marginTop: 0, marginBottom: 2 }}>
Species: {character.data.species}
</p>
<p style={{ marginTop: 0, marginBottom: 2 }}>
Gender: {character.data.gender}
</p>
</div>
</div>
)
})
}

function App() {
const [ids, setIds] = useState<Array<number>>([])
const [idsToLoad, setIdsToLoad] = useState<Array<number>>([])
const [error, setError] = useState('')

return (
<div className="App">
<h2>Character fetcher</h2>
<div>
<label style={{ display: 'block' }}>
Character ids (numberic, comma seprated)
</label>
<input
style={{ display: 'inline-block' }}
placeholder="ids"
onChange={(event) => {
const text = event.target.value.replace(' ', '')
const ids = text.split(',').map((id) => parseInt(id, 10))
const allValid = ids.reduce(
(valid, id) => valid && !isNaN(id),
true,
)

if (allValid) {
setIds(ids)
setError('')
} else {
setError('Invalid.. only use numbers and comma')
}
}}
/>
</div>

{error ? <h3 style={{ color: 'red' }}>{error}</h3> : null}

<button
type="button"
onClick={() => {
setIdsToLoad(ids)
Comment on lines +93 to +108

@coderabbitaicoderabbitaiBotJun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Clear or block stale IDs after validation fails.

When parsing fails, ids keeps the last valid value. Clicking Load characters after an invalid edit will therefore fetch stale IDs even though the UI is showing an error.

Suggested fix
 if (allValid) {
setIds(ids)
setError('')
} else {
+ setIds([])
setError('Invalid.. only use numbers and comma')
}
@@
<button
type="button"
+ disabled={!!error || ids.length === 0}
onClick={() => {
setIdsToLoad(ids)
}}
>
📝 Committable suggestion

‼️IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
if(allValid){
setIds(ids)
setError('')
}else{
setError('Invalid.. only use numbers and comma')
}
}}
/>
</div>
{error ? <h3style={{color: 'red'}}>{error}</h3> : null}
<button
type="button"
onClick={()=>{
setIdsToLoad(ids)
if(allValid){
setIds(ids)
setError('')
}else{
setIds([])
setError('Invalid.. only use numbers and comma')
}
}}
/>
</div>
{error ? <h3style={{color: 'red'}}>{error}</h3> : null}
<button
type="button"
disabled={!!error||ids.length===0}
onClick={()=>{
setIdsToLoad(ids)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@examples/react/batching/src/index.tsx` around lines 92 - 107, The validation
flow in the React batching example leaves stale `ids` in state when parsing
fails, so the `onClick` handler for the “Load characters” button can still use
the last valid value even while `error` is shown. Update the input validation
logic around the `setIds`, `setIdsToLoad`, and `setError` state updates so
invalid input either clears the pending IDs or prevents loading until the value
is valid, ensuring the button action cannot submit stale IDs after a failed
parse.

}}
>
Load characters
</button>
<div>
<h4 style={{ textAlign: 'left' }}>Characters:</h4>
<Characters ids={idsToLoad} />
</div>
</div>
)
}

function Root() {
return (
<QueryClientProvider client={queryClient}>
<App />
<ReactQueryDevtools initialIsOpen />
</QueryClientProvider>
)
}

const rootElement = document.getElementById('root')
if (!rootElement) throw new Error('Missing #root element')
ReactDOM.createRoot(rootElement).render(<Root />)
24 changes: 24 additions & 0 deletions examples/react/batching/tsconfig.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
{
"compilerOptions": {
"target": "ESNext",
"useDefineForClassFields": true,
"lib": ["ES2020", "DOM", "DOM.Iterable", "ESNext"],
"module": "ESNext",
"skipLibCheck": true,

/* Bundler mode */
"moduleResolution": "Bundler",
"allowImportingTsExtensions": true,
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"jsx": "react-jsx",

/* Linting */
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true
},
"include": ["src", "eslint.config.js"]
}
6 changes: 6 additions & 0 deletions examples/react/batching/vite.config.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
import{defineConfig}from'vite'
importreactfrom'@vitejs/plugin-react'

exportdefaultdefineConfig({
plugins: [react()],
})
Loading
Loading