Component Structure Guidelines

[hdinia]

This document outlines our recommended structure for React components, following screaming architecture while maintaining clarity, testability, and scalability.

Base Structure

/ComponentName
├── components/
│   ├── SubComponentA/
│   │   ├── index.tsx
│   │   ├── types.ts
│   │   ├── styles.ts        [Optional]
│   │   └── SubComponentA.test.tsx
│   └── SubComponentB/
├── shared/
│   ├── constants.ts
│   ├── types.ts
│   ├── utils.ts
│   └── utils.test.ts
├── hooks/
│   └── useFeatureA/
│       ├── index.ts
│       ├── types.ts
│       └── useFeatureA.test.ts
├── index.tsx
└── styles.ts              [Optional]

Key Rules & Best Practices

1. Component Definition

Always use function syntax for components:

// ✅ Do: Use function declaration
function UserProfile({ name, age }: UserProfileProps) {
  return (
    <div>
      <h2>{name}</h2>
      <span>{age}</span>
    </div>
  );
}

// ❌ Don't: Use arrow function
const UserProfile: FC<UserProfileProps> = ({ name, age }) => {
  return (
    <div>
      <h2>{name}</h2>
      <span>{age}</span>
    </div>
  );
};

2. Test Organization

Single Test File Rule:

When a component/hook/utility has only one test file, place it next to the source:

// ✅ Do: Single test file structure
/ButtonGroup
├── index.tsx
├── types.ts
└── ButtonGroup.test.tsx

// ❌ Don't: Create __tests__ directory for single file
/ButtonGroup
├── index.tsx
├── types.ts
└── __tests__/
    └── ButtonGroup.test.tsx

Multiple Test Files Rule:

Create a __tests__ directory when you have multiple test files:

// ✅ Do: Multiple test files structure
/DataGrid
└── __tests__/
    ├── DataGrid.unit.test.tsx          // Unit tests
    ├── DataGrid.integration.test.tsx   // Integration tests
    ├── utils.ts             // Test utilities
    └── fixtures.ts               // Test data

// ❌ Don't: Mix multiple test files at root
/DataGrid
├── DataGrid.unit.test.tsx
├── DataGrid.integration.test.tsx
└── DataGrid.e2e.test.tsx

Naming

Simple small component:

• [Component].test.ts(x)

Bigger component with more than unit tests:

• Unit tests > [Component].unit.test.ts(x)
• Integration tests > [Component].integration.test.ts(x)
• End to end tests > [Component].e2e.test.ts(x)

Directory Details

1. /components

Purpose: Child components specific to this component.

// ✅ Do: Clear component structure
/components
└── SubComponentA/
    ├── index.tsx
    ├── types.ts
    └── SubComponentA.test.tsx

// ❌ Don't: Mix concerns
/components
└── SubComponentA.tsx     // All in one file

Example:

// ✅ Do: Clear type definitions and implementation
// components/SubComponentA/types.ts
export interface SubComponentAProps {
  data: SubComponentData;
  onChange?: (data: SubComponentData) => void;
}

// components/SubComponentA/index.tsx
function SubComponentA({ data, onChange }: SubComponentAProps) {
  return <div onClick={() => onChange?.(data)}>{data.label}</div>;
}

// ❌ Don't: Mix types and implementation
function SubComponentA({ data, onChange }: { data: any; onChange?: Function }) {
  return <div onClick={() => onChange?.(data)}>{data.label}</div>;
}

2. /shared

Purpose: Shared business logic, types, and utilities.

// ✅ Do: Organized shared files
/shared
├── constants.ts
├── types.ts
├── utils.ts
└── utils.test.ts

// ❌ Don't: Mix shared logic with components
/shared
├── types.ts
└── SubComponentLogic.tsx

Example:

// ✅ Do: Clear type exports
// shared/types.ts
export interface ComponentData {
  id: string;
  value: unknown;
}

// ❌ Don't: Mix internal and external types
interface InternalType {} // Should be in a separate file
export interface PublicType {}

3. /hooks

Purpose: Custom hooks for component logic.

// ✅ Do: Clear hook structure
/hooks
└── useFeatureA/
    ├── index.ts
    ├── types.ts
    └── useFeatureA.test.ts

