🧩 技術調査 - TanStack

// Query の型推論例: queryFn の戻り値型が data に自動伝播する
const { data } = useQuery({
  queryKey: ['user', id],
  queryFn: async (): Promise<User> => {
    const res = await fetch(`/api/users/${id}`)
    return res.json()
  },
})
// data の型は User | undefined と推論される

// Router の型推論例: パスパラメータが型チェックされる
<Link
  to="/users/$userId"
  params={{ userId: '123' }}  // userId: string が必須
/>

npm install @tanstack/react-query
# DevTools - 任意
npm install @tanstack/react-query-devtools

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

const queryClient = new QueryClient()

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

npm install @tanstack/react-table

import {
  useReactTable,
  getCoreRowModel,
  flexRender,
  ColumnDef,
} from '@tanstack/react-table'

const columns: ColumnDef<Person>[] = [
  { accessorKey: 'name', header: '名前' },
  { accessorKey: 'age', header: '年齢' },
]

function MyTable({ data }: { data: Person[] }) {
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
  })
  // テーブルの描画は table.getHeaderGroups() / table.getRowModel() を使用
}

npm install @tanstack/react-router
npm install -D @tanstack/router-plugin @tanstack/router-devtools

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { TanStackRouterVite } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    TanStackRouterVite({ autoCodeSplitting: true }),
    react(),
  ],
})

npx create-tsrouter-app my-app

npm install @tanstack/react-form

import { useForm } from '@tanstack/react-form'

function MyForm() {
  const form = useForm({
    defaultValues: { name: '', email: '' },
    onSubmit: async ({ value }) => {
      console.log(value)
    },
  })

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        form.handleSubmit()
      }}
    >
      <form.Field
        name="name"
        children={(field) => (
          <input
            value={field.state.value}
            onChange={(e) => field.handleChange(e.target.value)}
          />
        )}
      />
      <button type="submit">送信</button>
    </form>
  )
}

npm create @tanstack/start@latest
# または
pnpm create @tanstack/start@latest

npx gitpick TanStack/router/tree/main/examples/react/start-basic start-basic
cd start-basic && npm install && npm run dev

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

function UserList() {
  const { data, isPending, error } = useQuery({
    queryKey: ['users'],
    queryFn: () =>
      fetch('/api/users').then((res) => res.json()),
  })

  if (isPending) return <p>読み込み中...</p>
  if (error) return <p>エラー: {error.message}</p>

  return (
    <ul>
      {data.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  )
}

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

function AddUser() {
  const queryClient = useQueryClient()

  const mutation = useMutation({
    mutationFn: (newUser: { name: string }) =>
      fetch('/api/users', {
        method: 'POST',
        body: JSON.stringify(newUser),
      }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] })
    },
  })

  return (
    <button onClick={() => mutation.mutate({ name: 'New User' })}>
      ユーザーを追加
    </button>
  )
}

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

function InfiniteList() {
  const {
    data,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage,
  } = useInfiniteQuery({
    queryKey: ['items'],
    queryFn: ({ pageParam = 0 }) =>
      fetch(`/api/items?cursor=${pageParam}`).then((res) => res.json()),
    initialPageParam: 0,
    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
  })

  return (
    <div>
      {data?.pages.map((page) =>
        page.items.map((item) => <div key={item.id}>{item.name}</div>)
      )}
      <button
        onClick={() => fetchNextPage()}
        disabled={!hasNextPage || isFetchingNextPage}
      >
        {isFetchingNextPage ? '読み込み中...' : 'さらに読み込む'}
      </button>
    </div>
  )
}

const columns: ColumnDef<Person>[] = [
  {
    accessorKey: 'firstName',
    header: '名',
    cell: (info) => info.getValue(),
  },
  {
    accessorFn: (row) => `${row.firstName} ${row.lastName}`,
    id: 'fullName',
    header: 'フルネーム',
  },
]

import { getSortedRowModel } from '@tanstack/react-table'

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),
})

// ヘッダーの描画
<th
  onClick={header.column.getToggleSortingHandler()}
  style={{ cursor: 'pointer' }}
>
  {flexRender(header.column.columnDef.header, header.getContext())}
  {{ asc: ' ↑', desc: ' ↓' }[header.column.getIsSorted() as string] ?? ''}
</th>

import { getFilteredRowModel, ColumnFiltersState } from '@tanstack/react-table'

const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])

const table = useReactTable({
  data,
  columns,
  state: { columnFilters },
  onColumnFiltersChange: setColumnFilters,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
})

// フィルター入力
<input
  value={(table.getColumn('name')?.getFilterValue() as string) ?? ''}
  onChange={(e) => table.getColumn('name')?.setFilterValue(e.target.value)}
  placeholder="名前で検索"
/>

import { getPaginationRowModel, PaginationState } from '@tanstack/react-table'

const [pagination, setPagination] = useState<PaginationState>({
  pageIndex: 0,
  pageSize: 10,
})

