React Core

Comprehensive guidance for building scalable, performant, and secure React applications with modern best practices.

Quick Start

New Project Setup

1. Initialize with Vite:

   bashCopy

   pnpm create vite my-app --template react-ts
   cd my-app
   pnpm install
   

2. Use configuration templates:

   • Vite: assets/config-templates/vite.config.ts
   • Vitest: assets/config-templates/vitest.config.ts
   • ESLint: assets/config-templates/.eslintrc.react.json

3. Install essential dependencies:

   bashCopy

   # Routing
   pnpm add react-router-dom
   
   # Data fetching
   pnpm add @tanstack/react-query
   
   # Forms
   pnpm add react-hook-form @hookform/resolvers zod
   
   # State management (if needed)
   pnpm add zustand
   

4. Organize by feature: See project-structure.md for complete layouts

Common Workflows

Resolving Performance Issues:

1. Check performance.md for optimization techniques
2. Profile with React DevTools
3. Implement code splitting, virtualization, or memoization as needed

Setting Up State Management:

1. Review state-management.md decision framework
2. Choose appropriate solution (component state, Context, Zustand, React Query)
3. Implement following documented patterns

Implementing Authentication:

1. Follow security guidelines in security.md
2. Use HttpOnly cookies for tokens
3. Implement protected routes and authorization

Project Architecture

Project Structure

Organize code by feature, not by technical type:

src/
├── app/                   # App-level routing
├── features/             # Feature modules (self-contained)
│   ├── authentication/
│   ├── users/
│   └── dashboard/
├── components/           # Shared components
├── hooks/               # Shared hooks
├── lib/                 # Third-party setup
└── utils/               # Shared utilities

Key principles:

• Feature isolation with clear public APIs
• Unidirectional dependency flow (app → features → shared)
• Absolute imports via path aliases
• Consistent naming conventions

See project-structure.md for complete guide including:

• Feature module organization
• Shared code structure
• Enforcing architectural boundaries with ESLint
• Monorepo considerations

State Management

Choose the right state solution for each use case:

Decision framework:

1. Server data? → Use React Query
2. Form data? → Use React Hook Form
3. Should be in URL? → Use useSearchParams
4. Shared across app? → Use Zustand/Context
5. Otherwise → Component state

See state-management.md for complete patterns including:

• useState vs useReducer
• Context optimization
• Zustand and Jotai examples
• React Query patterns
• State colocation best practices

Performance

Critical Optimizations

1. Code Splitting - Load code on demand

   tsxCopy

   const Dashboard = lazy(() => import('./routes/Dashboard'));
   

2. List Virtualization - Render only visible items

   tsxCopy

   import { useVirtualizer } from '@tanstack/react-virtual';
   

3. Image Optimization - Lazy load and use modern formats

   tsxCopy

   <img src="/image.jpg" loading="lazy" />
   

4. Bundle Optimization - Analyze and reduce bundle size

   bashCopy

   npx vite-bundle-visualizer
   

React 19 Compiler

React 19's compiler automatically memoizes - remove manual React.memo, useMemo, useCallback when using the compiler.

See performance.md for complete guide including:

• Component optimization (memoization)
• List virtualization with examples
• Web Vitals optimization
• Data prefetching strategies
• Performance monitoring tools

API Layer

Structure API calls for maintainability and type safety:

// features/users/api/get-user.ts
import { z } from 'zod';
import { useQuery } from '@tanstack/react-query';

const userSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

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

export async function getUser(userId: string): Promise<User> {
  const response = await apiClient.get(`/users/${userId}`);
  return userSchema.parse(response.data);
}

export function useUser(userId: string) {
  return useQuery({
    queryKey: ['users', userId],
    queryFn: () => getUser(userId),
  });
}

See api-layer.md for complete patterns including:

• API client setup (Axios/Fetch)
• Request organization
• Error handling
• TypeScript integration
• Authentication patterns

Testing

Follow the testing pyramid:

     /\
    /E2E\      ← Few
   /------\
  /Integr.\   ← Some
 /----------\
/   Unit     \ ← Many

Tools:

• Vitest (test runner)
• React Testing Library (component testing)
• Playwright (E2E testing)
• MSW (API mocking)

Example:

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

test('button calls onClick when clicked', async () => {
  const handleClick = vi.fn();
  const user = userEvent.setup();

  render(<Button onClick={handleClick}>Click me</Button>);

  await user.click(screen.getByRole('button'));
  expect(handleClick).toHaveBeenCalledTimes(1);
});