// ❌ Don't: Mix hook with components
/hooks
└── FeatureAHook.tsx  // Wrong file extension and structure

Example:

// ✅ Do: Clear hook implementation
function useFeatureA({ initialValue }: UseFeatureAOptions): UseFeatureAResult {
  const [value, setValue] = useState(initialValue);
  
  function updateValue(newValue: string) {
    setValue(newValue);
  }
  
  return { value, updateValue };
}

// ❌ Don't: Mix concerns in hooks
function useFeatureA() {
  const [value, setValue] = useState('');
  // Don't include JSX in hooks
  return <div>{value}</div>;
}

Complete Example

Here's a complex component following all rules:

Here's a complete example showing both rules in practice:

// Simple component with single test file
/ButtonGroup
├── index.tsx
├── types.ts
└── ButtonGroup.test.tsx

// Complex component with multiple test files
/DataGrid
├── components/
│   ├── GridHeader/
│   │   ├── index.tsx
│   │   ├── types.ts
│   │   └── __tests__/
│   │       ├── GridHeader.test.tsx
│   │       ├── GridHeader.integration.tsx
│   │       └── utils.ts
│   └── GridCell/
│       ├── index.tsx
│       ├── types.ts
│       └── GridCell.test.tsx        // Single test file
├── shared/
│   ├── utils.ts
│   ├── types.ts
│   └── utils.test.ts               // Single test file
└── hooks/
│    └── useGridSort/
│        ├── index.ts
│        ├── types.ts
│        └── __tests__/
│            ├── useGridSort.test.ts
│            ├── useGridSort.integration.ts
│            └── utils.ts
├── index.tsx
└── styles.ts              [Optional]

Component Implementation Examples:

Component Structure Additional Rules

Test Organization Rules

Single Test File Rule

When a component/hook/utility has only one test file, place it directly next to the source file with a .test.tsx extension:

/ComponentName
├── components/
│   └── SubComponentA/
│       ├── index.tsx
│       ├── types.ts
│       └── SubComponentA.test.tsx    // Single test file

Multiple Test Files Rule

Create a __tests__ directory when you have:

• Multiple types of tests (unit, integration, e2e)
• Test utilities or fixtures
• Multiple test files for different aspects of the component

/ComponentName
├── components/
│   └── ComplexComponent/
│       ├── index.tsx
│       ├── types.ts
│       └── __tests__/
│           ├── ComplexComponent.test.tsx         // Unit tests
│           ├── ComplexComponent.integration.tsx  // Integration tests
│           ├── ComplexComponent.e2e.tsx         // E2E tests
│           ├── test-utils.ts                    // Test utilities
│           └── fixtures.ts                      // Test data

Benefits

Clear Boundaries

• Each directory has a single responsibility
• Dependencies are explicit
• Easy to understand structure

Maintainability

• Co-located tests
• Isolated styles
• Clear type definitions

Scalability

• Easy to add new features
• Clear place for new code
• Consistent structure

Performance

• Enables tree-shaking
• Optimized imports
• Clear bundling boundaries

---

Props Destructuring

1. Function Arguments Destructuring

Always destructure props directly in the function arguments:

// ✅ Do: Destructure props in function arguments
function UserProfile({ name, age, email, isAdmin }: UserProfileProps) {
  return (
    
      {name}
      {age}
      {email}
      {isAdmin && }
    
  );
}

// ❌ Don't: Destructure props inside the function
function UserProfile(props: UserProfileProps) {
  const { name, age, email, isAdmin } = props;  // Avoid this
  
  return (
    
      {name}
      {age}
      {email}
      {isAdmin && }
    
  );
}

2. Benefits of Arguments Destructuring

1. Immediate Prop Visibility:

// ✅ Do: Props are immediately visible in function signature
function ProductCard({ 
  title, 
  price, 
  onAdd, 
  isInStock 
}: ProductCardProps) {
  // Props usage is clear from the start
}

// ❌ Don't: Hide props in function body
function ProductCard(props: ProductCardProps) {
  const { title, price, onAdd, isInStock } = props; // Props are hidden
}

2. TypeScript Type Inference:

