bulletproof-react

name	bulletproof-react
description	Bulletproof React architecture patterns for scalable, maintainable applications. Covers feature-based project structure, component patterns, state management boundaries, API layer design, error handling, security, and testing strategies. Use when structuring a React project, designing application architecture, organizing features, or when the user asks about React project structure or scalable patterns.
metadata	{"author":"Yam Borodetsky","original_author":"grahamcrackers","origin":"github.com/grahamcrackers/skills","internal":true}

Bulletproof React

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

Core references

Topic	Description	Reference
Project Structure	Feature-based organization, unidirectional architecture, ESLint enforcement	project-structure
Components & Styling	Component hierarchy, wrapping 3rd party libs, headless vs styled libraries	components-and-styling
API Layer	API client, request declarations, query/mutation hook patterns	api-layer
State Management	Component, application, server cache, form, and URL state categories	state-management
Error Handling	Error boundaries, API errors, error tracking with Sentry	error-handling
Testing	Unit, integration, e2e strategies with Vitest, Testing Library, Playwright, MSW	testing
Project Standards	ESLint, Prettier, TypeScript, Husky, absolute imports, file naming	project-standards
Security	Authentication, token storage, XSS prevention, RBAC/PBAC authorization	security
Performance	Code splitting, data prefetching, state optimization, children pattern	performance

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

State Type	Solution	Examples
Server state	TanStack Query	User data, posts, API responses
Client state (global)	Zustand / Jotai	Theme, sidebar open, user preferences
Client state (local)	useState / useReducer	Form inputs, toggles, modal open
URL state	URL search params / router	Filters, pagination, active tab
Form state	React Hook Form	Multi-step forms, validation

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

Layer	Tool	What to Test
Components	Testing Library	Render output, user interactions, a11y
Hooks	renderHook	State changes, side effects
API	MSW	Request/response handling, error states
Integration	Testing Library + MSW	Full feature flows (render → interact → verify)
E2E	Playwright	Critical user journeys

Conventions

Item	Convention	Example
Components	PascalCase	UserCard.tsx
Hooks	camelCase, use prefix	useUsers.ts
Utilities	camelCase	formatDate.ts
Types	PascalCase	User, CreateUserInput
Constants	UPPER_SNAKE_CASE	MAX_RETRIES
Directories	kebab-case	user-settings/
Files	kebab-case	user-card.tsx

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.