Skip to main content

13. React Component Structure

Status: Accepted Date: 2025-07-06

Context​

The public-facing website (kaido.team) and other future front-end applications require custom React components to implement unique branding and layout features. Without a standardized component structure, the theme's codebase can quickly become disorganized, leading to difficulties in maintenance, code reuse, and onboarding new developers. A consistent structure is essential for long-term project health.

Decision​

We will adopt a standardized, feature-oriented structure for all custom React components. Each reusable component will be encapsulated within its own directory. The directory name will be PascalCase, matching the component name.

Each component directory will contain:

  • **ComponentName.tsx**: The main component logic and JSX.
  • **ComponentName.module.css**: CSS Modules for component-scoped styling to prevent style conflicts.
  • **index.ts**: A barrel file that exports the component and any associated types, simplifying imports.
  • **types.ts** (optional): TypeScript type definitions specific to the component, for separation of concerns.

For example, a custom Header component would be located at src/theme/components/Header/ and contain Header.tsx, Header.module.css, and index.ts.

Consequences​

Positive:

  • Organization & Co-location: Keeps all files related to a single component (logic, styles, types) together, making them easier to find, understand, and modify.
  • Scalability: The structure is predictable and scales well as the number of components grows.
  • Reusability: Well-encapsulated components are easier to reuse across the application.
  • Scoped Styles: Using CSS Modules prevents global style pollution and unintended side effects, a common issue in large applications.

Negative:

  • File Overhead: This approach creates more files and directories, which can seem verbose for very simple, one-off components.
  • Strictness: Requires discipline from the team to follow the structure consistently.

Mitigation:

  • Component Scaffolding: Use scripts, CLIs (e.g., Plop.js), or IDE snippets to quickly scaffold the directory structure for a new component, reducing manual effort.
  • Linting: Implement linting rules to enforce the file structure and naming conventions, ensuring consistency across the codebase.
  • Documentation: Clearly document the component structure, with examples, in the project's contribution guidelines.