// ✅ Do: Better type inference for destructured props
function UserStatus({ 
  status, 
  lastActive 
}: UserStatusProps) {
  // TypeScript knows 'status' and 'lastActive' types immediately
  const statusColor = getStatusColor(status); // Better type inference
}

// ❌ Don't: Less precise type inference
function UserStatus(props: UserStatusProps) {
  const { status, lastActive } = props;
  // Extra step for TypeScript to infer types
}

3. Default Values:

// ✅ Do: Clean default value assignment
function Pagination({ 
  page = 1, 
  pageSize = 10, 
  total 
}: PaginationProps) {
  // Default values are clearly visible in the signature
}

// ❌ Don't: Separate default values
function Pagination(props: PaginationProps) {
  const { page, pageSize, total } = props;
  const currentPage = page ?? 1;        // Less clear
  const currentPageSize = pageSize ?? 10; // Clutters the function body
}

4. Optional Props:

// ✅ Do: Clear optional props handling
function Alert({ 
  message, 
  type = 'info',
  onClose?: () => void 
}: AlertProps) {
  // Optional onClose is clearly marked in signature
}

// ❌ Don't: Hide optional props
function Alert(props: AlertProps) {
  const { message, type = 'info', onClose } = props;
  // Optional nature of onClose is hidden
}

3. Complex Props Cases

For components with many props, group them logically:

// ✅ Do: Group related props
function DataTable({ 
  // Data props
  data,
  columns,
  
  // UI props
  isLoading,
  error,
  
  // Event handlers
  onSort,
  onFilter,
  onRowClick,
  
  // Pagination props
  page = 1,
  pageSize = 10,
  total
}: DataTableProps) {
  // Clean implementation
}

// ❌ Don't: Mix props without logical grouping
function DataTable(props: DataTableProps) {
  const { 
    data, isLoading, onSort, page, 
    columns, error, onFilter, pageSize,
    onRowClick, total 
  } = props;
  // Harder to understand prop relationships
}

Remember:

• Always destructure props in function arguments
• Group related props together in signature
• Use default values in the destructuring
• Keep optional props clear with ? syntax
• Benefits include:
  • Better readability
  • Immediate prop visibility
  • Better TypeScript type inference
  • Cleaner default value handling
  • Clear optional props marking
  • Logical prop grouping

---

Types Organization

1. Types Location

Public types go in shared/types.ts, while internal types should be co-located with their components:

// ✅ Do: Keep public types in shared/types.ts
// shared/types.ts
export interface TableProps {
  data: TableData[];
  onSort?: (column: string) => void;
}

// ✅ Do: Keep internal types with their components
// components/TableHeader/types.ts
interface InternalHeaderState {
  isResizing: boolean;
  startWidth: number;
}

// ❌ Don't: Put internal types in shared/types.ts
// shared/types.ts
interface InternalHeaderState { ... }  // Should be in component's types.ts

2. Enum-like Constants

Use object-like enum notation with as const in shared/constants.ts, using PascalCase for enum values and derive types using the suffix Type:

// ✅ Do: Use PascalCase for enum values
// shared/constants.ts
export const SORT_DIRECTION = {
  Ascending: 'ascending',
  Descending: 'descending',
  None: 'none',
} as const;

export const VIEW_MODES = {
  Grid: 'grid',
  List: 'list',
  Compact: 'compact',
} as const;

// shared/types.ts
export type SortDirectionType = typeof SORT_DIRECTION[keyof typeof SORT_DIRECTION];

// ❌ Don't: Use incorrect casing for enum values
export const SORT_DIRECTION = {
  ASCENDING: 'ascending',  // Should be PascalCase
  ascending: 'ascending',  // Should be PascalCase
} as const;

3. Constants Organization

All constants should be defined in shared/constants.ts using UPPER_SNAKE_CASE for the constant name:

// ✅ Do: Define all constants in shared/constants.ts with proper casing
// shared/constants.ts
export const TABLE_DEFAULT_PAGE_SIZE = 10;
export const MINIMUM_COLUMN_WIDTH = 100;

export const COLUMN_SIZES = {
  Small: 'sm',
  Medium: 'md',
  Large: 'lg',
} as const;

