{postMutation.isPending ? : null} {comment.content}

commentMutation.mutateAsync({ content: e.target.value })} />
                </div>
              )}
            </Mutation>
          ))}
        </>
      )}
    </Mutation>
  ));
}
```

### Motivation: useMutation Creates Unnecessary Depth

The existing useMutation is a hook, which leads to the creation of components like PostToUseMutation and CommentToUseMutation. This creates unnecessary depth and results in awkward component names, making the structure less flexible and harder to manage due to coupling with parent components.

```jsx /useMutation/
import { useMutation } from '@tanstack/react-query'

const PostsPage = () => {
  const posts = usePosts();

return posts.map(post => <PostToUseMutation key={post.id} post={post} />);
};

// PostToUseMutation (unnecessary name, needs to be refactored to use only useMutation)
const PostToUseMutation = ({ post }: { post: Post }) => { // Props need to be passed to useMutation.
  const postMutation = useMutation({
    mutationFn: ({ content }: { content: string }) => api.editPost({ postId: post.id, content }),
  });

if (postMutation.isPending) {
    return <Spinner />;
  }

return (
    <>
      <div>{post.content}</div>
      <textarea onChange={e => postMutation.mutateAsync({ content: e.target.value })} />
      {post.comments.map(comment => (
        <CommentToUseMutation key={comment.id} post={post} comment={comment} />
      ))}
    </>
  );
};

// CommentToUseMutation (unnecessary name, needs to be refactored to use only useMutation)
const CommentToUseMutation = ({ post, comment }: { post: Post, comment: Comment }) => { // Props need to be passed to useMutation.
  const commentMutation = useMutation({
    mutationFn: ({ content }: { content: string }) => api.editComment({ postId: post.id, commentId: comment.id, content }),
  });

return (
    <div>
      {comment.content}
      <textarea onChange={e => commentMutation.mutateAsync({ content: e.target.value })} />
    </div>
  );
};
```

---

## PrefetchQuery

URL: /docs/react-query/PrefetchQuery

# PrefetchQuery

A component that allows you to use usePrefetchQuery in JSX, avoiding the limitations of React hooks.

```jsx /PrefetchQuery/
import { PrefetchQuery, useSuspenseQuery } from '@suspensive/react-query'

const PostsPage = () => {
  const { data: posts } = useSuspenseQuery({
    queryKey: ['posts'],
    queryFn: () => getPosts(),
  })

return posts.map((post) => (
    <div key={post.id}>
      {/* 🚫 We can not invoke usePrefetchQuery like below because of React Hook rules
      // usePrefetchQuery({
      //   queryKey: ['posts', post.id, 'comments'],
      //   queryFn: () => getPostComments(post.id),
      // })

// ✅ We can invoke usePrefetchQuery for each post comments query before entering Post Comments page */}
      <PrefetchQuery
        queryKey={['posts', post.id, 'comments']}
        queryFn={() => getPostComments(post.id)}
      />
      <h2>{post.title}</h2>
      <p>{post.description}</p>
      <Link to={`/posts/${post.id}/comments`}>See comments</Link>
    </div>
  ))
}
```

---

## PrefetchInfiniteQuery

URL: /docs/react-query/PrefetchInfiniteQuery

# PrefetchInfiniteQuery

A component that allows you to use usePrefetchInfiniteQuery in JSX, avoiding the limitations of React hooks.

```jsx /PrefetchInfiniteQuery/
import {
  PrefetchInfiniteQuery,
  useSuspenseQuery,
} from '@suspensive/react-query'

const PostsPage = () => {
  const { data: posts } = useSuspenseQuery({
    queryKey: ['posts'],
    queryFn: () => getPosts(),
  })

return posts.map((post) => (
    <div key={post.id}>
      {/* 🚫 We can not invoke usePrefetchInfiniteQuery like below because of React Hook rules
      // usePrefetchInfiniteQuery({
      //   queryKey: ['posts', post.id, 'comments'],
      //   queryFn: () => getPostComments(post.id),
      // })

// ✅ We can invoke usePrefetchInfiniteQuery for each post comments query before entering Post Comments page */}
      <PrefetchInfiniteQuery
        queryKey={['posts', post.id, 'comments']}
        queryFn={() => getPostComments(post.id)}
      />
      <h2>{post.title}</h2>
      <p>{post.description}</p>
      <Link to={`/posts/${post.id}/comments`}>See comments</Link>
    </div>
  ))
}
```

---

## QueriesHydration

URL: /docs/react-query/QueriesHydration

# QueriesHydration

> **Experimental:** `<QueriesHydration/>` is an experimental feature, so this interface may change.

A component that prefetches multiple queries on the server and automatically hydrates them to client components.

This is useful when you want to prefetch data on the server side and pass it to the client in React Server Components environments.

> 💡 **Recommended reading**: Before using this component, we recommend reading the [TanStack Query Advanced Server Rendering guide](https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr), which covers Server Components, streaming, and the Next.js App Router. Understanding these concepts will help you use `QueriesHydration` more effectively.

## Basic Usage

Use `queryOptions` with `QueriesHydration` to prefetch data on the server. For better HTML Streaming, wrap each component with its own `Suspense` and `QueriesHydration`:

#### page.tsx (RSC)

```tsx /QueriesHydration/
import { QueriesHydration } from '@suspensive/react-query'
import { Suspense } from '@suspensive/react'
import { userQueryOptions, postsQueryOptions } from './queries'
import { UserProfile, PostList } from './_components'

// Server Component
const PostsPage = ({ userId }: { userId: number }) => {
  return (
    <>
      <Suspense fallback={<div>Loading user...</div>}>
        <QueriesHydration queries={[userQueryOptions(userId)]}>
          <UserProfile userId={userId} />
        </QueriesHydration>
      </Suspense>
      <Suspense fallback={<div>Loading posts...</div>}>
        <QueriesHydration queries={[postsQueryOptions(userId)]}>
          <PostList userId={userId} />
        </QueriesHydration>
      </Suspense>
    </>
  )
}
```

#### UserProfile.tsx (RCC)

```tsx
'use client'

import { useSuspenseQuery } from '@suspensive/react-query'
import { userQueryOptions } from './queries'

export const UserProfile = ({ userId }: { userId: number }) => {
  // Data prefetched on the server is automatically hydrated
  const { data: user } = useSuspenseQuery(userQueryOptions(userId))

return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  )
}
```

#### PostList.tsx (RCC)

```tsx
'use client'

import { useSuspenseQuery } from '@suspensive/react-query'
import { postsQueryOptions } from './queries'

export const PostList = ({ userId }: { userId: number }) => {
  // Data prefetched on the server is automatically hydrated
  const { data: posts } = useSuspenseQuery(postsQueryOptions(userId))

return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}
```

### Using Infinite Queries

You can also use `infiniteQueryOptions` with `QueriesHydration`. You can mix regular queries and infinite queries in the same array. For better HTML Streaming, wrap each component with its own `Suspense` and `QueriesHydration`:

```tsx /QueriesHydration/
import { QueriesHydration } from '@suspensive/react-query'
import { Suspense } from '@suspensive/react'
import { queryOptions, infiniteQueryOptions } from '@tanstack/react-query'
import { UserProfile, InfinitePostList } from './_components'

const userQueryOptions = (userId: string) =>
  queryOptions({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  })

const postsInfiniteQueryOptions = (userId: string) =>
  infiniteQueryOptions({
    queryKey: ['posts', userId],
    queryFn: ({ pageParam = 0 }) => fetchPosts(userId, pageParam),
    getNextPageParam: (lastPage, allPages) => lastPage.nextCursor,
    initialPageParam: 0,
  })

// Server Component
const PostsPage = ({ userId }: { userId: string }) => {
  return (
    <>
      <Suspense fallback={<div>Loading user...</div>}>
        <QueriesHydration queries={[userQueryOptions(userId)]}>
          <UserProfile userId={userId} />
        </QueriesHydration>
      </Suspense>
      <Suspense fallback={<div>Loading posts...</div>}>
        <QueriesHydration queries={[postsInfiniteQueryOptions(userId)]}>
          <InfinitePostList userId={userId} />
        </QueriesHydration>
      </Suspense>
    </>
  )
}
```

## Props

### queries

An array of queries or infinite queries to be prefetched on the server. Each query must have a `queryKey`. You can mix regular queries and infinite queries in the same array.

```tsx
type QueriesHydrationProps = {
  queries: (
    | WithRequired<QueryOptions<any, any, any, any>, 'queryKey'>
    | WithRequired<UseInfiniteQueryOptions<any, any, any, any, any>, 'queryKey'>
  )[]
  children: ReactNode
  queryClient?: QueryClient // Optional (default: new QueryClient())
  skipSsrOnError?: boolean | { fallback: ReactNode } // Optional (default: true)
  timeout?: number // Optional (unit: ms)
}
```

### queryClient

Optionally, you can pass a QueryClient instance to use. If not provided, a new QueryClient instance will be created.

```tsx /QueriesHydration/
import { QueryClient } from '@tanstack/react-query'
import { QueriesHydration } from '@suspensive/react-query'

const queryClient = new QueryClient()

const Page = async () => {
  return (
    <QueriesHydration queryClient={queryClient} queries={[]}>
      {/* ... */}
    </QueriesHydration>
  )
}
```

### skipSsrOnError

Controls the behavior when an error occurs while fetching queries on the server. This option becomes clearer when you understand the 3 stages where data fetching occurs:

1. **RSC (React Server Component)**: Query execution in `QueriesHydration`
2. **RCC (React Client Component) - Server**: Query execution in `useSuspenseQuery` if no cached data exists
3. **RCC (React Client Component) - Browser**: Query execution in `useSuspenseQuery` if no cached or fresh data exists

If stage 1 fails, stage 2 is likely to fail for the same reason. However, stage 3 (browser) might succeed (e.g., authentication-related issues, etc.). Since the browser can retry and potentially succeed, it's better to use `skipSsrOnError` to skip RCC(server) and fetch directly from RCC(browser) when RSC fails.

**Important**: When stage 1 succeeds (no error), the data is already hydrated to the client. In this case, you can verify in the browser's Network tab that no additional fetch requests are made in stages 2 and 3, as the data is served from the cache. This demonstrates the efficiency of server-side prefetching with `QueriesHydration`.

- `true` (default): If stage 1 fails, skip SSR and retry in stage 3 (browser)
- `false`: Even if stage 1 fails, proceed to stage 2 without hydration (retry fetching on server)
- `{ fallback: ReactNode }`: If stage 1 fails, skip SSR and display a custom fallback UI while moving to stage 3

```tsx /QueriesHydration/
import { QueriesHydration } from '@suspensive/react-query'
import { Suspense } from '@suspensive/react'
import {
  userQueryOptions,
  postsQueryOptions,
  commentsQueryOptions,
} from './queries'
import { UserProfile, PostList, CommentList } from './_components'

