Component Structure Standard

Component Structure Standard

Purpose

Define a consistent structure for React components to improve discoverability, reusability, and review quality.

Scope

Applies to:

• shared components under src/components/*
• module-scoped components under src/modules/*/components/*

Core Principles

1. Co-locate related files.
2. Keep component public API explicit.
3. Promote reuse only when reuse is proven.
4. Avoid import-path noise and accidental coupling.

Required Conventions

1) Folder vs single file

Use a folder when a component needs more than one file (styles, helpers, subcomponents, tests):

components/
  ComponentName/
    index.tsx
    componentName.module.css
    SubPart.tsx

Use a single file only when the component is truly single-file and stable:

components/
  ComponentName.tsx

2) Barrel entry point

When using a folder, expose the component through a single entry (index.ts or index.tsx).

3) Subcomponent placement

If a subcomponent is only used by its parent, keep it inside the same folder. If it is reused by other domains, promote it to its own component.

4) Styling placement

• Component-specific styles stay with the component.
• Styles shared by unrelated components belong in src/styles/*.

Import Guidelines

Prefer imports from component entry points rather than deep internals.

Good:

import TabManager from "@/components/TabManager";
import { SidePanelButton } from "@/components/SidePanel";

Avoid:

import TabManager from "@/components/TabManager/index";
import SidePanelButton from "@/components/SidePanel/SidePanelButton";

Anti-Patterns

• Multiple implicit entry points for one component.
• Cross-folder deep imports into another component’s private files.
• Promoting utility fragments to shared components before real reuse exists.

Migration Guidance

When a folder component shrinks to one file, flatten it into a single file. When a single-file component grows additional files, convert it to a folder with an explicit entry point.

PR Review Checklist

• Component structure matches this standard.
• Public import path is clear and stable.
• No private deep imports from other components.
• Styling location matches sharing scope.