// ❌ Don't: Define constants in component files or use incorrect casing
// components/Table/index.tsx
const defaultPageSize = 10;  // Should be in constants.ts
const COLUMN_SIZES = {
  SMALL: 'sm',  // Should use PascalCase
} as const;

4. Type Composition Exception

For type composition, all related types should stay in shared/types.ts:

// ✅ Do: Keep composed types together in shared/types.ts
// shared/constants.ts
export const COLUMN_SIZES = {
  Small: 'sm',
  Medium: 'md',
  Large: 'lg',
} as const;

// shared/types.ts
export type ColumnSizeType = typeof COLUMN_SIZES[keyof typeof COLUMN_SIZES];

export interface ColumnProps {
  size: ColumnSizeType;
  title: string;
}

// ❌ Don't: Split composed types
// components/Column/types.ts
type ColumnSizeType = 'sm' | 'md' | 'lg';  // Should be in shared/types.ts with other composed types

5. Naming Conventions

Follow consistent naming for types and constants:

// ✅ Do: Use consistent naming
// shared/constants.ts
export const LAYOUT_MODES = {
  Horizontal: 'horizontal',
  Vertical: 'vertical',
  Grid: 'grid',
} as const;

// shared/types.ts
export type LayoutModeType = typeof LAYOUT_MODES[keyof typeof LAYOUT_MODES];

// ❌ Don't: Use inconsistent naming
export const layoutModes = { ... }  // Should be UPPER_SNAKE_CASE
type TLayoutMode = ...  // Should be LayoutModeType

This organization ensures:

• Clear separation between public and internal types
• Consistent naming conventions
• PascalCase for enum values
• UPPER_SNAKE_CASE for constant names
• Type safety through derived types
• Proper co-location of internal types

Remember:

• Public types go in shared/types.ts
• Internal types stay with their components
• All constants and enum-like objects go in shared/constants.ts
• Use as const with object-like enums
• Use PascalCase for enum values
• Use UPPER_SNAKE_CASE for constant names
• Derive types from constants using Type suffix
• Exception: Keep composed types together in shared/types.ts

---

State Management Organization (Context)

1. Simple Context Case

For simple state (few values, simple updates):

// ✅ Do: Keep it simple for basic state
/ComponentName
├── context/
│   ├── ThemeContext.tsx
│   └── ThemeContext.test.tsx

// context/ThemeContext.tsx
interface ThemeContextValue {
  isDark: boolean;
  toggleTheme: () => void;
}

export const ThemeContext = createContext(undefined);

export function ThemeProvider({ children }: PropsWithChildren) {
  const [isDark, setIsDark] = useState(false);
  const toggleTheme = useCallback(() => setIsDark(prev => !prev), []);
  
  return (
    
      {children}
    
  );
}

// ❌ Don't: Over-engineer simple state
/ComponentName
├── context/
│   ├── ThemeContext/
│   │   ├── reducer.ts     // Unnecessary for simple state
│   │   ├── actions.ts
│   │   └── selectors.ts

2. Complex Context Case

For complex state (multiple values, complex updates, derived state):

// ✅ Do: Organize complex context properly
/ComponentName
├── context/
│   ├── DataContext/
│   │   ├── index.tsx
│   │   ├── types.ts
│   │   ├── constants.ts
│   │   └── DataContext.test.tsx
│   └── useDataContext.ts

// context/DataContext/types.ts
interface DataState {
  items: Item[];
  filters: Filters;
  sortOrder: SortOrder;
  selectedIds: string[];
}

interface DataContextValue extends DataState {
  actions: {
    updateFilters: (filters: Filters) => void;
    toggleSelection: (id: string) => void;
    setSortOrder: (order: SortOrder) => void;
  };
}

// context/DataContext/index.tsx
export function DataProvider({ children }: PropsWithChildren) {
  const [state, setState] = useState({
    items: [],
    filters: defaultFilters,
    sortOrder: 'asc',
    selectedIds: [],
  });

  const contextValue = useMemo(() => ({
    ...state,
    actions: {
      updateFilters: (filters) => setState(prev => ({ ...prev, filters })),
      toggleSelection: (id) => setState(prev => ({
        ...prev,
        selectedIds: prev.selectedIds.includes(id)
          ? prev.selectedIds.filter(i => i !== id)
          : [...prev.selectedIds, id],
      })),
      setSortOrder: (sortOrder) => setState(prev => ({ ...prev, sortOrder })),
    },
  }), [state]);

  return (
    
      {children}
    
  );
}

