react-tanstack-senior

React + TanStack シニア開発者スキル

基本理念

KISS > Clever Code
Readability > Brevity  
Explicit > Implicit
Composition > Inheritance
Colocation > Separation
Type Safety > Any

クイック判断ツリー

状態管理：

• サーバー状態 → TanStack Query（必須）
• URL 状態 → TanStack Router の検索パラメーター
• フォーム状態 → TanStack Form または React Hook Form
• グローバル UI 状態 → Zustand（Redux ではない）
• ローカル UI 状態 → useState/useReducer

ルーティング：

• SPA → TanStack Router
• フルスタック SSR → TanStack Start
• 既存の Next.js → Next.js を引き続き使用

プロジェクトセットアップのワークフロー

1. プロジェクトの種類を判断：

   • SPA／クライアントのみ？ → Vite + TanStack Router + Query
   • フルスタック SSR？ → TanStack Start（Vinxi ベース）
   • 既存のプロジェクト？ → 段階的に導入

2. プロジェクトを初期化 → folder-structure.md を参照

3. コア依存関係をセットアップ → recommended-libraries.md を参照

TanStack エコシステムのリファレンス

ライブラリ	参照するタイミング
tanstack-query.md	データ取得、キャッシュ、ミューテーション
tanstack-router.md	型安全なルーティング、ローダー、検索パラメーター
tanstack-table.md	複雑なテーブル、並べ替え、フィルタリング、ページネーション
tanstack-form.md	フォームの検証、フィールド配列、非同期検証
tanstack-start.md	フルスタック SSR フレームワーク

コード品質基準

命名規則

// Components: PascalCase dengan suffix deskriptif
UserProfileCard.tsx      // ✓
UserCard.tsx             // ✗ terlalu generic
user-profile.tsx         // ✗ wrong case

// Hooks: camelCase dengan prefix 'use'
useUserProfile()         // ✓
useGetUserProfile()      // ✗ redundant 'Get'
getUserProfile()         // ✗ missing 'use'

// Query keys: array dengan hierarchy
['users', 'list', { status }]           // ✓
['usersList']                            // ✗ tidak granular
`users-${status}`                        // ✗ string interpolation

// Files: kebab-case untuk non-components
api-client.ts            // ✓
apiClient.ts             // ✗ 

コンポーネント構成パターン

// 1. Imports (grouped: external → internal → types)
import { useSuspenseQuery } from '@tanstack/react-query'
import { userQueries } from '@/features/users/api'
import type { User } from '@/features/users/types'

// 2. Types (colocated, tidak di file terpisah kecuali shared)
interface UserCardProps {
  userId: string
  onSelect?: (user: User) => void
}

// 3. Component (single responsibility)
export function UserCard({ userId, onSelect }: UserCardProps) {
  // 3a. Queries/mutations first
  const { data: user } = useSuspenseQuery(userQueries.detail(userId))
  
  // 3b. Derived state (useMemo hanya jika expensive)
  const fullName = `${user.firstName} ${user.lastName}`
  
  // 3c. Handlers (useCallback hanya jika passed to memoized children)
  const handleClick = () => onSelect?.(user)
  
  // 3d. Early returns untuk edge cases
  if (!user.isActive) return null
  
  // 3e. JSX (clean, minimal nesting)
  return (
    <article onClick={handleClick} className="user-card">
      <h3>{fullName}</h3>
      <p>{user.email}</p>
    </article>
  )
}

避けるべきアンチパターン

// ❌ NEVER: useEffect untuk data fetching
useEffect(() => {
  fetch('/api/users').then(setUsers)
}, [])

// ✅ ALWAYS: TanStack Query
const { data: users } = useQuery(userQueries.list())

// ❌ NEVER: Prop drilling lebih dari 2 level
<Parent userData={user}>
  <Child userData={user}>
    <GrandChild userData={user} />

// ✅ ALWAYS: Context atau query di level yang butuh
function GrandChild() {
  const { data: user } = useQuery(userQueries.current())
}

// ❌ NEVER: Premature optimization
const value = useMemo(() => a + b, [a, b]) // simple math

// ✅ ALWAYS: Optimize only when measured
const value = a + b // just calculate

// ❌ NEVER: Index as key untuk dynamic lists
{items.map((item, i) => <Item key={i} />)}

// ✅ ALWAYS: Stable unique identifier
{items.map(item => <Item key={item.id} />)}

デバッグガイド

debugging-guide.md では、以下を説明しています：

• React DevTools によるプロファイリング
• TanStack Query DevTools
• メモリーリークの検出
• パフォーマンスのボトルネックの特定
• よくあるエラーパターン

よくある落とし穴とバグ

common-pitfalls.md では、以下を説明しています：

• 古いクロージャによるバグ
• 競合状態
• メモリーリークのパターン
• ハイドレーションの不一致
• クエリーの無効化に関する間違い

パフォーマンスチェックリスト

□ Bundle size < 200KB gzipped (initial)
□ Largest Contentful Paint < 2.5s
□ No unnecessary re-renders (React DevTools)
□ Images lazy loaded
□ Code splitting per route
□ Query deduplication working
□ No memory leaks (heap snapshot stable)

コードレビューのチェックリスト

□ No `any` types (use `unknown` if needed)
□ No `// @ts-ignore` tanpa penjelasan
□ Error boundaries di route level
□ Loading states handled
□ Empty states handled
□ Error states handled  
□ Accessibility (aria labels, keyboard nav)
□ No hardcoded strings (i18n ready)
□ No console.log in production code
□ Tests untuk business logic