const Page = async ({ userId }: { userId: number }) => {
  return (
    <>
      {/* Skip SSR and retry in browser if stage 1 fails (default behavior) */}
      <Suspense fallback={<div>Loading...</div>}>
        <QueriesHydration queries={[userQueryOptions(userId)]}>
          <UserProfile />
        </QueriesHydration>
      </Suspense>

{/* Skip SSR and retry in browser with custom fallback if stage 1 fails */}
      <Suspense fallback={<div>Loading...</div>}>
        <QueriesHydration
          queries={[postsQueryOptions()]}
          skipSsrOnError={{
            fallback: <div>Unable to fetch data from server...</div>,
          }}
        >
          <PostList />
        </QueriesHydration>
      </Suspense>

{/* Retry in stage 2 (RCC server) even if stage 1 fails */}
      <Suspense fallback={<div>Loading...</div>}>
        <QueriesHydration
          queries={[commentsQueryOptions()]}
          skipSsrOnError={false}
        >
          <CommentList />
        </QueriesHydration>
      </Suspense>
    </>
  )
}
```

### timeout

Limits the time allowed for fetching queries on the server. An error is thrown if query fetching exceeds this limit. When not set, no timeout is applied.

When `skipSsrOnError` is true or passed as `{ fallback: ReactNode }`, exceeding the timeout causes the server to give up rendering and the browser will attempt to render instead.

const Page = async ({ userId }: { userId: number }) => {
  return (
    <>
      <Suspense fallback={<div>Loading...</div>}>
        {/* An error is thrown if the query takes longer than 1000ms to fetch */}
        <QueriesHydration queries={[userQueryOptions(userId)]} timeout={1000}>
          <UserProfile />
        </QueriesHydration>
      </Suspense>
    </>
  )
}
```

## Motivation: Simplify prefetching multiple queries in Server Components

In React Server Components environments, you can prefetch data on the server to eliminate initial loading states. However, manually prefetching and dehydrating multiple queries is cumbersome.

### Traditional approach: Manual prefetch and dehydrate

#### page.tsx (RSC)

```tsx
import {
  QueryClient,
  dehydrate,
  HydrationBoundary,
} from '@tanstack/react-query'
import { Suspense } from '@suspensive/react'
import { userQueryOptions, postsQueryOptions } from './queries'
import { UserProfile, PostList } from './_components'

// Server Component
const PostsPage = ({ userId }: { userId: number }) => {
  return (
    <>
      <Suspense fallback={<div>Loading user...</div>}>
        <UserProfileWithData userId={userId} />
      </Suspense>
      <Suspense fallback={<div>Loading posts...</div>}>
        <PostListWithData userId={userId} />
      </Suspense>
    </>
  )
}

// Need to separate each server component for HTML Streaming
const UserProfileWithData = async ({ userId }: { userId: number }) => {
  const queryClient = new QueryClient()
  try {
    await queryClient.ensureQueryData(userQueryOptions(userId))
  } catch (error) {
    return (
      // If queryClient.ensureQueryData fails, use ClientOnly to prevent SSR and render on the browser directly
      <ClientOnly fallback={<div>Loading user...</div>}>
        <UserProfile userId={userId} />
      </ClientOnly>
    )
  }
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <UserProfile userId={userId} />
    </HydrationBoundary>
  )
}

const PostListWithData = async ({ userId }: { userId: number }) => {
  const queryClient = new QueryClient()
  try {
    await queryClient.ensureQueryData(postsQueryOptions(userId))
  } catch (error) {
    return (
      // If queryClient.ensureQueryData fails, use ClientOnly to prevent SSR and render on the browser directly
      <ClientOnly fallback={<div>Loading posts...</div>}>
        <PostList userId={userId} />
      </ClientOnly>
    )
  }
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <PostList userId={userId} />
    </HydrationBoundary>
  )
}
```

#### UserProfile.tsx (RCC)

```tsx
'use client'

import { useSuspenseQuery } from '@suspensive/react-query'
import { userQueryOptions } from './queries'

export const UserProfile = ({ userId }: { userId: number }) => {
  const { data: user } = useSuspenseQuery(userQueryOptions(userId))

return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  )
}
```

#### PostList.tsx (RCC)

```tsx
'use client'

import { useSuspenseQuery } from '@suspensive/react-query'
import { postsQueryOptions } from './queries'

export const PostList = ({ userId }: { userId: number }) => {
  const { data: posts } = useSuspenseQuery(postsQueryOptions(userId))

return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}
```

### Using QueriesHydration

With `<QueriesHydration/>`, all of this is handled automatically:

#### page.tsx (RSC)

#### UserProfile.tsx (RCC)

```tsx
'use client'

import { useSuspenseQuery } from '@suspensive/react-query'
import { userQueryOptions } from './queries'

export const UserProfile = ({ userId }: { userId: number }) => {
  // Data prefetched on the server is automatically hydrated
  const { data: user } = useSuspenseQuery(userQueryOptions(userId))

return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  )
}
```

#### PostList.tsx (RCC)

```tsx
'use client'

import { useSuspenseQuery } from '@suspensive/react-query'
import { postsQueryOptions } from './queries'

export const PostList = ({ userId }: { userId: number }) => {
  // Data prefetched on the server is automatically hydrated
  const { data: posts } = useSuspenseQuery(postsQueryOptions(userId))

return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}
```

Key benefits:

1. **Concise code**: Automates QueryClient creation, prefetch, and dehydrate processes
2. **Parallel data fetching**: Uses `Promise.all` to process all queries in parallel
3. **Type safety**: Requires queryKey to prevent mistakes
4. **Consistent pattern**: Handles multiple queries consistently

## Dependent Queries and Streaming

When handling dependent queries, wrapping each component with a separate `QueriesHydration` maximizes streaming benefits by creating independent Suspense boundaries. By sharing the same `queryClient`, you can use the result of the first query in subsequent queries.

#### page.tsx (RSC)

```tsx /QueriesHydration/
import { QueryClient } from '@tanstack/react-query'
import { QueriesHydration } from '@suspensive/react-query'
import { Suspense } from '@suspensive/react'
import {
  productQueryOptions,
  productReviewsQueryOptions,
  relatedProductsQueryOptions,
} from './queries'
import { ProductInfo, ProductReviews, RelatedProducts } from './_components'

const ProductPage = async ({ productId }: { productId: string }) => {
  const queryClient = new QueryClient()

// 1. First, fetch product information
  const product = await queryClient.ensureQueryData(
    productQueryOptions(productId)
  )

return (
    <>
      {/* Product information */}
      <Suspense fallback={<div>Loading product...</div>}>
        <QueriesHydration
          queryClient={queryClient}
          queries={[productQueryOptions(productId)]}
        >
          <ProductInfo productId={productId} />
        </QueriesHydration>
      </Suspense>

{/* Product reviews: depends on product information (e.g., filtered by product category) */}
      <Suspense fallback={<div>Loading reviews...</div>}>
        <QueriesHydration
          queryClient={queryClient}
          queries={[productReviewsQueryOptions(productId)]}
        >
          <ProductReviews productId={productId} />
        </QueriesHydration>
      </Suspense>

{/* Related products: depends on product information (same category) */}
      <Suspense fallback={<div>Loading related products...</div>}>
        <QueriesHydration
          queryClient={queryClient}
          queries={[relatedProductsQueryOptions(product.categoryId)]}
        >
          <RelatedProducts categoryId={product.categoryId} />
        </QueriesHydration>
      </Suspense>
    </>
  )
}
```

#### ProductInfo.tsx (RCC)

```tsx
'use client'

import { useSuspenseQuery } from '@suspensive/react-query'
import { productQueryOptions } from './queries'

export const ProductInfo = ({ productId }: { productId: string }) => {
  // Data prefetched on the server is automatically hydrated
  const { data: product } = useSuspenseQuery(productQueryOptions(productId))

return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <p>Price: {product.price}</p>
    </div>
  )
}
```

#### ProductReviews.tsx (RCC)

```tsx
'use client'

import { useSuspenseQuery } from '@suspensive/react-query'
import { productReviewsQueryOptions } from './queries'

export const ProductReviews = ({ productId }: { productId: string }) => {
  // Data prefetched on the server is automatically hydrated
  const { data: reviews } = useSuspenseQuery(
    productReviewsQueryOptions(productId)
  )

return (
    <div>
      <h2>Reviews</h2>
      <ul>
        {reviews.map((review) => (
          <li key={review.id}>
            <p>{review.comment}</p>
            <p>Rating: {review.rating}</p>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

#### RelatedProducts.tsx (RCC)

```tsx
'use client'

import { useSuspenseQuery } from '@suspensive/react-query'
import { relatedProductsQueryOptions } from './queries'

export const RelatedProducts = ({ categoryId }: { categoryId: string }) => {
  // Data prefetched on the server is automatically hydrated
  const { data: relatedProducts } = useSuspenseQuery(
    relatedProductsQueryOptions(categoryId)
  )

return (
    <div>
      <h2>Related Products</h2>
      <ul>
        {relatedProducts.map((product) => (
          <li key={product.id}>{product.name}</li>
        ))}
      </ul>
    </div>
  )
}
```

Benefits of this pattern:

1. **Independent Suspense boundaries**: Each component streams independently, so `ProductInfo` renders first when ready
2. **Shared queryClient**: Cache is shared, allowing reuse of `product` data
3. **Dependent queries support**: You can pass `product.categoryId` to `relatedProductsQueryOptions`
4. **Progressive rendering**: Components stream sequentially as they become ready

## Example

Here's a live example demonstrating `QueriesHydration` with Next.js streaming:

![Next.js Streaming React Query Example](/img/next-streaming-react-query-example.gif)

- **[Live Demo](https://next-streaming-react-query.suspensive.org)**: See it in action
- **[Source Code](https://github.com/toss/suspensive/tree/main/examples/next-streaming-react-query)**: View the full implementation

**Tip**: In the live demo, check the "4. no error (Best Practice)" case and open the browser's Developer Tools Network tab. You'll notice that no fetch requests are made because the data was successfully prefetched on the server and hydrated to the client, demonstrating the efficiency of `QueriesHydration`.

## Disabling SSR

If you want to skip server-side rendering for a specific component, simply add the `clientOnly` prop to `<Suspense/>`. In this case, since you don't need to prefetch data on the server, you don't need `QueriesHydration` either:

const PostsPage = ({ userId }: { userId: number }) => {
  return (
    <>
      {/* UserProfile skips SSR and only renders on the client */}
      <Suspense clientOnly fallback={<div>Loading user...</div>}>
        <UserProfile userId={userId} />
      </Suspense>
      {/* PostList is prefetched and rendered on the server */}
      <Suspense fallback={<div>Loading posts...</div>}>
        <QueriesHydration queries={[postsQueryOptions(userId)]}>
          <PostList userId={userId} />
        </QueriesHydration>
      </Suspense>
    </>
  )
}
```

When using the `clientOnly` prop:

