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:

   bash

   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:

   bash

   # 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

   tsx

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

2. •

   List Virtualization - Render only visible items

   tsx

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

3. •

   Image Optimization - Lazy load and use modern formats

   tsx

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

4. •

   Bundle Optimization - Analyze and reduce bundle size

   bash

   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.