React: What are the best practices for React project structure?

Project structure affects scalability, maintainability, and development speed.

System design context: As a React codebase grows from 10 to 1000+ components, the folder structure determines how easily developers can find code, understand dependencies, and add features. A poor structure leads to circular imports, merge conflicts, and cognitive overload. The goal is to group code by what it does, not what it is.

1. Feature-Sliced Design (FSD) — recommended approach:

Why FSD works: Each layer has strict rules about what it can import from lower layers. This prevents circular dependencies and makes refactoring safe. features/ never imports from pages/, and shared/ never imports from features/.

2. Colo-oriented structure (legacy approach):

3. File naming:

4. Import rules:

1// Use path aliases (@/)
2import { Button } from "@/shared/ui/Button";
3import { useAuth } from "@/features/auth";
4import type { User } from "@/entities/user";

Scaling patterns for large teams:

• Split by domain — each team owns a feature directory.
• Use barrel exports (index.ts) for clean public APIs.
• Enforce import rules with ESLint (eslint-plugin-import).
• Keep shared/ truly generic — if it references a domain entity, it belongs in entities/.

5. Other best practices:

• One component = one file (not two components in one file).
• Components < 200 lines (if more — split).
• Custom hooks instead of HOC and render props.
• TypeScript everywhere.
• ESLint + Prettier for consistency.