Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

overview.md

206 lines5.5 KB

1---
2id: overview
3title: Solid Query
4---
5​
6The `@tanstack/solid-query` package provides a 1st-class API for using TanStack Query with SolidJS.
7​
8## Example
9​
10```tsx
11import { QueryClient, QueryClientProvider, createQuery } from '@tanstack/solid-query'
12import { Switch, Match, For } from 'solid-js'
13​
14const queryClient = new QueryClient()
15​
16function Example() {
17 const query = createQuery(() => ['todos'], fetchTodos)
18​
19 return (
20 <div>
21 <Switch>
22 <Match when={query.isLoading}>
23 <p>Loading...</p>
24 </Match>
25 <Match when={query.isError}>
26 <p>Error: {query.error.message}</p>
27 </Match>
28 <Match when={query.isSuccess}>
29 <For each={query.data}>
30 {(todo) => <p>{todo.title}</p>}
31 </For>
32 </Match>
33 </Switch>
34 </div>
35 )
37​
38function App() {
39 return (
40 <QueryClientProvider client={queryClient}>
41 <Example />
42 </QueryClientProvider>
43 )
45​
46```
47​
48## Available Functions
49​
50Solid Query offers useful primitives and functions that will make managing server state in SolidJS apps easier.
51​
52- `createQuery`
53- `createQueries`
54- `createInfiniteQueries`
55- `createMutation`
56- `useIsFetching`
57- `useIsMutating`
58- `useQueryClient`
59- `QueryClient`
60- `QueryClientProvider`
61​
62​
63​
64​
65## Important Differences between Solid Query & React Query
66​
67Solid Query offers an API similar to React Query, but there are some key differences to be mindful of.
68​
69- To maintain their reactivity, Query keys need to be wrapped inside a function while using `createQuery`, `createQueries`, `createInfiniteQuery` and `useIsFetching`.
70​
71```tsx
72// ❌ react version
73useQuery(["todos", todo], fetchTodos)
74​
75// βœ… solid version
76createQuery(() => ["todos", todo()], fetchTodos)
77```
78​
79- Suspense works for queries out of the box if you access the query data inside a `<Suspense>` boundary.
80​
81```tsx
82import { For, Suspense } from 'solid-js'
83​
84function Example() {
85 const query = createQuery(() => ['todos'], fetchTodos)
86 return (
87 <div>
88 {/* βœ… Will trigger loading fallback, data accessed in a suspense context. */}
89 <Suspense fallback={"Loading..."}>
90 <For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
91 </Suspense>
92 {/* ❌ Will not trigger loading fallback, data not accessed in a suspense context. */}
93 <For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
94 </div>
95 )
97```
98​
99- Solid Query primitives (`createX`) do not support destructuring. The return value from these functions is a store, and their properties are only tracked in a reactive context.
100​
101```tsx
102import { QueryClient, QueryClientProvider, createQuery } from '@tanstack/solid-query'
103import { Match, Switch } from 'solid-js'
104​
105const queryClient = new QueryClient()
106​
107export default function App() {
108 return (
109 <QueryClientProvider client={queryClient}>
110 <Example />
111 </QueryClientProvider>
112 )
114​
115function Example() {
116 // ❌ react version -- supports destructing outside reactive context
117 // const { isLoading, error, data } = useQuery(['repoData'], () =>
118 // fetch('https://api.github.com/repos/tannerlinsley/react-query').then(res =>
119 // res.json()
120 // )
121 // )
122​
123 // βœ… solid version -- does not support destructuring outside reactive context
124 const query = createQuery(
125 () => ['repoData'],
126 () =>
127 fetch('https://api.github.com/repos/tannerlinsley/react-query').then(
128 (res) => res.json(),
129 ),
130 )
131​
132 // βœ… access query properties in JSX reactive context
133 return (
134 <Switch>
135 <Match when={query.isLoading}>Loading...</Match>
136 <Match when={query.isError}>Error: {query.error.message}</Match>
137 <Match when={query.isSuccess}>
138 <div>
139 <h1>{query.data.name}</h1>
140 <p>{query.data.description}</p>
141 <strong>πŸ‘€ {query.data.subscribers_count}</strong>{' '}
142 <strong>✨ {query.data.stargazers_count}</strong>{' '}
143 <strong>🍴 {query.data.forks_count}</strong>
144 </div>
145 </Match>
146 </Switch>
147 )
149```
150​
151- If you want options to be reactive you need to pass them using object getter syntax. This may look strange at first but it leads to more idiomatic solid code.
152​
153```tsx
154import {
155 QueryClient,
156 QueryClientProvider,
157 createQuery,
158} from '@tanstack/solid-query'
159import { createSignal, For } from 'solid-js'
160​
161const queryClient = new QueryClient()
162​
163function Example() {
164 const [enabled, setEnabled] = createSignal(false)
165 const query = createQuery(() => ['todos'], fetchTodos, {
166 // ❌ passing a signal directly is not reactive
167 // enabled: enabled(),
168​
169 // βœ… passing a function that returns a signal is reactive
170 get enabled() {
171 return enabled()
172 },
173 })
174​
175 return (
176 <div>
177 <Switch>
178 <Match when={query.isLoading}>
179 <p>Loading...</p>
180 </Match>
181 <Match when={query.isError}>
182 <p>Error: {query.error.message}</p>
183 </Match>
184 <Match when={query.isSuccess}>
185 <For each={query.data}>
186 {(todo) => <p>{todo.title}</p>}
187 </For>
188 </Match>
189 </Switch>
190 <button onClick={() => setEnabled(!enabled())}>Toggle enabled</button>
191 </div>
192 )
194​
195function App() {
196 return (
197 <QueryClientProvider client={queryClient}>
198 <Example />
199 </QueryClientProvider>
200 )
202```
203​
204- Errors can be caught and reset using SolidJS' native `ErrorBoundary` component. `QueryErrorResetBoundary` is not needed with Solid Query
205​
206- Since Property tracking is handled through Solid's fine grained reactivity, options like `notifyOnChangeProps` are not needed