---

API Services Organization

1. Simple API Case

For components with 1-2 API calls:

// ✅ Do: Keep it simple for basic API calls
/ComponentName
├── api/
│   ├── userApi.ts
│   └── userApi.test.ts

// api/userApi.ts
import axios from 'axios';

export const userApi = {
  getUser: async (id: string) => {
    const { data } = await axios.get(`/api/users/${id}`);
    return data;
  },
  
  updateUser: async (id: string, userData: UserData) => {
    const { data } = await axios.put(`/api/users/${id}`, userData);
    return data;
  },
};

// ❌ Don't: Mix API calls in components
function UserProfile({ id }: { id: string }) {
  const fetchUser = async () => {  // Should be in api file
    const response = await axios.get(`/api/users/${id}`);
    return response.data;
  };
}

---

API Organization Rules

1. Global API Directory

Use /src/api for shared API calls that are used across multiple components:

// ✅ Do: Place shared API calls in global directory
/src
├── api/
│   ├── users/
│   │   ├── types.ts
│   │   ├── usersApi.ts
│   │   └── __tests__/
│   │       └── usersApi.test.ts
│   ├── studies/
│   │   └── ...
│   └── config/
│       └── ...

// api/users/types.ts
export interface User {
  id: string;
  name: string;
  email: string;
}

export interface UserParams {
  role?: string;
  status?: 'active' | 'inactive';
}

// api/users/usersApi.ts
import axios from 'axios';
import { User, UserParams } from './types';

export const usersApi = {
  getUsers: async (params?: UserParams) => {
    const { data } = await axios.get<User[]>('/api/users', { params });
    return data;
  },
  
  updateUser: async (id: string, userData: Partial<User>) => {
    const { data } = await axios.put<User>(`/api/users/${id}`, userData);
    return data;
  },
};

// ❌ Don't: Duplicate shared API calls in components
/src/components/UserList/api/usersApi.ts        // Don't duplicate
/src/components/UserProfile/api/usersApi.ts     // Don't duplicate

2. Component-Level API Directory

Use component-level API calls only for highly specific, component-bound functionality:

// ✅ Do: Place component-specific API calls in the component
/src/components/DataGrid
├── api/
│   ├── types.ts
│   ├── gridApi.ts
│   └── __tests__/
│       └── gridApi.test.ts
└── index.tsx

// components/DataGrid/api/types.ts
export interface GridLayout {
  columns: Array<{ id: string; width: number }>;
  sortOrder: 'asc' | 'desc';
  pageSize: number;
}

// components/DataGrid/api/gridApi.ts
import axios from 'axios';
import { GridLayout } from './types';

export const gridApi = {
  saveLayout: async (layout: GridLayout) => {
    const { data } = await axios.post<{ success: boolean }>(
      '/api/user-preferences/grid-layout', 
      layout
    );
    return data;
  },
  
  getLayout: async () => {
    const { data } = await axios.get<GridLayout>('/api/user-preferences/grid-layout');
    return data;
  },
};

// ❌ Don't: Place generic API calls in components
/src/components/UserProfile/api/usersApi.ts  // Should be in global api

3. Usage Examples

Simple Global API Usage:

// ✅ Do: Simple API hooks with loading and error states
// src/api/users/useUsers.ts
export function useUsers(initialParams?: UserParams) {
  const [data, setData] = useState<User[] | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);

  const fetchUsers = async (params?: UserParams) => {
    try {
      setLoading(true);
      const users = await usersApi.getUsers(params);
      setData(users);
    } catch (err) {
      setError(err instanceof Error ? err : new Error('Unknown error'));
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    fetchUsers(initialParams);
  }, [/* dependencies */]);

  return { data, loading, error, refetch: fetchUsers };
}

