Organize React Code

Organize React Code

Structure React code around cohesive components and clear state ownership. Preserve the application's behavior while refactoring unless the user explicitly requests behavior or design changes.

Component Boundaries

• Extract components when a section has a distinct responsibility, can be named clearly, or makes its parent difficult to read.
• Avoid both monolithic components and tiny abstractions that do not create a meaningful boundary.
• Give every component its own directory named after the component.
• Use this structure:

ComponentName/
├── ComponentName.tsx
├── ComponentName.hook.ts
└── index.ts

• Keep ComponentName.tsx focused on JSX, props, and composition.
• Put the component's stateful logic, derived data, handlers, and orchestration in ComponentName.hook.ts.
• Use the exact case-sensitive hook filename <ComponentName>.hook.ts.
• A genuinely pure presentational component does not need an empty hook file.
• Export the component through its index.ts and import it through the directory boundary.
• Keep index.ts minimal. Export the component and only the public types or hooks consumers genuinely need. Do not create broad barrels that expose implementation details.
• Keep component-specific hooks private unless they intentionally form part of a provider or reusable component API.

JSX and Styling

• Express Tailwind classes directly and clearly in the JSX element they style.
• Do not hide long Tailwind strings behind generic class constants, lookup objects, or helpers whose only purpose is concatenating static classes.
• Use conditional class composition only when the rendered class genuinely depends on state or props.
• Preserve semantic HTML and accessible interaction behavior while reorganizing markup.

State Ownership

When a task involves choosing, changing, or auditing state ownership, load and follow $choose-react-state-management. Treat that dedicated skill as the authoritative guide for classifying local UI, shared client, server, URL, form, and persistent state.

Apply its decisions to this component structure:

• Keep component-owned state and handlers in the colocated <ComponentName>.hook.ts.
• Keep form drafts local even when submission uses a server-state mutation.
• Put shared providers or stores behind an intentional public API rather than importing component internals.
• Do not duplicate query results or other state merely to fit the folder layout.
• Maintain one source of truth and derive filtered, selected, or formatted values where they are consumed.

Effects

When reviewing, adding, removing, or relocating effects, load and follow $avoid-unnecessary-useeffect. Treat that dedicated skill as the authoritative guide for deciding whether an effect is necessary.

Apply its decisions to this component structure:

• Keep a necessary component-specific effect in the colocated <ComponentName>.hook.ts.
• Keep interaction logic in the handler that caused it rather than moving it into an effect.
• Keep server fetching in the project's server-state layer rather than in a component effect.
• Keep cleanup beside the subscription, listener, timer, or resource it owns.

Readability Rules

• Leave blank lines between logical blocks so functions are easy to scan.
• Format long objects with one property per line.
• Always use braces for if, else, loops, and similar control-flow blocks.
• Expand try, catch, and finally blocks; do not compress them into terse one-line forms.
• Prefer early returns when they simplify nesting.
• Do not use the void operator to silence promises. Handle, await, return, or deliberately catch the promise instead.
• Use explicit, domain-oriented names for components, hooks, handlers, and state transitions.

Review Workflow

1. Inventory component responsibilities, current effects, and state sources.
2. Define meaningful component boundaries before moving code.
3. Move logic into the exact colocated hook files and expose minimal component APIs.
4. Use $choose-react-state-management to classify state ownership and select the appropriate strategy.
5. Use $avoid-unnecessary-useeffect to remove unnecessary effects and correctly place the effects that remain.
6. Format the changed code and run the project's typecheck, tests, and production build when available.
7. Report any behavior that could not be verified and do not claim success when validation fails.