intermediate20 min read·Updated Jul 2026Expert reviewed
Folder Structure & Feature-Based Architecture
Technical debt is often just poor folder structure. Moving from file-type grouping (controllers, components, views) to domain/feature-based grouping prevents 'file-hopping' and enables modules to be self-contained and deleted easily.
1. What is the primary benefit of feature-based folder organization?
Interview Questions
1 questions
Cheatsheet
Download-ready reference
Cheatsheet
File-type layout groups by file role (components/, hooks/, api/). Good for tiny apps.
Feature layout groups by business domain (features/billing/, features/auth/). Scale-ready.
Strict Boundaries:
- Use index.ts inside each feature folder as the only export gate.
- Prevent external code from importing internal folders directly.
- ESLint rule "no-restricted-imports" enforces this boundary.
As the app grows, adding or modifying a single feature requires file-hopping across multiple folders. This increases cognitive load and results in loose coupling of features.
Feature-based grouping consolidates related files into one folder representing a business domain or feature:
To keep features decoupled, they must communicate only through a strict public interface. The index.ts file at the feature root acts as a barrel file containing explicit exports.
Other features must never import internal files directly:
// ❌ WRONG: importing internals breaks encapsulationimport { CheckoutButton } from '../billing/components/CheckoutButton';// CORRECT: importing through feature public APIimport { CheckoutButton } from '../billing';
Use ESLint rules (no-restricted-imports) to block direct imports of internal directories.
When components are reused, developers throw them into a global shared/ or common/ folder. This folder becomes a massive junk drawer. Keep components inside feature folders until they are genuinely needed by multiple unrelated domains.