// Usage in component
function UserList() {
  const { data: users, loading, error } = useUsers({ role: 'admin' });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <ul>
      {users?.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

Complex Component API Usage:

// ✅ Do: Complex API hooks with state management
// src/components/DataGrid/api/useGridLayout.ts
export function useGridLayout() {
  const [layout, setLayout] = useState<GridLayout | null>(null);
  const [saving, setSaving] = useState(false);
  const [error, setError] = useState<Error | null>(null);

  const saveLayout = async (newLayout: GridLayout) => {
    try {
      setSaving(true);
      await gridApi.saveLayout(newLayout);
      setLayout(newLayout);
    } catch (err) {
      setError(err instanceof Error ? err : new Error('Failed to save layout'));
      throw err; // Allow parent component to handle error
    } finally {
      setSaving(false);
    }
  };

  const loadLayout = async () => {
    try {
      const savedLayout = await gridApi.getLayout();
      setLayout(savedLayout);
    } catch (err) {
      setError(err instanceof Error ? err : new Error('Failed to load layout'));
      // Fall back to default layout
      setLayout(defaultLayout);
    }
  };

  // Load initial layout
  useEffect(() => {
    loadLayout();
  }, []);

  return {
    layout,
    saving,
    error,
    saveLayout,
    loadLayout,
  };
}

// Usage in component
function DataGrid() {
  const { 
    layout, 
    saving, 
    error, 
    saveLayout 
  } = useGridLayout();

  const handleLayoutChange = async (newLayout: GridLayout) => {
    try {
      await saveLayout(newLayout);
      toast.success('Layout saved successfully');
    } catch (err) {
      toast.error('Failed to save layout');
    }
  };

  return (
    <div>
      {/* Grid implementation */}
    </div>
  );
}

Remember:

• Use global API directory for shared functionality
• Keep component-specific API calls in the component
• Implement proper loading and error states
• Handle errors consistently
• Use TypeScript for better type safety
• Create custom hooks for complex API state management
• Keep API calls separate from UI components
• Use proper error boundaries

---

Future optimisations: Data Fetching & Validation

1. Basic Setup

First, set up your schema and types:

// ✅ Do: Define schemas in a dedicated types file
// types.ts
import { z } from 'zod';

export const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
  role: z.enum(['user', 'admin']),
  createdAt: z.string().datetime(),
});

export type User = z.infer<typeof UserSchema>;

// ❌ Don't: Mix schemas with API or component logic
function UserProfile() {
  const userSchema = z.object({ ... }); // Don't define schemas here
}

2. Simple Query Example

Basic query with validation:

// ✅ Do: Create reusable query hooks with validation
// api/queries/useUser.ts
export function useUser(id: string) {
  return useQuery({
    queryKey: ['user', id],
    queryFn: async () => {
      const response = await axios.get(`/api/users/${id}`);
      return UserSchema.parse(response.data);
    },
  });
}

// Usage
function UserProfile({ id }: { id: string }) {
  const { data: user, isLoading, error } = useUser(id);
  
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return <div>{user.name}</div>;
}

// ❌ Don't: Validate data in components
function UserProfile({ id }: { id: string }) {
  const { data } = useQuery({
    queryKey: ['user', id],
    queryFn: async () => {
      const response = await axios.get(`/api/users/${id}`);
      try {
        // Don't validate here
        return UserSchema.parse(response.data);
      } catch (error) {
        // Error handling...
      }
    },
  });
}

3. Complex Query with Relations

Handle related data with proper typing and validation:

// ✅ Do: Create comprehensive schemas for related data
// types.ts
const PostSchema = z.object({
  id: z.string(),
  title: z.string(),
  content: z.string(),
  authorId: z.string(),
});

const CommentSchema = z.object({
  id: z.string(),
  content: z.string(),
  postId: z.string(),
  userId: z.string(),
});

const PostWithDetailsSchema = PostSchema.extend({
  author: UserSchema,
  comments: z.array(CommentSchema),
});

type PostWithDetails = z.infer<typeof PostWithDetailsSchema>;

// api/queries/usePost.ts
export function usePost(id: string) {
  return useQuery({
    queryKey: ['post', id],
    queryFn: async () => {
      const response = await axios.get(`/api/posts/${id}?include=author,comments`);
      return PostWithDetailsSchema.parse(response.data);
    },
  });
}