const table = useReactTable({
  data,
  columns,
  state: { pagination },
  onPaginationChange: setPagination,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
})

// ページネーション UI
<div>
  <button onClick={() => table.firstPage()} disabled={!table.getCanPreviousPage()}>{'<<'}</button>
  <button onClick={() => table.previousPage()} disabled={!table.getCanPreviousPage()}>{'<'}</button>
  <button onClick={() => table.nextPage()} disabled={!table.getCanNextPage()}>{'>'}</button>
  <button onClick={() => table.lastPage()} disabled={!table.getCanNextPage()}>{'>>'}</button>
  <span>ページ {table.getState().pagination.pageIndex + 1} / {table.getPageCount()}</span>
</div>

// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: IndexPage,
})

function IndexPage() {
  return <h1>ホーム</h1>
}

import { Link } from '@tanstack/react-router'

function Navigation() {
  return (
    <nav>
      <Link to="/" activeProps={{ style: { fontWeight: 'bold' } }}>
        ホーム
      </Link>
      <Link to="/users/$userId" params={{ userId: '123' }}>
        ユーザー詳細
      </Link>
    </nav>
  )
}

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

// src/routes/users/$userId.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/users/$userId')({
  loader: async ({ params }) => {
    const res = await fetch(`/api/users/${params.userId}`)
    return res.json()
  },
  component: UserDetail,
})

function UserDetail() {
  const user = Route.useLoaderData()
  return <h1>{user.name}</h1>
}

import { useForm } from '@tanstack/react-form'

function ContactForm() {
  const form = useForm({
    defaultValues: {
      name: '',
      email: '',
      message: '',
    },
    onSubmit: async ({ value }) => {
      await fetch('/api/contact', {
        method: 'POST',
        body: JSON.stringify(value),
      })
    },
  })

  return (
    <form onSubmit={(e) => { e.preventDefault(); form.handleSubmit() }}>
      <form.Field
        name="name"
        children={(field) => (
          <div>
            <label>名前</label>
            <input
              value={field.state.value}
              onChange={(e) => field.handleChange(e.target.value)}
            />
          </div>
        )}
      />
      <form.Field
        name="email"
        children={(field) => (
          <div>
            <label>メール</label>
            <input
              value={field.state.value}
              onChange={(e) => field.handleChange(e.target.value)}
            />
          </div>
        )}
      />
      <button type="submit">送信</button>
    </form>
  )
}

<form.Field
  name="email"
  validators={{
    onChange: ({ value }) => {
      if (!value.includes('@')) return 'メールアドレスの形式が正しくありません'
      return undefined
    },
    onBlur: ({ value }) => {
      if (value.length < 5) return '5文字以上で入力してください'
      return undefined
    },
  }}
  children={(field) => (
    <div>
      <input
        value={field.state.value}
        onChange={(e) => field.handleChange(e.target.value)}
        onBlur={field.handleBlur}
      />
      {field.state.meta.errors.length > 0 && (
        <p style={{ color: 'red' }}>{field.state.meta.errors.join(', ')}</p>
      )}
    </div>
  )}
/>

validators={{
  onChangeAsync: async ({ value }) => {
    const exists = await checkEmailExists(value)
    if (exists) return 'このメールアドレスは既に登録されています'
    return undefined
  },
  onChangeAsyncDebounceMs: 500,
}}

npm install @tanstack/store @tanstack/react-store

import { Store } from '@tanstack/store'
import { useStore } from '@tanstack/react-store'

// コンポーネント外でストアを作成
const countStore = new Store({ count: 0, label: 'カウンター' })

function Counter() {
  // セレクタで必要な値のみ購読 - count が変わった時だけ再レンダリング
  const count = useStore(countStore, (state) => state.count)

  return (
    <div>
      <p>カウント: {count}</p>
      <button
        onClick={() =>
          countStore.setState((state) => ({
            ...state,
            count: state.count + 1,
          }))
        }
      >
        +1
      </button>
    </div>
  )
}

npm install @tanstack/react-query-devtools

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

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

npm install @tanstack/react-router-devtools

import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

function RootComponent() {
  return (
    <>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  )
}

npm install @tanstack/react-table-devtools

npm install @tanstack/devtools

import { TanStackDevtools } from '@tanstack/devtools'

function App() {
  return (
    <>
      <YourApp />
      <TanStackDevtools />
    </>
  )
}

const queryClient = useQueryClient()

// 特定クエリの無効化 - 再フェッチをトリガー
queryClient.invalidateQueries({ queryKey: ['todos'] })

// キャッシュデータの直接更新
queryClient.setQueryData(['todo', id], updatedTodo)

// キャッシュデータの取得
const cachedData = queryClient.getQueryData(['todos'])

// 特定クエリの削除
queryClient.removeQueries({ queryKey: ['todos'] })

// 全キャッシュのクリア
queryClient.clear()

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24時間
    },
  },
})

// サーバーサイド
import { dehydrate, QueryClient } from '@tanstack/react-query'