- Components within that Suspense boundary will not be rendered on the server
- Data will only be fetched and rendered on the client
- You don't need `QueriesHydration` since server-side prefetch is not needed

## Version Differences

### @tanstack/react-query v5

In `@tanstack/react-query` v5, it uses the `HydrationBoundary` component.

```tsx
import { HydrationBoundary } from '@tanstack/react-query'
import { QueriesHydration } from '@suspensive/react-query'

// QueriesHydration internally uses HydrationBoundary
```

### @tanstack/react-query v4

In `@tanstack/react-query` v4, it uses the `Hydrate` component.

```tsx
import { Hydrate } from '@tanstack/react-query'
import { QueriesHydration } from '@suspensive/react-query'

// QueriesHydration internally uses Hydrate
```

## Important Notes

- This component is an **async server component**.
- It can only be used in frameworks that support React Server Components (Next.js 13+ App Router, etc.).
- All queries must include a `queryKey`.

### Version History

| Version | Changes                                                          |
| ------- | ---------------------------------------------------------------- |
| v3.14.0 | `<QueriesHydration/>` has been added as an experimental feature. |

---

## QueryClientConsumer

URL: /docs/react-query/QueryClientConsumer

# QueryClientConsumer

> **Experimental:** `<QueryClientConsumer/>` is an experimental feature, so this interface may change.

This component allows the use of `useQueryClient` within JSX to bypass the constraints of React hooks.

The props interface varies depending on the version of `@tanstack/react-query` installed in the user environment. If version 4 is installed, you need to use `props.context`. For version 5, you must use `props.queryClient`.  
If the QueryClient is not passed through props, the component will use the nearest available QueryClient.

```tsx /QueryClientConsumer/
import { useSuspenseQuery } from '@tanstack/react-query'
import { QueryClientConsumer } from '@suspensive/react-query'

const PostsPage = () => {
  const { data: posts } = useSuspenseQuery({
    queryKey: ['posts'],
    queryFn: () => getPosts(),
  })

return (
    <>
      <QueryClientConsumer>
        {(queryClient) => (
          <button
            onClick={() =>
              queryClient.invalidateQueries({
                queryKey: ['posts'],
              })
            }
          >
            Posts refresh
          </button>
        )}
      </QueryClientConsumer>
      {posts.map((post) => (
        <Post key={post.id} {...post} />
      ))}
    </>
  )
}
```

### props.queryClient (@tanstack/react-query v5)

If you are using `@tanstack/react-query` version 5, you can access the desired QueryClient through `props.queryClient`.

```tsx /QueryClientConsumer/
import { QueryClient } from '@tanstack/react-query'
import { QueryClientConsumer } from '@suspensive/react-query'

const queryClient = new QueryClient()

const Example = () => {
  return (
      {/* 5️⃣ Use props.queryClient if you are working with @tanstack/react-query v5 */}
      <QueryClientConsumer queryClient={queryClient}>
        {(queryClient) => (<>{/* Use the QueryClient passed via props.queryClient */}</>)}
      </QueryClientConsumer>
  )
}
```

### props.context (@tanstack/react-query v4)

If you are using `@tanstack/react-query` version 4, use `props.context` to access the desired QueryClient.

```tsx /QueryClientConsumer/
import { createContext } from 'react'
import { QueryClient } from '@tanstack/react-query'
import { QueryClientConsumer } from '@suspensive/react-query'

const queryClient = new QueryClient()
const queryClientContext = createContext<QueryClient>(queryClient)

const Example = () => {
  return (
      {/* 4️⃣ Use props.context if you are working with @tanstack/react-query v4 */}
      <QueryClientConsumer context={queryClientContext}>
        {(queryClient) => (<>{/* Use the QueryClient passed via props.context */}</>)}
      </QueryClientConsumer>
  )
}
```

### Motivation: React hooks can only be used in functional components

React's hook (useQueryClient) can only be used within functional components. However, there are cases when you need features like invalidateQueries even within legacy class components. In such cases, `<QueryClientConsumer/>` helps you overcome these limitations.

```tsx /QueryClientConsumer/
import React from 'react'
import { QueryClientConsumer } from '@suspensive/react-query'

class PostsRefreshButton extends React.Component {
  render() {
    return (
      {/* ✅ Access the queryClient to invalidate queries within a legacy class component */}
      <QueryClientConsumer>
        {(queryClient) => (
          <button
            onClick={() =>
              queryClient.invalidateQueries({
                queryKey: ['posts'],
              })
            }
          >
            Posts refresh
          </button>
        )}
      </QueryClientConsumer>
    )
  }
}

export default PostsRefreshButton
```

---

## IsFetching

URL: /docs/react-query/IsFetching

# IsFetching

> **Experimental:** `<IsFetching/>` is an experimental feature, so this interface may change.

