TanStack Conventions

TanStack Conventions

This skill enforces cross-cutting conventions across all TanStack libraries for consistent, maintainable React SPA development.

Project Structure

Feature-Based Organization

src/
├── features/
│   ├── posts/
│   │   ├── components/
│   │   │   ├── PostList.tsx
│   │   │   ├── PostCard.tsx
│   │   │   ├── PostForm.tsx
│   │   │   └── index.ts          # Barrel export
│   │   ├── hooks/
│   │   │   ├── useCreatePost.ts
│   │   │   ├── useUpdatePost.ts
│   │   │   ├── useDeletePost.ts
│   │   │   └── index.ts
│   │   ├── queries/
│   │   │   ├── postQueries.ts    # Query options factories
│   │   │   └── index.ts
│   │   ├── api/
│   │   │   └── postApi.ts        # API client functions
│   │   ├── types.ts              # Feature-specific types
│   │   └── index.ts              # Feature barrel export
│   └── users/
│       └── ...
├── routes/
│   ├── __root.tsx
│   ├── index.tsx
│   ├── posts.tsx
│   ├── posts.index.tsx
│   └── posts.$postId.tsx
├── lib/
│   ├── query-client.ts           # Query client setup
│   ├── query-keys.ts             # Query key factory
│   └── router.ts                 # Router setup
├── components/
│   └── ui/                       # Shared UI components
├── hooks/                        # Shared hooks
├── types/                        # Global types
└── main.tsx

Import Conventions

Always Use Path Aliases

// ✅ CORRECT: Path aliases
import { PostList } from '@/features/posts/components'
import { useCreatePost } from '@/features/posts/hooks'
import { postQueryOptions } from '@/features/posts/queries'
import { queryKeys } from '@/lib/query-keys'
import { Button } from '@/components/ui'

// ❌ WRONG: Relative imports across features
import { User } from '../../users/types'
import { queryClient } from '../../../lib/query-client'

// ❌ WRONG: Deep imports bypassing barrels
import { PostCard } from '@/features/posts/components/PostCard'

Barrel Export Pattern

// features/posts/components/index.ts
export { PostList } from './PostList'
export { PostCard } from './PostCard'
export { PostForm } from './PostForm'

// features/posts/index.ts
export * from './components'
export * from './hooks'
export * from './queries'
export * from './types'