export async function getServerSideProps() {
  const queryClient = new QueryClient()
  await queryClient.prefetchQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
  })
  return {
    props: {
      dehydratedState: dehydrate(queryClient),
    },
  }
}

// クライアントサイド
import { HydrationBoundary } from '@tanstack/react-query'

function App({ dehydratedState }) {
  return (
    <QueryClientProvider client={queryClient}>
      <HydrationBoundary state={dehydratedState}>
        <YourApp />
      </HydrationBoundary>
    </QueryClientProvider>
  )
}

// Query Key Factory パターン
const todoKeys = {
  all:     ['todos'] as const,
  lists:   ()  => [...todoKeys.all, 'list'] as const,
  list:    (filters: Filters) => [...todoKeys.lists(), filters] as const,
  details: ()  => [...todoKeys.all, 'detail'] as const,
  detail:  (id: number) => [...todoKeys.details(), id] as const,
}

// 使用例
useQuery({ queryKey: todoKeys.detail(1), queryFn: () => fetchTodo(1) })

// 関連キャッシュの一括無効化
queryClient.invalidateQueries({ queryKey: todoKeys.lists() })

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60,     // 1分
      gcTime: 1000 * 60 * 5,    // 5分
    },
  },
})

const { data, error, isError } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  retry: 3,
  retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
})

if (isError) return <div>Error: {error.message}</div>

const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      if (query.state.data !== undefined) {
        toast.error(`データ更新に失敗しました: ${error.message}`)
      }
    },
  }),
  mutationCache: new MutationCache({
    onError: (error) => {
      toast.error(`操作に失敗しました: ${error.message}`)
    },
  }),
})

import { QueryErrorResetBoundary } from '@tanstack/react-query'
import { ErrorBoundary } from 'react-error-boundary'

function App() {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary onReset={reset} fallbackRender={({ resetErrorBoundary }) => (
          <div>
            <p>エラーが発生しました</p>
            <button onClick={resetErrorBoundary}>再試行</button>
          </div>
        )}>
          <Todos />
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  )
}

import { renderHook, waitFor } from '@testing-library/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

function createTestQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: { retry: false },
    },
  })
}

function createWrapper() {
  const queryClient = createTestQueryClient()
  return ({ children }) => (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  )
}

test('useCustomHook returns data', async () => {
  const { result } = renderHook(() => useCustomHook(), {
    wrapper: createWrapper(),
  })

  await waitFor(() => expect(result.current.isSuccess).toBe(true))
  expect(result.current.data).toEqual('Hello')
})

import { http, HttpResponse } from 'msw'
import { setupServer } from 'msw/node'

const server = setupServer(
  http.get('/api/todos', () => {
    return HttpResponse.json([{ id: 1, title: 'Test' }])
  })
)

beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

test('useTodos fetches data', async () => {
  const { result } = renderHook(() => useTodos(), {
    wrapper: createWrapper(),
  })
  await waitFor(() => expect(result.current.isSuccess).toBe(true))
  expect(result.current.data).toHaveLength(1)
})

const { data: todoCount } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  select: (data) => data.length,
})

// 大規模データで構造共有を無効化
useQuery({
  queryKey: ['large-dataset'],
  queryFn: fetchLargeData,
  structuralSharing: false,
})

// リストキャッシュから詳細画面の仮データを提供
useQuery({
  queryKey: ['todo', id],
  queryFn: () => fetchTodo(id),
  placeholderData: () => {
    return queryClient
      .getQueryData(['todos'])
      ?.find((todo) => todo.id === id)
  },
})

// 前回データの保持 - v5
import { keepPreviousData } from '@tanstack/react-query'

useQuery({
  queryKey: ['todos', page],
  queryFn: () => fetchTodos(page),
  placeholderData: keepPreviousData,
})

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

useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => {
    await queryClient.cancelQueries({ queryKey: ['todos'] })
    const previous = queryClient.getQueryData(['todos'])
    queryClient.setQueryData(['todos'], (old) =>
      old.map((t) => (t.id === newTodo.id ? newTodo : t))
    )
    return { previous }
  },
  onError: (_err, _newTodo, context) => {
    queryClient.setQueryData(['todos'], context.previous)
  },
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['todos'] })
  },
})

// NG: レンダーごとに新しい参照が生成される
useQuery({ queryKey: ['todos', { filter }], ... })

// OK: useMemo で安定化する - filter がプリミティブ値ならそのままでよい
const stableFilter = useMemo(() => ({ status, sort }), [status, sort])
useQuery({ queryKey: ['todos', stableFilter], ... })

// 広範囲マッチ
queryClient.invalidateQueries({ queryKey: ['todos'] })

// 完全一致のみ無効化
queryClient.invalidateQueries({ queryKey: ['todos'], exact: true })

declare module '@tanstack/react-query' {
  interface Register {
    defaultError: AxiosError<ApiError>
  }
}

const data = queryClient.getQueryData<Todo[]>(['todos'])

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "strict": true
  }
}