See testing.md for complete guide including:

• Component testing patterns
• Hook testing
• Integration tests
• MSW setup
• E2E with Playwright

Security

Key Security Practices

1. Authentication - Use HttpOnly cookies
2. Authorization - Implement RBAC/PBAC
3. XSS Prevention - Sanitize user content
4. CSRF Protection - Use SameSite cookies
5. Input Validation - Validate client and server-side

Example:

// ✅ Secure token storage
// Server sets HttpOnly cookie
res.cookie('auth_token', token, {
  httpOnly: true,
  secure: true,
  sameSite: 'strict',
});

// ✅ Sanitize user content
import DOMPurify from 'dompurify';
const sanitized = DOMPurify.sanitize(userContent);

See security.md for complete guide including:

• Token storage best practices
• Protected routes
• Role and permission-based access control
• XSS and CSRF prevention
• CSP configuration

React 19 Features

Major Improvements

1. React Compiler - Automatic memoization
2. Server Components - Render on server
3. Actions - Simplified form handling
4. New Hooks - use(), useFormStatus(), useOptimistic()
5. Simplified refs - No more forwardRef

Example:

'use client';

import { useActionState } from 'react';

async function createUserAction(prevState, formData) {
  const user = await api.createUser(formData);
  return { success: true, user };
}

export function CreateUserForm() {
  const [state, formAction, isPending] = useActionState(createUserAction, null);

  return (
    <form action={formAction}>
      <input name="email" required />
      <button disabled={isPending}>
        {isPending ? 'Creating...' : 'Create'}
      </button>
    </form>
  );
}

See react-19-best-practices.md for complete guide.

Build & Tooling

Vite Configuration

Optimized build setup with code splitting, minification, and tree shaking.

See build-and-bundling.md for:

• Complete Vite configuration
• Code splitting strategies
• Bundle analysis
• Production optimizations

Essential Tools

See ecosystem-tools.md for recommended packages:

• Routing (React Router, TanStack Router)
• Data fetching (React Query, SWR)
• Forms (React Hook Form)
• State (Zustand, Jotai)
• Styling (Tailwind, CSS Modules)
• UI Components (Radix UI, shadcn/ui)

Common Pitfalls

Avoid these frequent mistakes:

1. Stale closures in useEffect
2. Missing dependencies in dependency arrays
3. Unnecessary useEffect for derived state
4. Mutating state directly
5. Using index as key in lists

See common-pitfalls.md for examples and solutions.

TypeScript Integration

Type your React components properly:

type ButtonProps = {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary';
  onClick?: () => void;
};

export function Button({ children, variant = 'primary', onClick }: ButtonProps) {
  return <button className={variant} onClick={onClick}>{children}</button>;
}

See typescript-react.md for complete patterns including:

• Component typing
• Event handlers
• Hooks with TypeScript
• React Query types
• Utility types

Reference Files

Architecture & Organization:

• project-structure.md - Feature-based organization, imports, naming
• state-management.md - State categories, decision framework, patterns

Performance & Optimization:

• performance.md - Code splitting, virtualization, Web Vitals
• build-and-bundling.md - Vite config, bundle optimization

API & Data:

• api-layer.md - API client, request patterns, error handling

Testing & Quality:

• testing.md - Component tests, integration tests, E2E
• security.md - Auth, authorization, XSS/CSRF prevention

React 19 & Modern Features:

• react-19-best-practices.md - Compiler, Server Components, Actions

Tools & Ecosystem:

• ecosystem-tools.md - Recommended packages by category
• typescript-react.md - TypeScript patterns for React

Troubleshooting:

• common-pitfalls.md - Frequent mistakes and solutions

Configuration Templates

Pre-configured files for quick project setup:

• vite.config.ts - Optimized Vite configuration
• vitest.config.ts - Testing setup
• .eslintrc.react.json - React linting rules

Best Practices Summary

1. Organize by feature - Keep related code together
2. Choose state wisely - Use React Query for server data
3. Optimize strategically - Profile before optimizing
4. Test behavior - Test what users see and do
5. Secure by default - HttpOnly cookies, sanitize input
6. Type everything - Leverage TypeScript fully
7. Stay modern - Adopt React 19 features
8. Keep it simple - Avoid premature optimization

Build React applications that are fast, secure, and maintainable.