Skip to content

Commit acbad31

Browse files
committed
docs(react-query): clarify usage of defaultError in global Error type registration
Signed-off-by: leesb971204 <[email protected]>
1 parent 8b85d83 commit acbad31

File tree

1 file changed

+2
-38
lines changed

1 file changed

+2
-38
lines changed

docs/framework/react/typescript.md

Lines changed: 2 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -130,14 +130,14 @@ if (axios.isAxiosError(error)) {
130130

131131
### Registering a global Error
132132

133-
TanStack Query v5 allows for a way to set a global Error type for everything, without having to specify generics on call-sides, by amending the `Register` interface. This will make sure inference still works, but the error field will be of the specified type. We recommend `unknown` to ensure safe, explicit narrowing at call sites, by amending the `Register` interface:
133+
TanStack Query v5 allows for a way to set a global Error type for everything, without having to specify generics on call-sides, by amending the `Register` interface. This will make sure inference still works, but the error field will be of the specified type. If you want to enforce that call-sides must do explicit type-narrowing, set `defaultError` to `unknown`:
134134

135135
[//]: # 'RegisterErrorType'
136136

137137
```tsx
138138
import '@tanstack/react-query'
139139

140-
// ✅ Recommended
140+
141141
declare module '@tanstack/react-query' {
142142
interface Register {
143143
// Use unknown so call sites must narrow explicitly.
@@ -151,42 +151,6 @@ const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
151151

152152
[//]: # 'RegisterErrorType'
153153

154-
#### Why `unknown` instead of `AxiosError`?
155-
156-
Queries can throw from multiple places—not only your `queryFn`, but also `select`, memoized callbacks, or other user-land code. If you set a global error type like `AxiosError`, consumers may assume all errors are Axios-driven when many are not. Using `unknown` forces safe, explicit narrowing at usage sites and works for any mixed error source.
157-
158-
```tsx
159-
const { error } = useQuery(options)
160-
161-
if (isAxiosError(error)) {
162-
// handle Axios-specific details
163-
} else if (error instanceof Error) {
164-
// handle generic errors
165-
} else {
166-
// handle non-Error throwables if needed
167-
}
168-
```
169-
170-
If you want a stable shape across your app, normalize errors where they're thrown and rethrow a domain error:
171-
172-
```tsx
173-
class DomainError extends Error {
174-
constructor(public kind: 'Network' | 'Auth' | 'Unknown', message?: string) {
175-
super(message)
176-
}
177-
}
178-
179-
const queryFn = async () => {
180-
try {
181-
const res = await api.get('/user')
182-
return res.data
183-
} catch (e) {
184-
throw normalizeToDomainError(e) // convert AxiosError or others → DomainError
185-
}
186-
}
187-
```
188-
189-
This pattern keeps UI code simple while avoiding incorrect global assumptions about the error source.
190154
[//]: # 'TypingMeta'
191155

192156
## Typing meta

0 commit comments

Comments
 (0)