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

quick-start.md

231 lines5.9 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 createQuery,
15} from '@tanstack/solid-query'
16import { Switch, Match, For } from 'solid-js'
17​
18const queryClient = new QueryClient()
19​
20function Example() {
21 const query = createQuery(() => ({
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## Available Functions
53​
54Solid Query offers useful primitives and functions that will make managing server state in SolidJS apps easier.
55​
56- `createQuery`
57- `createQueries`
58- `createInfiniteQueries`
59- `createMutation`
60- `useIsFetching`
61- `useIsMutating`
62- `useQueryClient`
63- `QueryClient`
64- `QueryClientProvider`
65​
66## Important Differences between Solid Query & React Query
67​
68Solid Query offers an API similar to React Query, but there are some key differences to be mindful of.
69​
70- Arguments to `solid-query` primitives (like `createQuery`, `createMutation`, `useIsFetching`) listed above are functions, so that they can be tracked in a reactive scope.
71​
72```tsx
73// ❌ react version
74useQuery({
75 queryKey: ['todos', todo],
76 queryFn: fetchTodos,
77})
78​
79// βœ… solid version
80createQuery(() => ({
81 queryKey: ['todos', todo],
82 queryFn: fetchTodos,
83}))
84```
85​
86- Suspense works for queries out of the box if you access the query data inside a `<Suspense>` boundary.
87​
88```tsx
89import { For, Suspense } from 'solid-js'
90​
91function Example() {
92 const query = createQuery(() => ({
93 queryKey: ['todos'],
94 queryFn: fetchTodos,
95 }))
96 return (
97 <div>
98 {/* βœ… Will trigger loading fallback, data accessed in a suspense boundary. */}
99 <Suspense fallback={'Loading...'}>
100 <For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
101 </Suspense>
102 {/* ❌ Will not trigger loading fallback, data not accessed in a suspense boundary. */}
103 <For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
104 </div>
105 )
107```
108​
109- 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.
110​
111```tsx
112import {
113 QueryClient,
114 QueryClientProvider,
115 createQuery,
116} from '@tanstack/solid-query'
117import { Match, Switch } from 'solid-js'
118​
119const queryClient = new QueryClient()
120​
121export default function App() {
122 return (
123 <QueryClientProvider client={queryClient}>
124 <Example />
125 </QueryClientProvider>
126 )
128​
129function Example() {
130 // ❌ react version -- supports destructing outside reactive context
131 // const { isPending, error, data } = useQuery({
132 // queryKey: ['repoData'],
133 // queryFn: () =>
134 // fetch('https://api.github.com/repos/tannerlinsley/react-query').then(
135 // (res) => res.json()
136 // ),
137 // })
138​
139 // βœ… solid version -- does not support destructuring outside reactive context
140 const query = createQuery(() => ({
141 queryKey: ['repoData'],
142 queryFn: () =>
143 fetch('https://api.github.com/repos/tannerlinsley/react-query').then(
144 (res) => res.json(),
145 ),
146 }))
147​
148 // βœ… access query properties in JSX reactive context
149 return (
150 <Switch>
151 <Match when={query.isPending}>Loading...</Match>
152 <Match when={query.isError}>Error: {query.error.message}</Match>
153 <Match when={query.isSuccess}>
154 <div>
155 <h1>{query.data.name}</h1>
156 <p>{query.data.description}</p>
157 <strong>πŸ‘€ {query.data.subscribers_count}</strong>{' '}
158 <strong>✨ {query.data.stargazers_count}</strong>{' '}
159 <strong>🍴 {query.data.forks_count}</strong>
160 </div>
161 </Match>
162 </Switch>
163 )
165```
166​
167- Signals and store values can be passed in directly to function arguments. Solid Query will update the query `store` automatically.
168​
169```tsx
170import {
171 QueryClient,
172 QueryClientProvider,
173 createQuery,
174} from '@tanstack/solid-query'
175import { createSignal, For } from 'solid-js'
176​
177const queryClient = new QueryClient()
178​
179function Example() {
180 const [enabled, setEnabled] = createSignal(false)
181 const [todo, setTodo] = createSignal(0)
182​
183 // βœ… passing a signal directly is safe and observers update
184 // automatically when the value of a signal changes
185 const todosQuery = createQuery(() => ({
186 queryKey: ['todos'],
187 queryFn: fetchTodos,
188 enabled: enabled(),
189 }))
190​
191 const todoDetailsQuery = createQuery(() => ({
192 queryKey: ['todo', todo()],
193 queryFn: fetchTodo,
194 enabled: todo() > 0,
195 }))
196​
197 return (
198 <div>
199 <Switch>
200 <Match when={todosQuery.isPending}>
201 <p>Loading...</p>
202 </Match>
203 <Match when={todosQuery.isError}>
204 <p>Error: {todosQuery.error.message}</p>
205 </Match>
206 <Match when={todosQuery.isSuccess}>
207 <For each={todosQuery.data}>
208 {(todo) => (
209 <button onClick={() => setTodo(todo.id)}>{todo.title}</button>
210 )}
211 </For>
212 </Match>
213 </Switch>
214 <button onClick={() => setEnabled(!enabled())}>Toggle enabled</button>
215 </div>
216 )
218​
219function App() {
220 return (
221 <QueryClientProvider client={queryClient}>
222 <Example />
223 </QueryClientProvider>
224 )
226```
227​
228- Errors can be caught and reset using SolidJS' native `ErrorBoundary` component.
229 Set `throwOnError` or the `suspense` option to `true` to make sure errors are thrown to the `ErrorBoundary`
230​
231- Since Property tracking is handled through Solid's fine grained reactivity, options like `notifyOnChangeProps` are not needed