React Component Architecture: From Chaos to Clarity
Atomic Design, composition, separation of concerns... How to structure a React codebase that scales.
A React application can quickly become a tangle of components. After dozens of projects, here are the principles that keep code organized.
The Problem of Catch-All Components
We all start the same way: a 50-line UserProfile.tsx component. Six months later, it's 500 lines, handling display, API calls, validation, modals...
// ❌ The component that does everything
function UserProfile({ userId }) {
const [user, setUser] = useState(null);
const [isEditing, setIsEditing] = useState(false);
const [formData, setFormData] = useState({});
const [errors, setErrors] = useState({});
const [isLoading, setIsLoading] = useState(false);
useEffect(() => { /* fetch user */ }, []);
const handleSubmit = async () => { /* validation + API */ };
const handleDelete = async () => { /* confirmation + API */ };
// 200 lines of JSX with conditions everywhere
}
Principle 1: Separate Presentation and Logic
Presentation Components (UI)
Only do display. Receive props, return JSX.
// components/ui/UserCard.tsx
interface UserCardProps {
name: string;
email: string;
avatarUrl: string;
onEdit: () => void;
}
function UserCard({ name, email, avatarUrl, onEdit }: UserCardProps) {
return (
<div className="rounded-lg border p-4">
<img src={avatarUrl} alt={name} className="h-16 w-16 rounded-full" />
<h3 className="text-lg font-semibold">{name}</h3>
<p className="text-slate-500">{email}</p>
<button onClick={onEdit}>Edit</button>
</div>
);
}
Characteristics:
- No
useStatefor business logic - No API calls
- Easily testable and reusable
Container Components (Features)
Handle logic: state, effects, API calls.
// features/user/UserProfileContainer.tsx
function UserProfileContainer({ userId }: { userId: string }) {
const { user, isLoading } = useUser(userId);
const { mutate: updateUser } = useUpdateUser();
const [isEditing, setIsEditing] = useState(false);
if (isLoading) return <UserCardSkeleton />;
if (!user) return <UserNotFound />;
return (
<>
<UserCard
name={user.name}
email={user.email}
avatarUrl={user.avatarUrl}
onEdit={() => setIsEditing(true)}
/>
{isEditing && (
<UserEditModal
user={user}
onSave={updateUser}
onClose={() => setIsEditing(false)}
/>
)}
</>
);
}
Principle 2: Composition Over Inheritance
The Compound Components Pattern
For complex components with multiple related parts:
// Usage
<Card>
<Card.Header>
<Card.Title>Title</Card.Title>
<Card.Description>Description</Card.Description>
</Card.Header>
<Card.Content>
Main content
</Card.Content>
<Card.Footer>
<Button>Action</Button>
</Card.Footer>
</Card>
// Implementation
const Card = ({ children, className }) => (
<div className={cn("rounded-lg border", className)}>{children}</div>
);
Card.Header = ({ children }) => (
<div className="border-b p-4">{children}</div>
);
Card.Title = ({ children }) => (
<h3 className="text-lg font-semibold">{children}</h3>
);
// etc.
Advantages:
- Maximum flexibility
- Intuitive API
- Each part is simple
The Render Props / Children as Function Pattern
When the parent needs to control rendering:
<DataTable
data={users}
columns={columns}
renderRow={(user, index) => (
<TableRow key={user.id} highlight={index % 2 === 0}>
<TableCell>{user.name}</TableCell>
<TableCell>{user.email}</TableCell>
</TableRow>
)}
/>
Principle 3: Scalable Folder Structure
By Feature, Not by Type
// ❌ By type: hard to navigate
components/
buttons/
cards/
modals/
forms/
hooks/
useUser.ts
useProducts.ts
// âś… By feature: coherent
features/
auth/
components/
LoginForm.tsx
SignupForm.tsx
hooks/
useAuth.ts
api/
auth.ts
products/
components/
ProductCard.tsx
ProductList.tsx
hooks/
useProducts.ts
Shared Components Separate
src/
components/
ui/ # Generic components (Button, Card, Modal)
layout/ # Header, Footer, Sidebar
features/ # Business logic by domain
lib/ # Utilities, API clients
hooks/ # Hooks shared between features
Principle 4: Explicit Props
Avoid Excessive Prop Drilling
// ❌ Props traversing 5 levels
<App user={user}>
<Layout user={user}>
<Sidebar user={user}>
<UserMenu user={user} />
</Sidebar>
</Layout>
</App>
Solutions:
- Context for global data (user, theme)
- Composition to pass components directly
// âś… Composition: parent controls
<Layout
sidebar={<Sidebar><UserMenu user={user} /></Sidebar>}
>
<MainContent />
</Layout>
Type Props Rigorously
// ❌ Too permissive
interface ButtonProps {
variant?: string;
size?: string;
}
// âś… Strict types
interface ButtonProps {
variant?: 'primary' | 'secondary' | 'ghost';
size?: 'sm' | 'md' | 'lg';
}
Concrete Example: Page Refactoring
Before (500 lines)
function ProductPage({ productId }) {
// 15 useState
// 5 useEffect
// 10 handlers
// 300 lines of JSX with nested ternaries
}
After (clear structure)
// pages/products/[id].tsx - 30 lines
function ProductPage({ productId }) {
return (
<ProductProvider productId={productId}>
<ProductLayout>
<ProductHeader />
<ProductGallery />
<ProductInfo />
<ProductActions />
<ProductReviews />
</ProductLayout>
</ProductProvider>
);
}
// features/products/context/ProductProvider.tsx
// Handles all state and API calls
// features/products/components/ProductInfo.tsx
// Pure display, consumes context
Warning Signs
It's time to refactor when:
- A component exceeds 200 lines
- You're copy-pasting code between components
- Props traverse more than 2 levels
- You struggle to find where to modify something
- Tests are impossible to write
Conclusion
Good component architecture isn't about tools or trendy patterns. It's a discipline: separating responsibilities, naming clearly, organizing logically.
Start simple. Refactor when pain appears. Don't over-architect a prototype.
