Imported from David-Li0406/meta-skill-evloving (skill-flow/data/skills-refined-36k/skillsmp/feature-arch/AGENTS.md). Install upstream with npx skills add David-Li0406/meta-skill-evloving --skill feature-arch. Copyright stays with the author.

React Feature-Based Architecture

Version 0.1.0
Community
January 2026

Note:
This document is mainly for agents and LLMs to follow when maintaining,
generating, or refactoring codebases. Humans may also find it useful,
but guidance here is optimized for automation and consistency by AI-assisted workflows.

Abstract

Comprehensive architecture guide for organizing React applications by features, enabling scalable development with independent teams. Contains 42 rules across 8 categories, prioritized by impact from critical (directory structure and import rules) to incremental (naming conventions). Each rule includes detailed explanations, production-realistic code examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.

Table of Contents

1. Directory Structure — CRITICAL
   • 1.1 Include Only Necessary Segments — HIGH (Prevents empty folder clutter; keeps features minimal and focused)
   • 1.2 Keep Directory Hierarchy Flat — CRITICAL (Reduces cognitive load; prevents 5+ level deep import paths)
   • 1.3 Make Features Self-Contained — CRITICAL (Enables independent deployment and parallel team development)
   • 1.4 Organize by Feature, Not Technical Type — CRITICAL (Eliminates cross-file navigation; reduces onboarding time by 50%+)
   • 1.5 Separate App Layer from Features — HIGH (Isolates global concerns; enables feature modules to remain pure)
   • 1.6 Use Shared Layer for Truly Generic Code Only — CRITICAL (Prevents shared/ from becoming a dumping ground; maintains feature boundaries)
2. Import & Dependencies — CRITICAL
   • 2.1 Avoid Deep Barrel File Re-exports — HIGH (Prevents tree-shaking failures; reduces bundle size by avoiding unused code)
   • 2.2 Enforce Unidirectional Import Flow — CRITICAL (Prevents circular dependencies; enables deterministic build order)
   • 2.3 Export Through Public API Only — CRITICAL (Prevents deep imports; enables internal refactoring without breaking consumers)
   • 2.4 Prohibit Cross-Feature Imports — CRITICAL (Prevents feature coupling; enables independent feature development)
   • 2.5 Use Consistent Path Aliases — HIGH (Eliminates ../../../ chains; makes imports self-documenting)
   • 2.6 Use Type-Only Imports for Types — MEDIUM (Enables cross-feature type sharing without runtime coupling)
3. Module Boundaries — HIGH
   • 3.1 Define Explicit Interface Contracts — HIGH (Prevents implicit dependencies; enables parallel feature development)
   • 3.2 Enforce Feature Isolation — HIGH (Changes in one feature have zero impact on others; enables fearless refactoring)
   • 3.3 Keep Features Appropriately Sized — MEDIUM (Right-sized features balance cohesion and manageability)
   • 3.4 Minimize Shared State Between Features — HIGH (Reduces coupling surface area; prevents state synchronization bugs)
   • 3.5 Scope Routing to Feature Concerns — HIGH (Enables feature-level code splitting; prevents routing configuration sprawl)
   • 3.6 Use Events for Cross-Feature Communication — MEDIUM-HIGH (Decouples features at runtime; enables loose coupling without direct imports)
4. Data Fetching — HIGH
   • 4.1 Avoid N+1 Query Patterns — HIGH (Prevents request count from scaling with data size; eliminates O(N) network calls)
   • 4.2 Colocate Data Fetching with Features — HIGH (Makes features self-contained; enables independent API evolution)
   • 4.3 Fetch at Server Component Level — MEDIUM-HIGH (Eliminates client-server waterfalls; reduces bundle size by keeping fetch logic on server)
   • 4.4 Fetch Independent Data in Parallel — HIGH (Reduces total load time by ~50% for pages with multiple data sources)
   • 4.5 Keep Query Functions Single-Purpose — HIGH (Prevents query permutation explosion as features grow)
   • 4.6 Use Feature-Scoped Query Keys — MEDIUM-HIGH (Enables targeted cache invalidation; prevents accidental cache collisions)
5. Component Organization — MEDIUM-HIGH
   • 5.1 Apply Single Responsibility to Components — MEDIUM-HIGH (Enables parallel development and isolated testing; reduces component complexity)
   • 5.2 Colocate Styles with Components — MEDIUM (Enables complete component portability; prevents orphaned styles)
   • 5.3 Prefer Composition Over Prop Drilling — MEDIUM-HIGH (Eliminates prop drilling; enables flexible slot-based component design)
   • 5.4 Separate Container and Presentational Concerns — MEDIUM (Enables design system reuse; keeps business logic testable)
   • 5.5 Use Feature-Level Error Boundaries — MEDIUM (Isolates failures to single features; prevents full-page crashes)
   • 5.6 Use Props as Feature Boundaries — MEDIUM-HIGH (Creates clear interfaces between features; enables feature composition)
6. State Management — MEDIUM
   • 6.1 Lift State Only as High as Necessary — MEDIUM (Reduces re-renders; keeps state close to where it's used)
   • 6.2 Reset Feature State on Unmount — MEDIUM (Prevents stale state bugs; ensures clean feature initialization)
   • 6.3 Scope State Stores to Features — MEDIUM (Prevents global state coupling; enables feature-level state reset and testing)
   • 6.4 Separate Server State from Client State — MEDIUM (Eliminates manual cache sync; leverages query library optimizations)
   • 6.5 Use Context Sparingly for Feature State — MEDIUM (Prevents context re-render cascades; keeps features portable)
7. Testing Strategy — MEDIUM
   • 7.1 Colocate Tests with Features — MEDIUM (Makes test coverage visible; ensures tests move with features)
   • 7.2 Create Feature-Specific Test Utilities — MEDIUM (Reduces test boilerplate; ensures consistent test setup)
   • 7.3 Test Features in Isolation — MEDIUM (Enables faster tests; provides clear failure attribution)
   • 7.4 Write Integration Tests at App Layer — MEDIUM (Verifies feature composition; catches integration bugs)
8. Naming Conventions — LOW
   • 8.1 Use Consistent File Naming Conventions — LOW (Enables pattern-based tooling; reduces cognitive load)
   • 8.2 Use Descriptive Export Names — LOW (Enables IDE autocomplete; makes imports self-documenting)
   • 8.3 Use Domain-Driven Feature Names — LOW (Improves discoverability; aligns code with business terminology)

References

1. https://www.robinwieruch.de/react-feature-architecture/
2. https://feature-sliced.design/
3. https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md
4. https://legacy.reactjs.org/docs/faq-structure.html

Source Files

This document was compiled from individual reference files. For detailed editing or extension: