As React applications grow from prototypes to enterprise-grade platforms, the standard ‘components-by-type’ folder structure often collapses under its own weight. Placing all hooks in one directory and all components in another creates cognitive overhead and tightly couples unrelated features. Feature-based [[architecture](/blog/resilient-architecture-design-building-for-the-disasters-we-cant-predict)](/blog/building-enola-part-3-linking-architecture-across-repositories) shifts the focus from technical implementation details to domain-driven boundaries, ensuring that code related to a specific business capability lives within a single, encapsulated module.

This approach addresses the ‘spaghetti dependency’ problem common in large codebases. By enforcing strict module boundaries, we can treat individual features as semi-independent units, facilitating easier testing, code ownership, and even micro-frontend transitions if the need arises.

Defining the Module Boundary

A feature module should contain everything required for that domain: UI components, local state management, API service definitions, and route definitions. The key to success is the ‘index.ts’ entry point, which serves as the public API for the feature. Any code outside the feature module should only access members exported from this index file.

src/features/billing/
├── api/
├── components/
├── hooks/
├── types/
└── index.ts // Public API for the billing module

Encapsulation via Index Files

By explicitly defining an index file, you create a contract for the rest of the application. Internal implementation details—such as specific utility functions or private sub-components—remain hidden. This allows you to refactor the internal logic of a feature without breaking consumers, provided the public API remains stable.

export { BillingDashboard } from './components/BillingDashboard';
export { useBillingSubscription } from './hooks/useBillingSubscription';
export type { BillingStatus } from './types';

Managing Cross-Feature Communication

A common challenge in modular systems is how features interact. If ‘Billing’ needs data from ‘UserAccount’, avoid direct imports of internal files. Instead, use a shared layer for common utilities, or better yet, emit domain events or use a shared state interface. Direct dependency cycles are the primary cause of architectural decay.

Features should be as autonomous as possible. If two features are constantly needing to reach into each other’s internal state, it is a strong signal that they should be merged into a single domain module.

Measuring Architectural Success

In a production environment, we track architectural health through two primary metrics: coupling density and build times. Coupling density is measured by analyzing the import graph; we expect to see a clear hierarchy where shared core libraries are at the bottom, and feature modules reside at the top, rarely importing from each other.

• Dependency Inversion: Use interfaces to decouple features from shared infrastructure.
• Module Boundary Enforcement: Use ESLint rules (no-restricted-imports) to prevent cross-feature internal access.
• Lazy Loading: Leverage React.lazy() on the feature index files to split the bundle at the domain level.

Conclusion

Adopting a feature-based architecture is not merely an organizational preference; it is a defensive programming strategy. By limiting the scope of change to specific domain modules, teams can work in parallel with reduced risk of regression. While it introduces more boilerplate initially, the long-term gains in maintainability and developer velocity are significant for any application expected to live beyond a single release cycle.