Skip to content

Commit

Permalink
docs: align routing with framework switcher (TanStack#4608)
Browse files Browse the repository at this point in the history
* docs: align routing with framework switcher

Co-authored-by: Aryan Deora <[email protected]>

* docs: remove angular from docs config

* docs: add doc ref redirect example

Co-authored-by: Aryan Deora <[email protected]>
  • Loading branch information
DamianOsipiuk and ardeora authored Dec 16, 2022
1 parent 2e331bf commit 198017b
Show file tree
Hide file tree
Showing 81 changed files with 699 additions and 396 deletions.
822 changes: 426 additions & 396 deletions docs/config.json

Large diffs are not rendered by default.

File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
206 changes: 206 additions & 0 deletions docs/solid/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,206 @@
---
id: overview
title: Solid Query
---

The `@tanstack/solid-query` package provides a 1st-class API for using TanStack Query with SolidJS.

## Example

```tsx
import { QueryClient, QueryClientProvider, createQuery } from '@tanstack/solid-query'
import { Switch, Match, For } from 'solid-js'

const queryClient = new QueryClient()

function Example() {
const query = createQuery(() => ['todos'], fetchTodos)

return (
<div>
<Switch>
<Match when={query.isLoading}>
<p>Loading...</p>
</Match>
<Match when={query.isError}>
<p>Error: {query.error.message}</p>
</Match>
<Match when={query.isSuccess}>
<For each={query.data}>
{(todo) => <p>{todo.title}</p>}
</For>
</Match>
</Switch>
</div>
)
}

function App() {
return (
<QueryClientProvider client={queryClient}>
<Example />
</QueryClientProvider>
)
}

```

## Available Functions

Solid Query offers useful primitives and functions that will make managing server state in SolidJS apps easier.

- `createQuery`
- `createQueries`
- `createInfiniteQueries`
- `createMutation`
- `useIsFetching`
- `useIsMutating`
- `useQueryClient`
- `QueryClient`
- `QueryClientProvider`




## Important Differences between Solid Query & React Query

Solid Query offers an API similar to React Query, but there are some key differences to be mindful of.

- To maintain their reactivity, Query keys need to be wrapped inside a function while using `createQuery`, `createQueries`, `createInfiniteQuery` and `useIsFetching`.

```tsx
// ❌ react version
useQuery(["todos", todo], fetchTodos)

// ✅ solid version
createQuery(() => ["todos", todo()], fetchTodos)
```

- Suspense works for queries out of the box if you access the query data inside a `<Suspense>` boundary.

```tsx
import { For, Suspense } from 'solid-js'

function Example() {
const query = createQuery(() => ['todos'], fetchTodos)
return (
<div>
{/* ✅ Will trigger loading fallback, data accessed in a suspense context. */}
<Suspense fallback={"Loading..."}>
<For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
</Suspense>
{/* ❌ Will not trigger loading fallback, data not accessed in a suspense context. */}
<For each={query.data}>{(todo) => <div>{todo.title}</div>}</For>
</div>
)
}
```

- 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.

```tsx
import { QueryClient, QueryClientProvider, createQuery } from '@tanstack/solid-query'
import { Match, Switch } from 'solid-js'

const queryClient = new QueryClient()

export default function App() {
return (
<QueryClientProvider client={queryClient}>
<Example />
</QueryClientProvider>
)
}

function Example() {
// ❌ react version -- supports destructing outside reactive context
// const { isLoading, error, data } = useQuery(['repoData'], () =>
// fetch('https://api.github.com/repos/tannerlinsley/react-query').then(res =>
// res.json()
// )
// )

// ✅ solid version -- does not support destructuring outside reactive context
const query = createQuery(
() => ['repoData'],
() =>
fetch('https://api.github.com/repos/tannerlinsley/react-query').then(
(res) => res.json(),
),
)

// ✅ access query properties in JSX reactive context
return (
<Switch>
<Match when={query.isLoading}>Loading...</Match>
<Match when={query.isError}>Error: {query.error.message}</Match>
<Match when={query.isSuccess}>
<div>
<h1>{query.data.name}</h1>
<p>{query.data.description}</p>
<strong>👀 {query.data.subscribers_count}</strong>{' '}
<strong>✨ {query.data.stargazers_count}</strong>{' '}
<strong>🍴 {query.data.forks_count}</strong>
</div>
</Match>
</Switch>
)
}
```

- 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.

```tsx
import {
QueryClient,
QueryClientProvider,
createQuery,
} from '@tanstack/solid-query'
import { createSignal, For } from 'solid-js'

const queryClient = new QueryClient()

function Example() {
const [enabled, setEnabled] = createSignal(false)
const query = createQuery(() => ['todos'], fetchTodos, {
// ❌ passing a signal directly is not reactive
// enabled: enabled(),

// ✅ passing a function that returns a signal is reactive
get enabled() {
return enabled()
},
})

return (
<div>
<Switch>
<Match when={query.isLoading}>
<p>Loading...</p>
</Match>
<Match when={query.isError}>
<p>Error: {query.error.message}</p>
</Match>
<Match when={query.isSuccess}>
<For each={query.data}>
{(todo) => <p>{todo.title}</p>}
</For>
</Match>
</Switch>
<button onClick={() => setEnabled(!enabled())}>Toggle enabled</button>
</div>
)
}

function App() {
return (
<QueryClientProvider client={queryClient}>
<Example />
</QueryClientProvider>
)
}
```

- Errors can be caught and reset using SolidJS' native `ErrorBoundary` component. `QueryErrorResetBoundary` is not needed with Solid Query

- Since Property tracking is handled through Solid's fine grained reactivity, options like `notifyOnChangeProps` are not needed
8 changes: 8 additions & 0 deletions docs/svelte/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
id: overview
title: Svelte Query (Coming Soon)
---

> ⚠️ This module has not yet been developed. It requires an adapter similar to `react-query` to work. We estimate the amount of code to do this is low-to-moderate, but does require familiarity with the Svelte framework. If you would like to contribute this adapter, please open a PR!
The `@tanstack/svelte-query` package offers a 1st-class API for using TanStack Query via Svelte. However, all of the primitives you receive from this API are core APIs that are shared across all of the TanStack Adapters including the Query Client, query results, query subscriptions, etc.
5 changes: 5 additions & 0 deletions docs/vue/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
id: overview
title: Overview
ref: docs/react/overview.md
---
54 changes: 54 additions & 0 deletions docs/vue/quick-start.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
---
id: overview
title: Vue Query
---

The `vue-query` package offers a 1st-class API for using TanStack Query via Vue. However, all of the primitives you receive from these hooks are core APIs that are shared across all of the TanStack Adapters including the Query Client, query results, query subscriptions, etc.

## Example

This example very briefly illustrates the 3 core concepts of Vue Query:

- [Queries](guides/queries)
- [Mutations](guides/mutations)
- [Query Invalidation](guides/query-invalidation)

```vue
<script setup>
import { useQueryClient, useQuery, useMutation } from "@tanstack/vue-query";
// Access QueryClient instance
const queryClient = useQueryClient();
// Query
const { isLoading, isError, data, error } = useQuery({ queryKey: ['todos'], queryFn: getTodos });
// Mutation
const mutation = useMutation({
mutationFn: postTodo,
onSuccess: () => {
// Invalidate and refetch
queryClient.invalidateQueries({ queryKey: ["todos"] });
},
});
function onButtonClick() {
mutation.mutate({
id: Date.now(),
title: "Do Laundry",
});
}
</script>
<template>
<span v-if="isLoading">Loading...</span>
<span v-else-if="isError">Error: {{ error.message }}</span>
<!-- We can assume by this point that `isSuccess === true` -->
<ul v-else>
<li v-for="todo in data" :key="todo.id">{{ todo.title }}</li>
</ul>
<button @click="onButtonClick">Add Todo</button>
</template>
```

These three concepts make up most of the core functionality of Vue Query. The next sections of the documentation will go over each of these core concepts in great detail.

0 comments on commit 198017b

Please sign in to comment.