Scalable Folder Architecture

Simple Structure for Small Apps

For a small app, a flat structure — one components/ folder, one hooks/ folder, maybe a utils/ folder — is often perfectly sufficient and easy to navigate. Adding more elaborate structure before it's actually needed can add friction without real benefit.

Note: Start simple. You can always reorganize into a more elaborate structure later once the app's real shape becomes clear.

Warning: Over-engineering folder structure for a project with 5 components can make the codebase feel more complicated than it actually is.

Example: Creating a Flat Folder Structure

$ mkdir -p src/components src/hooks src/utils
$ ls src
components  hooks  utils  App.jsx  main.jsx

Feature-Based Structure for Larger Apps

As an app grows, grouping files by FEATURE (all of a shopping cart's components, hooks, and logic together in one features/cart/ folder) rather than by file TYPE keeps related code physically close together, making it easier to find everything relevant to one feature at once.

Note: A good signal you've outgrown a flat structure: you frequently need to jump between several distant folders just to work on one feature.

Warning: Mixing both organizing principles inconsistently (some features grouped, others scattered by type) is often more confusing than picking either approach and sticking with it.

Example: Creating a Feature-Based Folder Structure

$ mkdir -p src/features/cart/components src/features/cart/hooks
$ ls -R src/features/cart
src/features/cart:
components  hooks  cartSlice.js  CartPage.jsx

src/features/cart/components:
CartItem.jsx  CartSummary.jsx

Consistency Over Perfection

There's no single universally correct folder structure — different teams and frameworks favor different conventions successfully. What matters most is picking ONE approach and applying it consistently, so anyone on the team (or future you) can predict where to find or add a given file.

Note: Document your project's chosen convention briefly (even a short README section) so new contributors don't have to guess.

Warning: A codebase with several competing, inconsistently-applied organizing schemes is often harder to navigate than one with a single, simpler, consistently-followed convention.