128 lines
3.5 KiB
Markdown
128 lines
3.5 KiB
Markdown
# 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)**:
|
|
```typescript
|
|
export interface PageHeaderProps {
|
|
title: string;
|
|
subtitle?: string;
|
|
}
|
|
|
|
export const PageHeader = ({ title, subtitle }: PageHeaderProps) => {
|
|
return (
|
|
// Component implementation
|
|
);
|
|
};
|
|
```
|
|
|
|
**Types File (types.ts)**:
|
|
```typescript
|
|
export interface PageHeaderTheme {
|
|
backgroundColor: string;
|
|
textColor: string;
|
|
}
|
|
|
|
// Additional component-specific types
|
|
```
|
|
|
|
**Barrel File (index.ts)**:
|
|
```typescript
|
|
export * from './PageHeader';
|
|
export * from './types';
|
|
```
|
|
|
|
## Import Examples
|
|
|
|
```typescript
|
|
// 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:
|
|
|
|
```markdown
|
|
# 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. |