Render-prop component that exposes the number of queries currently fetching (from TanStack Query's `useIsFetching`). Useful for showing global loading indicators without adding hooks in every component.

```tsx /IsFetching basic/
import { IsFetching } from '@suspensive/react-query'

const GlobalFetchingIndicator = () => (
  <IsFetching>{(isFetching) => (isFetching ? <Spinner /> : null)}</IsFetching>
)
```

### Filters (QueryFilters)

You can scope the indicator with the same filters accepted by TanStack Query's `useIsFetching` (e.g., `queryKey`, `predicate`).

```tsx /IsFetching with filters/
import { IsFetching } from '@suspensive/react-query'

const PostsFetchingIndicator = () => (
  <IsFetching queryKey={['posts']}>
    {(isFetching) => (isFetching ? <Spinner /> : null)}
  </IsFetching>
)
```

### Props

- **children**: `(isFetching: number) => ReactNode`
- **...QueryFilters**: Same shape as TanStack Query's `QueryFilters` for `useIsFetching`.

---

## createGetQueryClient

URL: /docs/react-query/createGetQueryClient

# createGetQueryClient

> **Experimental:** `createGetQueryClient` is an experimental feature, so this interface may change.

A utility function to manage QueryClient instances in a server-safe manner.

- **On the server**: Always creates a new QueryClient instance for each request
- **In the browser**: Returns a singleton QueryClient instance, creating one if it doesn't exist

This pattern is essential for proper React Query usage with SSR frameworks like Next.js, as it prevents sharing QueryClient state between requests on the server while maintaining a single instance in the browser to preserve cache across re-renders.

> **Important:** Sharing a QueryClient between requests on the server can lead to **serious security vulnerabilities**. `getQueryClient` creates a new QueryClient instance for each request to prevent data leakage between users and exposure of sensitive information. See the [Server-Side Behavior](#server-side-behavior) section below for details.

## Basic Usage

First, create a `get-query-client.ts` file in your project:

```tsx
// get-query-client.ts
import { createGetQueryClient } from '@suspensive/react-query'

export const { getQueryClient } = createGetQueryClient()
```

Then, import and use it in your code:

```tsx
// app/providers.tsx
'use client'

import { QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { getQueryClient } from '@/app/get-query-client'
import type * as React from 'react'

export default function Providers({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient()

return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools />
    </QueryClientProvider>
  )
}
```

## Configuration

You can pass a `QueryClientConfig` to `createGetQueryClient` to customize the QueryClient instance:

```tsx
// get-query-client.ts
import { createGetQueryClient } from '@suspensive/react-query'

export const { getQueryClient } = createGetQueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5000,
      retry: 3,
    },
  },
})
```

```tsx
// app/providers.tsx
'use client'

export default function Providers({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient()

return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools />
    </QueryClientProvider>
  )
}
```

> **Warning:** **Browser Environment Behavior**
> 
> In the browser environment, the config provided when calling `createGetQueryClient` is used to create the QueryClient instance. The `getQueryClient` function does not accept any arguments and will always return the same singleton instance. This is intentional to maintain a stable singleton across re-renders.

## Server-Side Behavior

### Preventing Security Issues (Highest Priority)

Sharing a QueryClient between requests on the server can lead to serious security vulnerabilities:

- **Data leakage between users**: One user's data may be exposed to another user
- **Sensitive information exposure**: Authentication tokens, personal information, etc. may be included in another user's request
- **Incorrect cache state**: Cached data from a previous request may be incorrectly returned to the next request

`getQueryClient` creates a new QueryClient instance for each request to completely prevent these security issues.

> 💡 **Related documentation**: For more information about why QueryClient should not be shared between requests on the server, see the [TanStack Query SSR Guide - Initial Setup](https://tanstack.com/query/latest/docs/framework/react/guides/ssr#initial-setup) section.

### Setting Cache Removal Time to Prevent OOM

On the server, `getQueryClient` sets the cache removal time to `Infinity` to prevent memory leaks and OOM (Out of Memory) errors. This is an additional safety measure to address memory issues that can occur when servers handle many concurrent requests.

`gcTime` (v5) or `cacheTime` (v4) represents the time until TanStack Query removes query data from the QueryClient's cache. By setting this to `Infinity` on the server:

- Data is not automatically removed from the cache, keeping it available until the request completes
- The [`isValidTimeout`](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts) check in TanStack Query prevents `setTimeout` scheduling in [`scheduleGc`](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L13-L21), completely eliminating the performance cost that would occur with many concurrent requests

This behavior is **automatic and cannot be overridden** - even if you provide a different cache removal time value in your config, it will be set to `Infinity` on the server. (In v4, the `cacheTime` option is used; in v5, the `gcTime` option is used. See the Version Differences section below for details.)

> 💡 **Related documentation**: For more information about high memory consumption on server and why `gcTime` defaults to `Infinity` on the server, see the [TanStack Query SSR Guide - High memory consumption on server](https://tanstack.com/query/latest/docs/framework/react/guides/ssr#high-memory-consumption-on-server) section.

```tsx
// get-query-client.ts
import { createGetQueryClient } from '@suspensive/react-query'

// Config is passed to createGetQueryClient, not getQueryClient
export const { getQueryClient } = createGetQueryClient({
  defaultOptions: {
    queries: {
      // On server, cache removal time is set to Infinity
      // to keep cache alive until the request completes and prevent setTimeout scheduling
      gcTime: 5000, // v5: This will be overridden to Infinity on server
      // In v4, cacheTime is used and also overridden to Infinity
    },
  },
})

// On server: Cache removal time is always Infinity (OOM prevention)
// On browser: Uses the provided value (or default)
```

### New Instance Per Request

On the server, `getQueryClient` creates a new QueryClient instance for each call. This ensures that:

- Each request has isolated cache state
- No data leaks between different user requests
- Proper cleanup when the request completes

```tsx
// get-query-client.ts
import { createGetQueryClient } from '@suspensive/react-query'

export const { getQueryClient } = createGetQueryClient()
```

```tsx
// Server environment
const queryClient1 = getQueryClient()
const queryClient2 = getQueryClient()

// queryClient1 !== queryClient2 (different instances)
```

## Browser-Side Behavior

### Singleton Pattern

In the browser, `getQueryClient` returns the same QueryClient instance across multiple calls. This ensures:

- Cache is preserved across re-renders
- Consistent state management
- Optimal performance

```tsx
// get-query-client.ts
import { createGetQueryClient } from '@suspensive/react-query'

export const { getQueryClient } = createGetQueryClient()
```

```tsx
// Browser environment
const queryClient1 = getQueryClient()
const queryClient2 = getQueryClient()

// queryClient1 === queryClient2 (same instance)
```

## Use Cases

### Next.js App Router

```tsx
// get-query-client.ts
import { createGetQueryClient } from '@suspensive/react-query'

export const { getQueryClient } = createGetQueryClient()
```

```tsx
// app/providers.tsx
'use client'

export default function Providers({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient()

return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools />
    </QueryClientProvider>
  )
}
```

```tsx
// app/layout.tsx
import { Providers } from './providers'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}
```

### With Custom Configuration

```tsx
// get-query-client.ts
import { createGetQueryClient } from '@suspensive/react-query'

export const { getQueryClient } = createGetQueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 minutes
      gcTime: 1000 * 60 * 10, // 10 minutes (v5)
      // cacheTime: 1000 * 60 * 10, // 10 minutes (v4)
      retry: 2,
      refetchOnWindowFocus: false,
    },
    mutations: {
      retry: 1,
    },
  },
})
```

```tsx
// app/providers.tsx
'use client'

export default function Providers({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient()

return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools />
    </QueryClientProvider>
  )
}
```

## Version Differences

### @tanstack/react-query v4

In v4, use the `createGetQueryClient` function, and the cache time option is called `cacheTime`:

```tsx
// get-query-client.ts
import { createGetQueryClient } from '@suspensive/react-query'

export const { getQueryClient } = createGetQueryClient()
```

```tsx
// get-query-client.ts
import { createGetQueryClient } from '@suspensive/react-query'

// Server: cacheTime is automatically set to Infinity
export const { getQueryClient } = createGetQueryClient({
  defaultOptions: {
    queries: {
      cacheTime: 5000, // Overridden to Infinity on server
    },
  },
})
```

```tsx
// app/providers.tsx
'use client'

export default function Providers({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient()

return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools />
    </QueryClientProvider>
  )
}
```

### @tanstack/react-query v5

In v5, use the `createGetQueryClient` function, and the cache time option is called `gcTime` (garbage collection time):

```tsx
// get-query-client.ts
import { createGetQueryClient } from '@suspensive/react-query'

export const { getQueryClient } = createGetQueryClient()
```

```tsx
// get-query-client.ts
import { createGetQueryClient } from '@suspensive/react-query'

// Server: gcTime is automatically set to Infinity
export const { getQueryClient } = createGetQueryClient({
  defaultOptions: {
    queries: {
      gcTime: 5000, // Overridden to Infinity on server
    },
  },
})
```

```tsx
// app/providers.tsx
'use client'

export default function Providers({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient()

return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools />
    </QueryClientProvider>
  )
}
```

## Important Notes

- **Server safety**: Always use `getQueryClient` instead of creating `new QueryClient()` directly in SSR environments to ensure proper request isolation and OOM prevention.

> **Error:** **Never use QueryClient as a global variable**
> 
> Even if you use `getQueryClient`, storing it in a global variable like `export const queryClient = getQueryClient()` in App Router and importing it elsewhere will cause the same security risks. The QueryClient instance will be shared between requests on the server, leading to data leakage between users. Always call `getQueryClient()` directly where you need it, rather than storing it in a global variable.

- **Browser singleton**: The browser instance is a singleton. Configure your QueryClient when calling `createGetQueryClient`, as `getQueryClient` does not accept any arguments.

- **Automatic OOM prevention**: The cache removal time override to `Infinity` on the server is automatic and cannot be disabled. This is a safety feature to prevent memory issues. (In v4, the `cacheTime` option is used; in v5, the `gcTime` option is used.)

---

## usePrefetchQuery

URL: /docs/react-query/usePrefetchQuery

# usePrefetchQuery

The usePrefetchQuery does not return anything, it should be used just to fire a prefetch during render, before a suspense boundary that wraps a component that uses useSuspenseQuery.

```jsx /usePrefetchQuery/
import { usePrefetchQuery, useSuspenseQuery } from '@suspensive/react-query'

const PostPage = ({ postId }) => {
  usePrefetchQuery({
    queryKey: ['posts', postId],
    queryFn: () => getPost(postId),
  }) // Prefetch query before suspense boundary

return (
    <Suspense fallback={<div>Loading...</div>}>
      <Post postId={postId} />
    </Suspense>
  )
}

export const Post = ({ postId }) => {
  const { data } = useSuspenseQuery({
    queryKey: ['posts', postId],
    queryFn: () => getPost(postId),
  })

return <>...</>
}
```

---

## usePrefetchInfiniteQuery

URL: /docs/react-query/usePrefetchInfiniteQuery

# usePrefetchInfiniteQuery

The usePrefetchInfiniteQuery does not return anything, it should be used just to fire a prefetch during render, before a suspense boundary that wraps a component that uses useSuspenseInfiniteQuery.

```jsx /usePrefetchInfiniteQuery/
import {
  usePrefetchInfiniteQuery,
  useSuspenseInfiniteQuery,
} from '@suspensive/react-query'

const PostsPage = ({ postId }) => {
  usePrefetchInfiniteQuery({
    queryKey: ['posts'],
    queryFn: () => getPosts(),
  }) // Prefetch query before suspense boundary

return (
    <Suspense fallback={<div>Loading...</div>}>
      <Posts />
    </Suspense>
  )
}

export const Posts = () => {
  const postsInfiniteQuery = useSuspenseInfiniteQuery({
    queryKey: ['posts'],
    queryFn: () => getPosts(),
  })

return <>...</>
}
```

---

## queryOptions

URL: /docs/react-query/queryOptions

# queryOptions

> **Warning:** **Deprecated in @suspensive/react-query**
> 
> This interface is now officially supported in TanStack Query v4.40.0+. Since TanStack Query has backported this interface, we are deprecating the backported version from @suspensive/react-query. Please migrate to the official TanStack Query interface:
> 
> ```diff
- import { queryOptions } from '@suspensive/react-query'
+ import { queryOptions } from '@tanstack/react-query'
```
> 
> For more details, see [TanStack Query PR #9140](https://github.com/TanStack/query/pull/9140).

Tkdodo, The maintainer of TanStack Query explains well why this interface is needed in [video explaining queryOptions in TanStack Query v5](https://youtu.be/bhE3wuB_TuA?feature=shared&t=1697).
You can also use queryOptions in TanStack Query v4.

1. QueryKey management becomes easier by processing queryKey and queryFn together.
2. You can remove unnecessary custom query hooks. This is because they can all be used directly in `useQuery`, `useQueries` of TanStack Query v4, and `useSuspenseQuery`, `useSuspenseQueries`, and `SuspenseQuery` of Suspensive React Query.
3. TanStack Query v5 already supports queryOptions. This Suspensive React Query's `queryOptions` will make migration from TanStack Query v4 to TanStack Query v5 easier.

```jsx /queryOptions/
import { queryOptions, useSuspenseQuery, useSuspenseQueries, SuspenseQuery } from '@suspensive/react-query'
import { useQuery, useQueries, useQueryClient } from '@tanstack/react-query'

const postQueryOptions = (postId) =>
   queryOptions({
     queryKey: ['posts', postId] as const,
     queryFn: ({
       queryKey: [, postId], // You can use queryKey.
     }) => fetch(`https://example.com/posts/${postId}`),
   })

// No need to create custom query hooks.
// You can use queryOptions directly in useQuery, useQueries, useSuspenseQuery, useSuspenseQueries, SuspenseQuery.
const post1Query = useQuery(postQueryOptions(1))
const { data: post1 } = useSuspenseQuery({
   ...postQueryOptions(1);
   refetchInterval: 2000, // Extensibility is clearly expressed in usage.
})
const [post1Query, post2Query] = useQueries({
   queries: [postQueryOptions(1), { ...postQueryOptions(2), refetchInterval: 2000 }],
})
const [{ data: post1 }, { data: post2 }] = useSuspenseQueries({
   queries: [postQueryOptions(1), { ...postQueryOptions(2), refetchInterval: 2000 }],
})
const Example = () => <SuspenseQuery {...postQueryOptions(1)}>{({ data: post1 }) => <>{post1.text}</>}</SuspenseQuery>

// You can easily use queryKey and queryFn in queryClient's methods.
const queryClient = useQueryClient()
queryClient.refetchQueries(postQueryOptions(1))
queryClient.prefetchQuery(postQueryOptions(1))
queryClient.invalidateQueries(postQueryOptions(1))
queryClient.fetchQuery(postQueryOptions(1))
queryClient.resetQueries(postQueryOptions(1))
queryClient.cancelQueries(postQueryOptions(1))

```

### Version History

| Version  | Changes                                                                                                                       |
| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `v3.0.0` | `networkMode` has been removed. For more details, please refer to the [Migration to v3 guide](./migration/migrate-to-v3.mdx). |

---

## mutationOptions

URL: /docs/react-query/mutationOptions

# mutationOptions

> **Warning:** **Deprecated in @suspensive/react-query**
> 
> This interface is now officially supported in TanStack Query v4.44.0+. Since TanStack Query has backported this interface, we are deprecating the backported version from @suspensive/react-query. Please migrate to the official TanStack Query interface:
> 
> ```diff
- import { mutationOptions } from '@suspensive/react-query'
+ import { mutationOptions } from '@tanstack/react-query'
```

`mutationOptions` helps you easily reuse and consistently manage option objects for Mutations. This provides similar benefits to the ones offered by [`queryOptions`](/docs/react-query/queryOptions).

```jsx /mutationOptions/
import { mutationOptions, useMutation, Mutation } from '@suspensive/react-query'

const editPostMutationOptions = (postId: number) =>
  mutationOptions({
    mutationFn: (content: string) => fetch(`https://example.com/posts/${postId}`, {
      method: 'PATCH',
      body: JSON.stringify({ content }),
    }).then(res => res.json()),
  })

// You can directly use mutationOptions without creating custom mutation hooks.
const editPostMutation = useMutation(editPostMutationOptions(1))

// Directly use mutationOptions with <Mutation />.
const Example = () => (
  <Mutation {...editPostMutationOptions(1)}>
    {({ mutate, isLoading }) => (
      <div>
        <p>{isLoading ? 'Updating...' : 'Latest updated'}</p>
        <textarea onBlur={(e) => mutate(e.target.value)} disabled={isLoading} />
      </div>
    )}
  </Mutation>
)
```

---

## infiniteQueryOptions

URL: /docs/react-query/infiniteQueryOptions

# infiniteQueryOptions

> **Warning:** **Deprecated in @suspensive/react-query**
> 
> This interface is now officially supported in TanStack Query v4.41.0+. Since TanStack Query has backported this interface, we are deprecating the backported version from @suspensive/react-query. Please migrate to the official TanStack Query interface:
> 
> ```diff
- import { infiniteQueryOptions } from '@suspensive/react-query'
+ import { infiniteQueryOptions } from '@tanstack/react-query'
```
> 
> For more details, see [TanStack Query PR #9334](https://github.com/TanStack/query/pull/9334).

`infiniteQueryOptions` helps utilize queryOptions in Infinite Query. This provides similar benefits to the ones offered by [`queryOptions`](https://suspensive.org/docs/react-query/queryOptions).

```jsx /infiniteQueryOptions/
import { infiniteQueryOptions, useSuspenseInfiniteQuery, SuspenseInfiniteQuery } from '@suspensive/react-query'
import { useInfiniteQuery, useQueryClient } from '@tanstack/react-query'

const postsInfiniteQueryOptions = (page) =>
  infiniteQueryOptions({
    queryKey: ['posts', page] as const,
    queryFn: ({
      queryKey: [, page], // You can use queryKey.
    }) => fetch(`https://example.com/posts?page=${page}`).then(res => res.json()),
    getNextPageParam: (lastPage) => lastPage.nextPage ?? false,
  })

// No need to create a custom query hook.
// You can directly utilize infiniteQueryOptions in useInfiniteQuery, useSuspenseInfiniteQuery, and SuspenseInfiniteQuery.
const postsQuery = useInfiniteQuery(postsInfiniteQueryOptions(1))
const { data: posts, fetchNextPage, hasNextPage } = useSuspenseInfiniteQuery({
  ...postsInfiniteQueryOptions(1),
  refetchInterval: 2000, // Extensibility is clearly expressed in usage.
})
const Example = () => (
  <SuspenseInfiniteQuery {...postsInfiniteQueryOptions(1)}>
    {({ data, fetchNextPage, hasNextPage }) => (
      <div>
        {data.pages.map((page, index) => (
          <div key={index}>
            {page.posts.map(post => (
              <div key={post.id}>{post.title}</div>
            ))}
          </div>
        ))}
        <button onClick={() => fetchNextPage()} disabled={!hasNextPage}>
          Load More
        </button>
      </div>
    )}
  </SuspenseInfiniteQuery>
)

// You can easily use queryKey and queryFn in queryClient's methods.
const queryClient = useQueryClient()
queryClient.refetchQueries(postsInfiniteQueryOptions(1))
queryClient.prefetchQuery(postsInfiniteQueryOptions(1))
queryClient.invalidateQueries(postsInfiniteQueryOptions(1))
queryClient.fetchQuery(postsInfiniteQueryOptions(1))
queryClient.resetQueries(postsInfiniteQueryOptions(1))
queryClient.cancelQueries(postsInfiniteQueryOptions(1))
```

### Version History

---

## useSuspenseQuery

URL: /docs/react-query/useSuspenseQuery

# useSuspenseQuery

> **Warning:** **Deprecated in @suspensive/react-query**
> 
> This hook is now officially supported in TanStack Query v4.40.0+. Since TanStack Query has backported this interface, we are deprecating the backported version from @suspensive/react-query. Please migrate to the official TanStack Query interface:
> 
> ```diff
- import { useSuspenseQuery } from '@suspensive/react-query'
+ import { useSuspenseQuery } from '@tanstack/react-query'
```
> 
> For more details, see [TanStack Query PR #9140](https://github.com/TanStack/query/pull/9140).

There is no isLoading or isError in the return type of this hook. This is because `<Suspense/>` and `<ErrorBoundary/>` guarantee the data of this hook. Also, in the options of this hook, suspense is set to true by default. Any new options you need can be used like @tanstack/react-query's [useQuery](https://tanstack.com/query/v4/docs/react/reference/useQuery).

```tsx /useSuspenseQuery/
import { useSuspenseQuery } from '@suspensive/react-query'

const Example = () => {
  const query = useSuspenseQuery({
    queryKey,
    queryFn,
  }) // suspense: true is the default.

// No type narrowing required with isSuccess.
  query.data // TData
}
```

### Motivation

You can use [useQuery](https://tanstack.com/query/v4/docs/react/reference/useQuery) with `<Suspense/>` and `<ErrorBoundary/>` by using the suspense option in @tanstack/react-query.

```tsx /useQuery/
import { useQuery } from '@tanstack/react-query'

const Example = () => {
  const query = useQuery({
    queryKey,
    queryFn,
    suspense: true,
  })

query.data // TData | undefined

if (query.isSuccess) {
    query.data // TData
  }
}
```

The return type of useQuery (query.data) will always be a success case thanks to this component's parents, `<Suspense/>` and `<ErrorBoundary/>`.
But @tanstack/react-query doesn't express this in its TypeScript types.

That's why @suspensive/react-query provides **useSuspenseQuery**.

> **Note:** Focus on successful cases.
> 
> Now we can focus only on successful cases as fetching always succeeds inside our component.

### Version History

| Version  | Changes                                                                                                                                   |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `v3.0.0` | `networkMode` has been fixed to `'always'`. For more details, please refer to the [Migration to v3 guide](./migration/migrate-to-v3.mdx). |

---

## useSuspenseQueries

URL: /docs/react-query/useSuspenseQueries

# useSuspenseQueries

> **Warning:** **Deprecated in @suspensive/react-query**
> 
> This hook is now officially supported in TanStack Query v4.40.0+. Since TanStack Query has backported this interface, we are deprecating the backported version from @suspensive/react-query. Please migrate to the official TanStack Query interface:
> 
> ```diff
- import { useSuspenseQueries } from '@suspensive/react-query'
+ import { useSuspenseQueries } from '@tanstack/react-query'
```
> 
> For more details, see [TanStack Query PR #9140](https://github.com/TanStack/query/pull/9140).

There is no isLoading or isError in the return type of this hook. This is because `<Suspense/>` and `<ErrorBoundary/>` guarantee the data of this hook. Also, in the options of this hook, suspense is set to true by default. You can use @tanstack/react-query's [useQueries](https://tanstack.com/query/v4/docs/react/reference/useQueries) for the new options you need.

```tsx /useSuspenseQueries/
import { useSuspenseQueries } from '@suspensive/react-query'

const Example = () => {
  const [query1, query2] = useSuspenseQueries({
    queries: [
      { queryKey: [1], queryFn },
      { queryKey: [2], queryFn },
    ],
  }) // suspense: true is the default.

// No type narrowing required with isSuccess.
  query1.data // TData
  query2.data // TData
}
```

### Motivation

You can use [useQueries](https://tanstack.com/query/v4/docs/react/reference/useQueries) with `<Suspense/>` and `<ErrorBoundary/>` by using the suspense option of @tanstack/react-query useQueries.

```tsx /useQueries/
import { useQueries } from '@tanstack/react-query'

const Example = () => {
  const [query1, query2] = useQueries({
    queries: [
      { queryKey: [1], queryFn, suspense: true },
      { queryKey: [2], queryFn, suspense: true },
    ],
  })

query1.data // TData | undefined
  query2.data // TData | undefined

if (query1.isSuccess) {
    query1.data // TData
  }
  if (query2.isSuccess) {
    query2.data // TData
  }
}
```

The return type of useQueries (query1.data, query2.data) will always be a success case thanks to this component's parents, `<Suspense/>` and `<ErrorBoundary/>`.
But @tanstack/react-query doesn't express this in its TypeScript types.

That's why @suspensive/react-query provides **useSuspenseQueries**.

> **Note:** Focus on successful cases.
> 
> Now we can focus only on successful cases as fetching always succeeds inside our component.

### Version History

| Version  | Changes                                                                                                                                   |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `v3.0.0` | `networkMode` has been fixed to `'always'`. For more details, please refer to the [Migration to v3 guide](./migration/migrate-to-v3.mdx). |

---

## useSuspenseInfiniteQuery

URL: /docs/react-query/useSuspenseInfiniteQuery

# useSuspenseInfiniteQuery

> **Warning:** **Deprecated in @suspensive/react-query**
> 
> This hook is now officially supported in TanStack Query v4.40.0+. Since TanStack Query has backported this interface, we are deprecating the backported version from @suspensive/react-query. Please migrate to the official TanStack Query interface:
> 
> ```diff
- import { useSuspenseInfiniteQuery } from '@suspensive/react-query'
+ import { useSuspenseInfiniteQuery } from '@tanstack/react-query'
```
> 
> For more details, see [TanStack Query PR #9334](https://github.com/TanStack/query/pull/9334).

Return type of this hook has no isLoading, isError property. because `<Suspense/>` and `<ErrorBoundary/>` guarantee the data from this hook. In addition, this hook's options have default suspense: true, and you can provide new options to this hook like [useInfiniteQuery](https://tanstack.com/query/v4/docs/react/reference/useInfiniteQuery) of @tanstack/react-query.

```tsx /useSuspenseInfiniteQuery/
import { useSuspenseInfiniteQuery } from '@suspensive/react-query'

const Example = () => {
  const query = useSuspenseInfiniteQuery({
    queryKey,
    queryFn,
  }) // suspense:true is default.

// No need to do type narrowing by isSuccess.
  query.data // InfiniteData<TData>
}
```

### Motivation

If you turn suspense on in @tanstack/react-query, You can use [useInfiniteQuery](https://tanstack.com/query/v4/docs/react/reference/useInfiniteQuery) with `<Suspense/>` and `<ErrorBoundary/>`.

```tsx /useInfiniteQuery/
import { useInfiniteQuery } from '@tanstack/react-query'

const Example = () => {
  const query = useInfiniteQuery({
    queryKey,
    queryFn,
    suspense: true,
  })

query.data // InfiniteData<TData> | undefined

if (query.isSuccess) {
    query.data // InfiniteData<TData>
  }
}
```

but useInfiniteQuery's return type query.data will always be fulfilled because of `<Suspense/>` as parent of this component.

This is why @suspensive/react-query provide **useSuspenseInfiniteQuery**.

> **Note:** Focus on successful cases.
> 
> Now we can focus on the component, as data fetching will always succeed.

### Version History

| Version  | Changes                                                                                                                                   |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `v3.0.0` | `networkMode` has been fixed to `'always'`. For more details, please refer to the [Migration to v3 guide](./migration/migrate-to-v3.mdx). |

---

## Migrating to v2

URL: /docs/react-query/migration/migrate-to-v2

# Migrating to v2

@suspensive/react-query v1 was originally [added as one of TanStack Query's community resources](https://tanstack.com/query/v4/docs/framework/react/community/suspensive-react-query) and was a library that provided `useSuspenseQuery`, `useSuspenseQueries` and `useSuspenseInfiniteQuery` to users of @tanstack/react-query v4.
Afterwards, [as `useSuspenseQuery`, `useSuspenseQueries`, and `useSuspenseInfiniteQuery` were officially added to @tanstack/react-query v5](https://github.com/TanStack/query/pull/5739) with changes interfaces such as enabled disappeared and queryOptions were received as one.
Therefore **we made the interface of @suspensive/react-query v2 as similar to the official interface as possible to make it easier for existing users of @suspensive/react-query v1 to migrate to @tanstack/react-query v5**.

However, because of [the higher browser specifications (class private fields) required by @tanstack/react-query v5](https://tanstack.com/query/v5/docs/framework/react/installation#requirements), @tanstack/react-query v4 is still useful to many teams.
Therefore, we will maintain support for @tanstack/react-query v4.

## What's new

### New `<SuspenseQuery/>`, `<SuspenseInfiniteQuery/>` [#775](https://github.com/toss/suspensive/pull/775)

Because the existing useSuspenseQuery is a hook, it creates components with names such as AuthorInfo and PostList to place Suspense and ErrorBoundary on the parent.
This makes it difficult to predict what suspense and errors will be thrown inside AuthorInfo and PostList.

#### Motivation: Want to expose that suspense occurs in child components.

```jsx
// posts/page.tsx
import { Suspense, ErrorBoundary } from '@suspensive/react'
import { AuthorInfo } from './components/AuthorInfo'
import { PostList } from './components/PostList'

const PostsPage = ({ userId }) => (
  <ErrorBoundary fallback={({ error }) => <>{error.message}</>}>
    <Suspense fallback={'loading...'}>
      <AuthorInfo userId={userId} />
      {/* It is difficult to predict whether a suspension will occur internally. */}
      <PostList userId={userId} />
      {/* It is difficult to predict whether a suspension will occur internally. */}
    </Suspense>
  </ErrorBoundary>
)
```

```jsx
// posts/components/AuthorInfo.tsx
import { useSuspenseQuery } from '@suspensive/react-query'
import { AuthorProfile } from '~/components'

// From the perspective of using this component, it is impossible to predict whether Suspense will occur internally just by the name AuthorInfo.
const AuthorInfo = ({ userId }) => {
  // We need to create this component just for data-fetching.
  const { data: author } = useSuspenseQuery(userQueryOptions(userId))

return <AuthorProfile {...author} />
}
```

```jsx
// posts/components/PostList.tsx
import { useSuspenseQuery } from '@suspensive/react-query'
import { PostListItem } from '~/components'

// From the perspective of using this component, it is impossible to predict whether a suspense will occur internally based on the name PostList alone.
const PostList = ({ userId }) => {
  // We need to create this component just for data-fetching.
  const { data: posts } = useSuspenseQuery({
    ...postsQueryOptions(userId),
    select: (posts) => posts.filter(({ isShow }) => isShow),
  })

return (
    <>
      {posts.map((post) => (
        <PostListItem {...post} />
      ))}
    </>
  )
}
```

#### Solution: Let's reveal that suspense occurs with `<SuspenseQuery/>`

Therefore, we provide these components to clearly express what causes suspension at the same depth.

1. Prop-drilling resulting from removing depth such as AuthorInfo and PostList for data-fetching only is also removed.
2. Changing the range of Suspense and ErrorBoundary becomes simple. Parallel processing of queries is also easier.
3. Because it manages all data-fetching within the Page component, the internal components are presentational, so it is easy to separate the components.

```jsx
import { SuspenseQuery } from '@suspensive/react-query'
import { Suspense, ErrorBoundary } from '@suspensive/react'
import { PostListItem, AuthorProfile } from '~/components'

const PostsPage = ({ authorId }) => (
  <ErrorBoundary fallback={({ error }) => <>{error.message}</>}>
    <Suspense fallback={'loading...'}>
      <SuspenseQuery {...userQueryOptions(authorId)}>
        {({ data: author }) => <AuthorProfile {...author} />}
      </SuspenseQuery>
      <SuspenseQuery
        {...postsQueryOptions(authorId)}
        select={(posts) => posts.filter(({ isShow }) => isShow)}
      >
        {({ data: posts }) => posts.map((post) => <PostListItem {...post} />)}
      </SuspenseQuery>
    </Suspense>
  </ErrorBoundary>
)
```

### New `queryOptions` [#828](https://github.com/toss/suspensive/pull/828)

// No need to create custom query hooks.
// You can use queryOptions directly in useQuery, useQueries, useSuspenseQuery, useSuspenseQueries, SuspenseQuery.
const post1Query = useQuery(postQueryOptions(1))
const { data: post1 } = useSuspenseQuery({
   ...postQueryOptions(1),
   refetchInterval: 2000, // Extensibility is clearly expressed in usage.
})
const [post1Query, post2Query] = useQueries({
   queries: [postQueryOptions(1), { ...postQueryOptions(2), refetchInterval: 2000 }],
})
const [{ data: post1 }, { data: post2 }] = useSuspenseQueries({
   queries: [postQueryOptions(1), { ...postQueryOptions(2), refetchInterval: 2000 }],
})
const Example = () => (
  <SuspenseQuery {...postQueryOptions(1)}>
    {({ data: post1 }) => <>{post1.text}</>}
  </SuspenseQuery>
);

```

## Handling BREAKING CHANGES

### Removed `enabled`, `placeholderData` option of `useSuspenseQuery`

```diff
import { useSuspenseQuery } from '@suspensive/react-query'

const Example = () => {
  const query = useSuspenseQuery({
    queryKey: ['key'],
    queryFn: () => api.text()
-   enabled: Math.random() > 0.5,
-   placeholderData: 'placeholder'
  })
}
```

### Removed `enabled`, `placeholderData` option of `useSuspenseInfiniteQuery`

```diff
import { useSuspenseInfiniteQuery } from '@suspensive/react-query'

const Example = () => {
  const infiniteQuery = useSuspenseInfiniteQuery({
    queryKey: ['key'],
    queryFn: () => api.text()
-   enabled: Math.random() > 0.5,
-   placeholderData: 'placeholder'
  })
}
```

### Unified interface naming for options and return type of `useSuspenseQuery` same with @tanstack/react-query v5's useSuspenseQuery

```diff filename="index.ts of @suspensive/react-query"
export { useSuspenseQuery } from './useSuspenseQuery'
export type {
- BaseUseSuspenseQueryResult,
  UseSuspenseQueryOptions,
- UseSuspenseQueryResultOnLoading,
- UseSuspenseQueryResultOnSuccess,
+ UseSuspenseQueryResult
} from './useSuspenseQuery'
export { useSuspenseQueries } from './useSuspenseQueries'
+ export type { SuspenseQueriesOptions, SuspenseQueriesResults } from './useSuspenseQueries'
export { useSuspenseInfiniteQuery } from './useSuspenseInfiniteQuery'
export type {
- BaseUseSuspenseInfiniteQueryResult,
  UseSuspenseInfiniteQueryOptions,
- UseSuspenseInfiniteQueryResultOnLoading,
- UseSuspenseInfiniteQueryResultOnSuccess,
+ UseSuspenseInfiniteQueryResult
} from './useSuspenseInfiniteQuery'
- export { QueryAsyncBoundary } from './QueryAsyncBoundary'
export { QueryErrorBoundary } from './QueryErrorBoundary'
```

---

## Migrating to v3

URL: /docs/react-query/migration/migrate-to-v3

# Migrating to v3

## What's new

### New `mutationOptions` [#1490](https://github.com/toss/suspensive/pull/1490)

`mutationOptions` helps you easily reuse and consistently manage option objects for Mutations. This provides similar benefits to the ones offered by [`queryOptions`](/docs/react-query/queryOptions).

```jsx /mutationOptions/
import { mutationOptions, useMutation, Mutation } from '@suspensive/react-query'

// You can directly use mutationOptions without creating custom mutation hooks.
const editPostMutation = useMutation(editPostMutationOptions(1))

## Handling BREAKING CHANGES

### `networkMode` is now fixed to `'always'` in `useSuspenseQuery`, `useSuspenseQueries`, `useSuspenseInfiniteQuery` of `@suspensive/react-query` [#1458](https://github.com/toss/suspensive/pull/1458)

> **Info:** This breaking change affects users who use both `@tanstack/react-query` v4 and `@suspensive/react-query`.

Previously, online status was determined using the `navigator.onLine` API. However, Chromium-based browsers have a known issue where this API may return incorrect values, falsely reporting the device as offline even when it is connected.  
To ensure consistent behavior across all environments, `@suspensive/react-query` now sets the default `networkMode` to `'always'` when using Suspense hooks.

This change aligns with the default behavior in React Query v5 and prevents Suspense hooks from starting with `fetchStatus: 'paused'` during runtime.

- Reference: [Default networkMode configuration and fetchStatus = "paused"](https://github.com/TanStack/query/discussions/4753), [navigator.onLine returning false value even network is available](https://issues.chromium.org/issues/338514113)

```diff
import { queryOptions, useSuspenseQuery } from '@suspensive/react-query'

// Applies the same to queryOptions and infiniteQueryOptions as well.
const QueryOptionsExample = () => {
  const options = queryOptions({
    queryKey: ['key'],
    queryFn: () => api()
-   networkMode: 'always'
  })
}

// Applies the same to useSuspenseQuery, useSuspenseInfiniteQuery, SuspenseQuery, and SuspenseInfiniteQuery.
const SuspenseQueryExample = () => {
  const query = useSuspenseQuery({
    queryKey: ['key'],
    queryFn: () => api()
-   networkMode: 'always'
  })
}
```

### `<QueryErrorBoundary/>` is removed [#1424](https://github.com/toss/suspensive/pull/1424)

In `@suspensive/react-query` v2, `QueryErrorBoundary` was provided as a peer dependency of `@suspensive/react`.
However, this approach complicated user dependencies for the sake of a simple implementation.
Therefore, it has been removed to simplify the library.

You can implement your own `QueryErrorBoundary` as shown below.

```diff
- import { QueryErrorBoundary } from '@suspensive/react-query'
+ import { ErrorBoundary } from '@suspensive/react'
+ import { useQueryErrorResetBoundary } from '@tanstack/react-query'
+ import {
+   type ComponentPropsWithoutRef,
+   type ComponentRef,
+   forwardRef,
+ } from 'react'

+ const QueryErrorBoundary = forwardRef<
+   ComponentRef<typeof ErrorBoundary>,
+   ComponentPropsWithoutRef<typeof ErrorBoundary>
+ >(({ onReset, ...props }, resetRef) => {
+   const { reset } = useQueryErrorResetBoundary()
+   return (
+     <ErrorBoundary
+       {...props}
+       onReset={() => {
+         onReset?.()
+         reset()
+       }}
+       ref={resetRef}
+     />
+   )
+ })

const Example = () => (
  <QueryErrorBoundary>
    <SuspenseQuery />
  </QueryErrorBoundary>
)
```

---

## Motivation

URL: /docs/jotai/motivation

# Motivation

Jotai's async atoms work with Suspense, but hooks hide which atoms trigger Suspense and where. @suspensive/jotai makes this visible.

### Hooks hide what triggers Suspense

When a child component uses `useAtom` with an async atom, the parent has no way to tell which children will suspend. Suspense boundaries become guesswork.

```tsx
const PaymentPage = () => (
  <Suspense fallback={'pending...'}>
    {/* Does UserInfo suspend? Which atom? No way to tell from here. */}
    <UserInfo />
    <ShoppingCart />
  </Suspense>
)
```

With Suspensive's [`<Atom/>`](/docs/jotai/Atom), [`<AtomValue/>`](/docs/jotai/AtomValue), and [`<SetAtom/>`](/docs/jotai/SetAtom), atom usage is declared right in JSX — you can see exactly what suspends and where.

```tsx
const PaymentPage = () => (
  <Suspense fallback={'pending...'}>
    {/* Clear: userAtom triggers Suspense here. */}
    <Atom atom={userAtom}>{([data]) => <UserProfile {...data} />}</Atom>
    <Atom atom={cartAtom}>{([data]) => <ShoppingCart {...data} />}</Atom>
  </Suspense>
)
```

### Works with Jotai's extension ecosystem

Jotai has extensions like [tRPC](https://jotai.org/docs/extensions/trpc), [Query](https://jotai.org/docs/extensions/query), and [Cache](https://jotai.org/docs/extensions/cache). With Suspensive's `<Atom/>`, `<AtomValue/>`, and `<SetAtom/>`, atoms from these extensions work out of the box — no extra wrappers needed.

```tsx
import { AtomValue } from '@suspensive/jotai'
import { Suspense, ErrorBoundary } from '@suspensive/react'
import { userQueryAtom } from '~/queries' // atomWithSuspenseQuery from jotai-tanstack-query

const MyPage = () => (
  <ErrorBoundary fallback={({ error }) => <>{error.message}</>}>
    <Suspense fallback={'pending...'}>
      <AtomValue atom={userQueryAtom}>
        {({ data: user }) => <UserProfile key={user.id} {...user} />}
      </AtomValue>
    </Suspense>
  </ErrorBoundary>
)
```

---

## Installation

URL: /docs/jotai/installation

# Installation

### Check supported browsers

Suspensive Libraries are optimized for modern browsers. It is compatible with the following browsers config.

<br />

<tbody>
    {[
      { browser: 'Chrome', version: '>= 51' },
      { browser: 'Firefox', version: '>= 53' },
      { browser: 'Edge', version: '>= 18' },
      { browser: 'Safari', version: '>= 11' },
      { browser: 'iOS', version: '>= 11' },
      { browser: 'Opera', version: '>= 38' },
    ].map((item) => (
      
        {item.browser}
        {item.version}
      
    ))}
  </tbody>

> Depending on your environment, you might need to add polyfills. If you want to support older browsers, you need to transpile the library from node_modules yourselves.

### Check supported react, jotai version

<br />

<tbody>
    {[
      { library: 'react', version: '^18 || ^19' },
      { library: 'jotai', version: '^2' },
    ].map((item) => (
      
        {item.library}
        {item.version}
      
    ))}
  </tbody>

### Add as Dependencies

@suspensive/jotai lives in npm. To install the latest stable version, run the following command.

```shell npm2yarn
npm install @suspensive/jotai
```

---

## Atom

URL: /docs/jotai/Atom

# Atom

The Atom component provides an interface similar to Jotai's [useAtom](https://jotai.org/docs/core/use-atom#useatom) hook as props, allowing declarative usage.

### props.atom

You can use Jotai's atom as is.

```tsx /Atom/
import { Atom } from '@suspensive/jotai'
import { atom } from 'jotai'

const countAtom = atom(1)

const Example = () => (
  <Atom atom={countAtom}>
    {([count, setCount]) => (
      <>
        <div>count: {count}</div>
        <button onClick={() => setCount(count + 1)}>+1</button>
      </>
    )}
  </Atom>
)
```

For Async Atom, it delegates the pending state of the Promise to the parent Suspense until the Promise resolves.

```tsx /Atom/
import { Atom } from '@suspensive/jotai'
import { Suspense } from '@suspensive/react'
import { atom } from 'jotai'

const countAtom = atom(1)
const asyncDoubleCountAtom = atom(async (get) => {
  await delay(2000)
  return get(countAtom) * 2
})

const Example = () => (
  <Suspense fallback={'pending...'}>
    <Atom atom={asyncDoubleCountAtom}>{([count]) => <>count: {count}</>}</Atom>
  </Suspense>
)
```

### Motivation

It's not immediately clear from the parent component which atoms are used internally in the child components and whether they trigger Suspense.

```tsx
// payment/page.tsx
import { Suspense } from '@suspensive/react'
import { UserInfo, ShoppingCart } from '~/components'

const PaymentPage = () => (
  <Suspense fallback={'pending...'}>
    {/* It's not clear whether UserInfo internally triggers Suspense with an Async Atom. */}
    <UserInfo />
    {/* It's not clear whether ShoppingCart internally triggers Suspense with an Async Atom. */}
    <ShoppingCart />
  </Suspense>
)
```

```tsx
// payment/components/UserInfo.tsx
import { useAtomValue } from '@suspensive/jotai'
import { UserAddress } from '~/components'
import { userAsyncAtom } from '~/atoms'

// It's not clear from the usage of this component what Atom UserInfo uses internally and whether it triggers Suspense.
const UserInfo = () => {
  const data = useAtomValue(userAsyncAtom)

return <UserAddress {...data} />
}
```

```tsx
// payment/components/ShoppingCart.tsx
import { useAtom } from 'jotai'
import { ShoppingItem } from '~/components'
import { shoppingCartAtom } from '~/atoms'

// It's not clear from the usage of this component what Atom ShoppingCart uses internally and whether it triggers Suspense.
const ShoppingCart = () => {
  const [data] = useAtom(shoppingCartAtom)

return (
    <>
      {data.map((item) => (
        <ShoppingItem key={item.id} {...item} />
      ))}
    </>
  )
}
```

---

## AtomValue

URL: /docs/jotai/AtomValue

# AtomValue

The AtomValue component provides an interface similar to Jotai's [useAtomValue](https://jotai.org/docs/core/use-atom#useatomvalue) hook as props, allowing declarative usage.

### props.atom

You can use Jotai's atom as is.

```tsx /AtomValue/
import { AtomValue } from '@suspensive/jotai'
import { atom } from 'jotai'

const countAtom = atom(1)

const Example = () => {
  return (
    <AtomValue atom={countAtom}>{(count) => <>count: {count}</>}</AtomValue>
  )
}
```

For Async Atom, it delegates the pending state of the Promise to the parent Suspense until the Promise resolves.

```tsx /AtomValue/
import { AtomValue } from '@suspensive/jotai'
import { Suspense } from '@suspensive/react'
import { atom } from 'jotai'

const countAtom = atom(1)
const asyncDoubleCountAtom = atom(async (get) => {
  await delay(2000)
  return get(countAtom) * 2
})

const Example = () => (
  <Suspense fallback={'pending...'}>
    <AtomValue atom={asyncDoubleCountAtom}>
      {(count) => <>count: {count}</>}
    </AtomValue>
  </Suspense>
)
```

### Motivation

Similar to [`<Atom/>`](https://suspensive.org/docs/jotai/Atom), `<AtomValue/>` also does not clearly reveal which atoms are used internally in child components and whether they trigger Suspense.

---

## SetAtom

URL: /docs/jotai/SetAtom

# SetAtom

The SetAtom component provides an interface similar to Jotai's [useSetAtom](https://jotai.org/docs/core/use-atom#usesetatom) hook as props, allowing declarative usage.

### props.atom

You can use Jotai's atom as is.

```tsx /SetAtom/
import { SetAtom } from '@suspensive/jotai'
import { atom } from 'jotai'

const switchAtom = atom(false)

const Example = () => (
  <SetAtom atom={switchAtom}>
    {(setCount) => (
      <>
        <button onClick={() => setCount(true)}>Set True</button>
        <button onClick={() => setCount(false)}>Set False</button>
      </>
    )}
  </SetAtom>
)
```

For Async Atom, it delegates the pending state of the Promise to the parent Suspense until the Promise resolves.

```tsx /SetAtom/
import { SetAtom } from '@suspensive/jotai'
import { Suspense } from '@suspensive/react'
import { atom } from 'jotai'

const request = async () => fetch('https://...').then((res) => res.json())
const baseAtom = atom(0)

const Example = () => (
  <Suspense fallback={'pending...'}>
    <SetAtom atom={baseAtom}>
      {(setValue) => (
        <>
          {/* Suspense will be triggered until the Promise resolves. */}
          <button onClick={() => setValue(request())}>request</button>
        </>
      )}
    </SetAtom>
  </Suspense>
)
```

### Motivation

Similar to [`<Atom/>`](https://suspensive.org/docs/jotai/Atom), `<SetAtom/>` also does not clearly reveal which atoms are used internally in child components and whether they trigger Suspense.

---

## Motivation

URL: /docs/codemods/motivation

# Motivation

Codemods are powerful tools that automate repetitive and large-scale tasks within a codebase, making code updates more efficient. They allow for fast and safe updates without the need to manually review numerous changes.

Suspensive provides codemods to help manage API updates and deprecated APIs seamlessly.

### Handle Large-Scale API Changes Quickly and Easily

Projects using Suspensive packages often have these packages utilized globally across the codebase. Manually locating and modifying all usages is not only time-consuming but also prone to errors.

```bash filename="Terminal"
npx @suspensive/codemods
✔ Which transform would you like to apply? > tanstack-query-import
✔ On which files or directory should the codemods be applied? … .
Processing 130 files...
Spawning 10 workers...
Sending 13 files to free worker...
Sending 13 files to free worker...
...
All done.
Results:
0 errors
31 unmodified
0 skipped
99 ok
Time elapsed: 2.980 seconds
```

The log above shows the result of running the [`tanstack-query-import`](/docs/codemods/tanstackQueryImport) codemod to automatically migrate the deprecated `@suspensive/react-query` API to `@tanstack/react-query` v5 in a `@suspensive/react-query` & `@tanstack/react-query` environment. Out of 130 files, 99 were transformed in just 2.980 seconds.

## Update Suspensive Packages Easily and Safely

Major updates to packages often introduce breaking changes that complicate code migration. Suspensive plans to thoroughly support these breaking changes through codemod, making management simpler. By using codemods, you can upgrade to new versions and features quickly and securely.

---

## Usage

URL: /docs/codemods/usage

# Usage

You can run Suspensive's Codemods with a single command, easily using npx without the need to install it as a dependency.

Navigate to your project folder in the terminal and run the following command.

```bash filename="Terminal"
npx @suspensive/codemods <transform> <path>
```

Adjust `<transform>` and `<path>` to match the environment where you want to apply the codemod.

- `<transform>`: name of transform
- `<path>`: files or directory to transform

You can use the following options.

- `--dry`: Output the transformation result without modifying the file.
- `--print`: Output the transformation result to the console.

---

## Migrate TanStack Query imports

URL: /docs/codemods/tanstackQueryImport

# Migrate TanStack Query imports

> **Info:** - We recommend upgrading to `@tanstack/react-query@5` when using `@suspensive/react-query` with `@tanstack/react-query@4`.
> - Starting from `@suspensive/react-query-4@3.3.0`, `queryOptions`, `infiniteQueryOption`, `useSuspenseQuery`, and `useSuspenseQueries` have been deprecated. (`@tanstack/react-query@4.40.0` officially supports `useSuspenseQuery` and `queryOptions`.)

Any API in `@suspensive/react-query` that is officially provided by `@tanstack/react-query` will be marked as `deprecated`.  
This is because `@suspensive/react-query` offers the same APIs such as Suspense Hooks and `queryOptions`/`infiniteQueryOption`, and we want to encourage developers to use the official `@tanstack/react-query` APIs first.

```bash filename="Terminal"
npx @suspensive/codemods tanstack-query-import .
```

This codemod automatically transforms import paths from `@suspensive/react-query` to `@tanstack/react-query`.

For example:

```tsx /@suspensive/
import { queryOptions } from '@suspensive/react-query'
import { useSuspenseQuery } from '@suspensive/react-query-5' // The versioned package is also transformed!
```

Transforms into:

```tsx /@tanstack/
import { queryOptions } from '@tanstack/react-query'
import { useSuspenseQuery } from '@tanstack/react-query'
```

---

## Migrate `<QueryClientConsumer/>` Props

URL: /docs/codemods/migrateQueryClientConsumerProps

# Migrate `<QueryClientConsumer/>` Props

> **Info:** This codemod is recommended for updating `@suspensive/react-query` & `@tanstack/react-query@4` to `@tanstack/react-query@5`.

In the `@suspensive/react-query` & `@tanstack/react-query@5` environment, the `context` prop of the `<QueryClientConsumer/>` component provided by `@suspensive/react-query` has been changed to `queryClient`.

```bash filename="Terminal"
npx @suspensive/codemods migrate-query-client-consumer-props .
```

Using this codemod, you can automatically transform the `context` prop into `queryClient`.

For example:

```tsx /context/
const PostRefreshButton = () => {
  return (
    <QueryClientConsumer context={queryClientContext}>
      {(queryClient) => (
        <button
          onClick={() =>
            queryClient.invalidateQueries({
              queryKey: ['posts'],
            })
          }
        >
          Posts refresh
        </button>
      )}
    </QueryClientConsumer>
  )
}
```

Transforms into:

```tsx /queryClient/
const PostRefreshButton = () => {
  return (
    {/** The 'context' prop is now transformed into 'queryClient'! */}
    <QueryClientConsumer queryClient={queryClient}>
      {(queryClient) => (
        <button
          onClick={() =>
            queryClient.invalidateQueries({
              queryKey: ['posts'],
            })
          }
        >
          Posts refresh
        </button>
      )}
    </QueryClientConsumer>
  )
}
```

---

## Migrate `with` API

URL: /docs/codemods/migrateWithAPI

# Migrate `with` API

> **Info:** This codemod is recommended when upgrading `@suspensive/react` from v2 to v3.

In `@suspensive/react` v3, the `wrap` API has been removed and replaced with the new `with` API, which is provided on each component such as `<ErrorBoundaryGroup/>`, `<ErrorBoundary/>`, and `<Suspense/>`.

For full details on the breaking changes that this codemod helps with, refer to [Migrating to v3](/docs/react/migration/migrate-to-v3).

```bash filename="Terminal"
npx @suspensive/codemods migrate-with-api .
```

This codemod automatically transforms the `wrap` builder pattern into the new `with` API on each component.

For example:

```tsx /wrap/
import { wrap } from '@suspensive/react'

const Example = wrap
  .ErrorBoundaryGroup({ blockOutside: false })
  .ErrorBoundary({
    fallback: ({ error }) => <>{error.message}</>,
    onError: logger.log,
  })
  .Suspense({ fallback: <>loading...</>, clientOnly: true })
  .on(() => {
    return <>Example</>
  })
```

Transforms into:

```tsx /with/
import { ErrorBoundaryGroup, ErrorBoundary, Suspense } from '@suspensive/react'
import { useSuspenseQuery } from '@suspensive/react-query'

const Example = ErrorBoundaryGroup.with(
  { blockOutside: false },
  ErrorBoundary.with(
    {
      fallback: ({ error }) => <>{error.message}</>,
      onError: logger.log,
    },
    Suspense.with({ fallback: <>loading...</>, clientOnly: true }, () => {
      return <>Example</>
    })
  )
)
```

---

## Remove `networkMode`

URL: /docs/codemods/removeNetworkmode

# Remove `networkMode`

> **Info:** We recommend running this when upgrading from `@suspensive/react-query` v2 & `@tanstack/react-query@4` to `@suspensive/react-query` v3.

In `@suspensive/react-query` v3, the Suspense API has `networkMode` hardcoded as `'always'` and it can no longer be modified.

For full details on the breaking changes that this codemod helps with, refer to [Migrating to v3](/docs/react-query/migration/migrate-to-v3).

```bash filename="Terminal"
npx @suspensive/codemods remove-networkmode .
```

This codemod safely and easily removes unnecessary `networkMode` properties from Suspense API usage.

For example:

```tsx /networkMode/
import { queryOptions } from '@tanstack/react-query'

const options = queryOptions({
  queryKey: ['key'],
  queryFn: () => Promise.resolve('data'),
  networkMode: 'always',
})
```

Transforms into:

```tsx /networkMode/
import { queryOptions } from '@tanstack/react-query'

const options = queryOptions({
  queryKey: ['key'],
  queryFn: () => Promise.resolve('data'),
})
```

---

## Migrating to Suspensive v3

URL: /docs/migration/migrate-to-v3

# Migrating to Suspensive v3

Suspensive v3 introduces several important changes to improve stability and add new features.

### Stabilized experimental Suspensive packages

- [@suspensive/jotai](../jotai/motivation)
- [@suspensive/codemods](../codemods/motivation) - [#1461](https://github.com/toss/suspensive/pull/1461)

### Prevent infinite loop when an error occurs in the ErrorBoundary fallback

The way errors are handled in the `fallback` of `ErrorBoundary` in @suspensive/react has changed. [#1409](https://github.com/toss/suspensive/pull/1409)

### Removed peerDependency of @suspensive/react-query

We no longer depend on @suspensive/react as a peerDependency. It was only used to provide `QueryErrorBoundary`.
This simplifies the usage of @suspensive/react-query, ensuring that users do not need to use any additional libraries other than @tanstack/react-query. [#1434](https://github.com/toss/suspensive/pull/1434)

### Migration guide

## Thanks to all Suspensive contributors

We were able to release v3 because of Suspensive's contributors. Thank you to everyone who worked together to make it a better library, and we look forward to your continued support.

[![contributors](https://contrib.rocks/image?repo=toss/suspensive)](https://github.com/toss/suspensive/graphs/contributors)

---

## Migrating to Suspensive v2

URL: /docs/migration/migrate-to-v2

# Migrating to Suspensive v2

Suspensive v2, **we focused on increasing compatibility and improving DX**.
To accomplish this, we had to introduce some dramatic changes. As a result, we removed some previously deprecated features and added some new interfaces.

### The minimum required React version is now 18.0

**Suspensive v2 requires React 18.0 or later.** This is because we are using the new useSyncExternalStore hook, which is only available in React 18.0 and later. Previously, we have been using the shim provided by React(use-sync-external-store).
In addition, in React 18, [Suspense-related features were added](https://legacy.reactjs.org/blog/2022/03/29/react-v18.html), We decided that the direction of the Suspensive libraries needed to focus on React 18 or higher in the future rather than responding to Legacy React.

### Key Features

- **React 18+ support**: [#629](https://github.com/toss/suspensive/pull/629) - Updated to use React 18 native APIs
- **New queryOptions**: [#828](https://github.com/toss/suspensive/pull/828) - Added queryOptions for better type safety and query management
- **Suspense clientOnly prop**: [#521](https://github.com/toss/suspensive/pull/521) - Added clientOnly prop to replace Suspense.CSROnly
- **DevMode for development**: [#470](https://github.com/toss/suspensive/pull/470) - Added DevMode for better debugging experience
- **Improved browser support**: [#455](https://github.com/toss/suspensive/pull/455) - Added support for wider range of browsers
- **Naming convention updates**: [#401](https://github.com/toss/suspensive/pull/401) - Aligned naming with TanStack Query v5 conventions
- **AsyncBoundary deprecation**: [#345](https://github.com/toss/suspensive/pull/345) - Deprecated AsyncBoundary for cleaner API design

### Migration guide

## Thanks to all Suspensive contributors

We were able to release v2 because of Suspensive's contributors. Thank you to everyone who worked together to make it a better library, and we look forward to your continued support.

[![contributors](https://contrib.rocks/image?repo=toss/suspensive)](https://github.com/toss/suspensive/graphs/contributors)

---

## Changelogs

URL: /docs/changelogs

# Changelogs

---

## Contributors

URL: /docs/contributors

# Contributors

Thank you to everyone who contributed to Suspensive and we look forward to your continued support.

## Maintainers

}
    title="@manudeli (Jonghyeon Ko)"
    href="https://github.com/manudeli"
  />
  
    }
    title="@gwansikk (Gwansik Kim)"
    href="https://github.com/gwansikk"
  />
  
    }
    title="@kangju2000 (Juhyeok Kang)"
    href="https://github.com/kangju2000"
  />
  
    }
    title="@marshallku (Marshall Ku)"
    href="https://github.com/marshallku"
  />
  
    }
    title="Who's next?"
    href="https://github.com/toss/suspensive"
  />

### Former maintainers

}
    title="@okinawaa (Chanhyuk Park)"
    href="https://github.com/okinawaa"
  />
  
    }
    title="@minsoo-web (Minsoo Kim)"
    href="https://github.com/minsoo-web"
  />
  
    }
    title="@bigsaigon333 (Donghee Kim)"
    href="https://github.com/bigsaigon333"
  />
  
    }
    title="@SEOKKAMONI (Seokjin Kim)"
    href="https://github.com/SEOKKAMONI"
  />

---

## Related Links

URL: /docs/links

# Related Links

- [React 18 keynote](https://youtu.be/FZ0cG47msEk?t=408)
- [[Umbrella] Releasing Suspense in facebook/react](https://github.com/facebook/react/issues/13206)
- [Suspense for Data Fetching (Experimental) in react docs for version 17](https://17.reactjs.org/docs/concurrent-mode-suspense.html)
- [Pull Request to add `<ErrorBoundaryGroup/>` in @toss/error-boundary](https://github.com/toss/slash/pull/157)
- [Pull Request to fix useSuspendedQuery in @toss/react-query wrapping react-query v3](https://github.com/toss/slash/pull/73)
- [Pull Request to remove error-boundary's difficulty because of type of reset's args](https://github.com/toss/slash/pull/178)
- [Dan Abramov: Beyond React 16 | JSConf Iceland](https://youtu.be/nLF0n9SACd4)