Yasin Avci

Yasin Avci

Full-Stack Developer

Paris, France

Contact me
Back to articles
ReactArchitectureFrontend

React Component Architecture: From Chaos to Clarity

Atomic Design, composition, separation of concerns... How to structure a React codebase that scales.

April 25, 20244 min read

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 useState for 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:

  1. Context for global data (user, theme)
  2. 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.