TanStack Query Devtools 教學：用視覺化工具看懂 Query、Cache 與 Mutation

npm i @tanstack/react-query-devtools

pnpm add @tanstack/react-query-devtools

yarn add @tanstack/react-query-devtools

bun add @tanstack/react-query-devtools

pnpm add -D @tanstack/react-query-devtools

'use client'

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { useState } from 'react'

export default function QueryProvider({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient())

  return (
    <QueryClientProvider client={queryClient}>
      {children}

      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

// In Next.js, this file would be called: app/providers.tsx
'use client'

// Since QueryClientProvider relies on useContext under the hood, we have to put 'use client' on top
import {
  environmentManager,
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        // With SSR, we usually want to set some default staleTime
        // above 0 to avoid refetching immediately on the client
        staleTime: 60 * 1000,
      },
    },
  })
}

let browserQueryClient: QueryClient | undefined = undefined

function getQueryClient() {
  if (environmentManager.isServer()) {
    // Server: always make a new query client
    return makeQueryClient()
  } else {
    // Browser: make a new query client if we don't already have one
    // This is very important, so we don't re-make a new client if React
    // suspends during the initial render. This may not be needed if we
    // have a suspense boundary BELOW the creation of the query client
    if (!browserQueryClient) browserQueryClient = makeQueryClient()
    return browserQueryClient
  }
}

export default function QueryProvider({ children }: { children: React.ReactNode }) {
  // NOTE: Avoid useState when initializing the query client if you don't
  //       have a suspense boundary between this and the code that may
  //       suspend because React will throw away the client on the initial
  //       render if it suspends and there is no boundary
  const queryClient = getQueryClient()

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

// app/layout.tsx
import QueryProvider from './QueryProvider'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="zh-TW">
      <body>
        <QueryProvider>{children}</QueryProvider>
      </body>
    </html>
  )
}

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

type Post = {
  id: string
  title: string
}

async function fetchPosts(): Promise<Post[]> {
  const res = await fetch('/api/posts')

  if (!res.ok) {
    throw new Error('Failed to fetch posts')
  }

  return res.json()
}

export function PostList() {
  const { data, isPending, isError, error, isFetching } = useQuery({
    queryKey: ['posts'],
    queryFn: fetchPosts,
  })

  if (isPending) {
    return <p>Loading...</p>
  }

  if (isError) {
    return <p>{error.message}</p>
  }

  return (
    <div>
      {isFetching && <p>資料更新中...</p>}

      <ul>
        {data.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </div>
  )
}

['posts']

function usePost(postId: string) {
  return useQuery({
    queryKey: ['post', postId],
    queryFn: () => fetchPost(postId),
  })
}

['post', 'abc-123']
['post', 'def-456']

function usePost(postId: string) {
  return useQuery({
    queryKey: ['post'],
    queryFn: () => fetchPost(postId),
  })
}

if (isPending) {
  return <p>Loading...</p>
}

return (
  <>
    {isFetching && <p>資料更新中...</p>}
    <PostList data={data} />
  </>
)

useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  staleTime: 1000 * 60 * 5,
})

useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  gcTime: 1000 * 60 * 10,
})

import { useMutation, useQueryClient } from '@tanstack/react-query'

async function createPost(input: { title: string }) {
  const res = await fetch('/api/posts', {
    method: 'POST',
    body: JSON.stringify(input),
  })

  if (!res.ok) {
    throw new Error('Failed to create post')
  }

  return res.json()
}

export function CreatePostButton() {
  const queryClient = useQueryClient()

  const mutation = useMutation({
    mutationFn: createPost,
    onSuccess: () => {
      queryClient.invalidateQueries({
        queryKey: ['posts'],
      })
    },
  })

  return (
    <button
      onClick={() => {
        mutation.mutate({ title: 'TanStack Query Devtools 教學' })
      }}
    >
      新增文章
    </button>
  )
}

const createPostMutation = useMutation({
  mutationKey: ['posts', 'create'],
  mutationFn: createPost,
  onSuccess: () => {
    queryClient.invalidateQueries({
      queryKey: ['posts'],
    })
  },
})

const updatePostMutation = useMutation({
  mutationKey: ['posts', 'update'],
  mutationFn: updatePost,
  onSuccess: (_, variables) => {
    queryClient.invalidateQueries({
      queryKey: ['post', variables.postId],
    })

    queryClient.invalidateQueries({
      queryKey: ['posts'],
    })
  },
})

const deletePostMutation = useMutation({
  mutationKey: ['posts', 'delete'],
  mutationFn: deletePost,
  onSuccess: () => {
    queryClient.invalidateQueries({
      queryKey: ['posts'],
    })
  },
})

['posts', 'create']
['posts', 'update']
['posts', 'delete']

import { useMutationState } from '@tanstack/react-query'

const creatingPosts = useMutationState({
  filters: {
    mutationKey: ['posts', 'create'],
    status: 'pending',
  },
})

const isCreatingPost = creatingPosts.length > 0

return (
  <button disabled={isCreatingPost}>
    {isCreatingPost ? '新增中...' : '新增文章'}
  </button>
)

const mutation = useMutation({
  mutationKey: ['posts', 'create'],
  mutationFn: createPost,
  onSuccess: () => {
    queryClient.invalidateQueries({
      queryKey: ['posts'],
    })
  },
})

useQuery({
  queryKey: ['posts', { keyword, timestamp: Date.now() }],
  queryFn: fetchPosts,
})

useMutation({
  mutationFn: createPost,
})

useMutation({
  mutationFn: updatePost,
})

useMutation({
  mutationFn: deletePost,
})

useMutation({
  mutationKey: ['posts', 'create'],
  mutationFn: createPost,
})

useMutation({
  mutationKey: ['posts', 'update'],
  mutationFn: updatePost,
})

useMutation({
  mutationKey: ['posts', 'delete'],
  mutationFn: deletePost,
})

'use client'

import { useState } from 'react'
import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'

export function QueryDebugPanel() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <div>
      <button onClick={() => setIsOpen((prev) => !prev)}>
        {isOpen ? '關閉 Devtools' : '開啟 Devtools'}
      </button>

      {isOpen && (
        <ReactQueryDevtoolsPanel onClose={() => setIsOpen(false)} />
      )}
    </div>
  )
}