React Component Organization Conventions

Feature-Based Organization

Group related components into feature folders:

src/
  features/
    navigation/           # Feature group
      README.md           # Feature documentation with architecture diagrams
      page-header/        # Component
      page-wrapper/       # Component
      sidebar/            # Component
    auth/                 # Another feature group
    dashboard/            # Another feature group

Component Folder Structure

For each component that requires co-located files (types, tests, etc.):

component-name/
  - ComponentName.tsx     # Main component implementation
  - types.ts              # Component-specific types
  - ComponentName.test.tsx # Component tests
  - README.md             # Component-specific documentation
  - index.ts              # Barrel exports

Naming Conventions

Folders: Use kebab-case (page-header/)
Component Files: Use PascalCase matching export name (PageHeader.tsx)
Type Files: Use types.ts for component-specific types
Test Files: Use component name with .test.tsx suffix (PageHeader.test.tsx)
Index Files: Always use index.ts for barrel exports

Styling Conventions

Use Tailwind: Always use Tailwind classes for styling instead of CSS files or inline styles
Use UI Components: Leverage existing UI components from components/ui directory
No External CSS: Never import external CSS files
No New Libraries: Do not add new dependencies; use existing ones
Follow Patterns: Match styling patterns used in the existing codebase

Export Patterns

Component File (PageHeader.tsx):

export interface PageHeaderProps {
  title: string;
  subtitle?: string;
}

export const PageHeader = ({ title, subtitle }: PageHeaderProps) => {
  return (
    // Component implementation
  );
};

Types File (types.ts):

export interface PageHeaderTheme {
  backgroundColor: string;
  textColor: string;
}

// Additional component-specific types

Barrel File (index.ts):

export * from './PageHeader';
export * from './types';

Import Examples

// Import specific component
import { PageHeader } from '../components/page-header/PageHeader';

// Import via barrel
import { PageHeader, PageHeaderTheme } from '../components/page-header';

Feature Documentation

Each feature folder should include a comprehensive README.md:

# Navigation Components

## Overview
This module contains all navigation-related components for the application.

## Architecture
```mermaid
graph TD
    App --> PageWrapper
    PageWrapper --> PageHeader
    PageWrapper --> Sidebar
    PageWrapper --> MainContent
    PageHeader --> Breadcrumbs
    PageHeader --> UserMenu

Components

PageHeader: Application header with navigation controls
PageWrapper: Layout wrapper for all pages
Sidebar: Main navigation sidebar


## Benefits of this Approach

- Avoids "index.tsx maze" - component location is always clear
- Easier debugging (stack traces point to actual component files)
- Feature-based organization provides clear domain boundaries
- Architecture documentation with visual diagrams improves onboarding
- Maintains logical co-location while separating concerns
- Enables precise imports when needed
- Follows widely accepted React community standards
- Scales well with large component libraries

This convention balances maintainability with developer experience and remains effective as your application grows.

3.5 KiB Raw Permalink Blame History