// ❌ Don't: Make multiple separate queries
function PostDetails({ id }: { id: string }) {
  // Don't do separate queries for related data
  const { data: post } = useQuery(['post', id], ...);
  const { data: author } = useQuery(['user', post?.authorId], ...);
  const { data: comments } = useQuery(['comments', id], ...);
}

4. Mutations with Optimistic Updates

// ✅ Do: Implement type-safe optimistic updates
// types.ts
const UpdateUserSchema = UserSchema.partial().omit({ id: true });
type UpdateUserInput = z.infer<typeof UpdateUserSchema>;

// api/mutations/useUpdateUser.ts
export function useUpdateUser() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: async ({ id, data }: { id: string; data: UpdateUserInput }) => {
      const response = await axios.patch(`/api/users/${id}`, data);
      return UserSchema.parse(response.data);
    },
    onMutate: async ({ id, data }) => {
      await queryClient.cancelQueries({ queryKey: ['user', id] });
      
      const previousUser = queryClient.getQueryData<User>(['user', id]);
      
      queryClient.setQueryData<User>(['user', id], old => ({
        ...old!,
        ...data,
      }));
      
      return { previousUser };
    },
    onError: (err, { id }, context) => {
      queryClient.setQueryData(['user', id], context?.previousUser);
    },
    onSettled: (_, __, { id }) => {
      queryClient.invalidateQueries({ queryKey: ['user', id] });
    },
  });
}

// ❌ Don't: Skip validation in mutations
const useUpdateUser = () => useMutation({
  mutationFn: ({ id, data }) => axios.patch(`/api/users/${id}`, data), // Missing validation
});

5. Cached Selectors

// ✅ Do: Create reusable selectors with type safety
// api/selectors/userSelectors.ts
export const selectUserPermissions = (user: User) => {
  const rolePermissions = {
    admin: ['read', 'write', 'delete'],
    user: ['read'],
  };
  
  return rolePermissions[user.role] ?? [];
};

function AdminPanel() {
  const { data: user } = useUser(id);
  const permissions = user ? selectUserPermissions(user) : [];
  
  return permissions.includes('delete') ? <DeleteButton /> : null;
}

// ❌ Don't: Recalculate derived data
function AdminPanel() {
  const { data: user } = useUser(id);
  // Don't recalculate on every render
  const permissions = user?.role === 'admin' ? ['read', 'write', 'delete'] : ['read'];
}

6. Query Invalidation Strategy

// ✅ Do: Create clear invalidation strategies
// api/queryClient.ts
export const queryKeys = {
  users: {
    all: ['users'] as const,
    lists: () => [...queryKeys.users.all, 'list'] as const,
    detail: (id: string) => [...queryKeys.users.all, id] as const,
    posts: (id: string) => [...queryKeys.users.all, id, 'posts'] as const,
  },
  posts: {
    all: ['posts'] as const,
    lists: () => [...queryKeys.posts.all, 'list'] as const,
    detail: (id: string) => [...queryKeys.posts.all, id] as const,
  },
} as const;

// api/mutations/useCreatePost.ts
export function useCreatePost() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: async (data: CreatePostInput) => {
      const response = await axios.post('/api/posts', data);
      return PostSchema.parse(response.data);
    },
    onSuccess: (newPost) => {
      // Invalidate specific queries
      queryClient.invalidateQueries({
        queryKey: queryKeys.posts.lists(),
      });
      queryClient.invalidateQueries({
        queryKey: queryKeys.users.posts(newPost.authorId),
      });
    },
  });
}

// ❌ Don't: Use hard-coded query keys or broad invalidation
const useCreatePost = () => useMutation({
  onSuccess: () => {
    queryClient.invalidateQueries(); // Too broad
    // or
    queryClient.invalidateQueries(['posts']); // Hard-coded
  },
});

Remember:

• Define schemas in dedicated files
• Use type inference from Zod schemas
• Implement consistent error handling
• Create reusable validation utilities
• Use proper query invalidation strategies
• Implement optimistic updates for better UX
• Create type-safe selectors for derived data
• Keep query keys organized and type-safe