Bulletproof React

Bulletproof React

Architecture patterns for building scalable, maintainable React applications. Based on bulletproof-react.

Core references

Project structure

Organize by feature, not by file type:

src/
├── app/                # Application shell (routes, providers, router)
├── assets/             # Static files (images, fonts)
├── components/         # Shared, reusable UI components
├── config/             # Environment variables, constants
├── features/           # Feature-based modules
├── hooks/              # Shared custom hooks
├── lib/                # Pre-configured library wrappers
├── stores/             # Global client state
├── testing/            # Test utilities, MSW handlers, factories
├── types/              # Shared TypeScript types
└── utils/              # Pure utility functions

Feature modules

features/users/
├── api/            # API functions and query hooks
├── components/     # Feature-specific components
├── hooks/          # Feature-specific hooks
├── types/          # Feature-specific types
└── utils/          # Feature-specific utilities

Rules:

• Features should not import from other features. Compose at the app level.
• Code flows one direction: shared → features → app.
• Promote to shared directories only when reused by 2+ features.
• Prefer direct imports over barrel re-exports for Vite tree-shaking.

Component hierarchy

Page Components          → route-level, compose features, handle layout
  └── Feature Components → feature-specific, business logic
        └── UI Components      → shared primitives, no business logic

API layer pattern

// Pure API function
function getUsers(params?: GetUsersParams): Promise<UsersResponse> {
    return api.get("/users", { params });
}

// Query hook wrapping the API function
function useUsers(params?: GetUsersParams) {
    return useQuery({
        queryKey: ["users", params],
        queryFn: () => getUsers(params),
    });
}

State management boundaries

Don't mix server and client state. Never copy query data into useState.

Error hierarchy

App Error Boundary          → catches unrecoverable crashes
  └── Route Error Boundary     → catches route-level failures, shows retry
        └── Feature Error Boundary   → catches feature-specific errors

Testing strategy

Conventions

Imports

Use path aliases to avoid deep relative imports:

import { Button } from "@/components/ui/button";
import { useUsers } from "@/features/users/api";

Configure @/ as the src/ alias in tsconfig.json.