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

quick-start.md

217 lines5.5 KB

1---
2id: quick-start
3title: Quick Start
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 {
12 QueryClient,
13 QueryClientProvider,
14 useQuery,
15} from '@tanstack/solid-query'
16import { Switch, Match, For } from 'solid-js'
17​
18const queryClient = new QueryClient()
19​
20function Example() {
21 const query = useQuery(() => ({
22 queryKey: ['todos'],
23 queryFn: fetchTodos,
24 }))
25​
26 return (
27 <div>
28 <Switch>
29 <Match when={query.isPending}>
30 <p>Loading...</p>
31 </Match>
32 <Match when={query.isError}>
33 <p>Error: {query.error.message}</p>
34 </Match>
35 <Match when={query.isSuccess}>
36 <For each={query.data}>{(todo) => <p>{todo.title}</p>}</For>
37 </Match>
38 </Switch>
39 </div>
40 )
42​
43function App() {
44 return (
45 <QueryClientProvider client={queryClient}>
46 <Example />
47 </QueryClientProvider>
48 )
50```
51​
52## Important Differences between Solid Query & React Query
53​
54Solid Query offers an API similar to React Query, but there are some key differences to be mindful of.
55​
56- Arguments to `solid-query` primitives (like `useQuery`, `useMutation`, `useIsFetching`) are functions, so that they can be tracked in a reactive scope.
57​
58```tsx
59// ❌ react version
60useQuery({
61 queryKey: ['todos', todo],
62 queryFn: fetchTodos,
63})
64​
65// βœ… solid version
66useQuery(() => ({
67 queryKey: ['todos', todo],
68 queryFn: fetchTodos,
69}))
70```
71​
72- Suspense works for queries out of the box if you access the query data inside a `<Suspense>` boundary.
73​
74```tsx
75import { For, Suspense } from 'solid-js'
76​
77function Example() {
78 const query = useQuery(() => ({
79 queryKey: ['todos'],
80 queryFn: fetchTodos,
81 }))
82 return (
83 <div>
84 {/* βœ… Will trigger loading fallback, data accessed in a suspense boundary. */}
85 <Suspense fallback={'Loading...'}>
86 <For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
87 </Suspense>
88 {/* ❌ Will not trigger loading fallback, data not accessed in a suspense boundary. */}
89 <For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
90 </div>
91 )
93```
94​
95- Solid Query primitives do not support destructuring. The return value from these functions is a store, and their properties are only tracked in a reactive context.
96​
97```tsx
98import {
99 QueryClient,
100 QueryClientProvider,
101 useQuery,
102} 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 { isPending, error, data } = useQuery({
118 // queryKey: ['repoData'],
119 // queryFn: () =>
120 // fetch('https://api.github.com/repos/TanStack/query').then(
121 // (res) => res.json()
122 // ),
123 // })
124​
125 // βœ… solid version -- does not support destructuring outside reactive context
126 const query = useQuery(() => ({
127 queryKey: ['repoData'],
128 queryFn: () =>
129 fetch('https://api.github.com/repos/TanStack/query').then((res) =>
130 res.json(),
131 ),
132 }))
133​
134 // βœ… access query properties in JSX reactive context
135 return (
136 <Switch>
137 <Match when={query.isPending}>Loading...</Match>
138 <Match when={query.isError}>Error: {query.error.message}</Match>
139 <Match when={query.isSuccess}>
140 <div>
141 <h1>{query.data.name}</h1>
142 <p>{query.data.description}</p>
143 <strong>πŸ‘€ {query.data.subscribers_count}</strong>{' '}
144 <strong>✨ {query.data.stargazers_count}</strong>{' '}
145 <strong>🍴 {query.data.forks_count}</strong>
146 </div>
147 </Match>
148 </Switch>
149 )
151```
152​
153- Signals and store values can be passed in directly to function arguments. Solid Query will update the query `store` automatically.
154​
155```tsx
156import {
157 QueryClient,
158 QueryClientProvider,
159 useQuery,
160} from '@tanstack/solid-query'
161import { createSignal, For } from 'solid-js'
162​
163const queryClient = new QueryClient()
164​
165function Example() {
166 const [enabled, setEnabled] = createSignal(false)
167 const [todo, setTodo] = createSignal(0)
168​
169 // βœ… passing a signal directly is safe and observers update
170 // automatically when the value of a signal changes
171 const todosQuery = useQuery(() => ({
172 queryKey: ['todos'],
173 queryFn: fetchTodos,
174 enabled: enabled(),
175 }))
176​
177 const todoDetailsQuery = useQuery(() => ({
178 queryKey: ['todo', todo()],
179 queryFn: fetchTodo,
180 enabled: todo() > 0,
181 }))
182​
183 return (
184 <div>
185 <Switch>
186 <Match when={todosQuery.isPending}>
187 <p>Loading...</p>
188 </Match>
189 <Match when={todosQuery.isError}>
190 <p>Error: {todosQuery.error.message}</p>
191 </Match>
192 <Match when={todosQuery.isSuccess}>
193 <For each={todosQuery.data}>
194 {(todo) => (
195 <button onClick={() => setTodo(todo.id)}>{todo.title}</button>
196 )}
197 </For>
198 </Match>
199 </Switch>
200 <button onClick={() => setEnabled(!enabled())}>Toggle enabled</button>
201 </div>
202 )
204​
205function App() {
206 return (
207 <QueryClientProvider client={queryClient}>
208 <Example />
209 </QueryClientProvider>
210 )
212```
213​
214- Errors can be caught and reset using SolidJS' native `ErrorBoundary` component.
215 Set `throwOnError` to `true` to make sure errors are thrown to the `ErrorBoundary`
216​
217- Since Property tracking is handled through Solid's fine grained reactivity, options like `notifyOnChangeProps` are not needed