Nobody teaches folder structure; everyone judges it. Reviewers open your repo and form an opinion in ten seconds.
Small static project
my-site/ ├── index.html ├── css/style.css ├── js/main.js ├── images/ └── README.md ← the most-skipped, most-read file
App-sized (Vite/React)
src/ ├── components/ # reusable UI (Button, Card, Navbar) ├── pages/ # route-level views ├── hooks/ # useAuth, useFetch ├── utils/ # pure helpers (formatDate, calcGpa) ├── services/ # API calls in ONE place — not scattered fetches ├── assets/ └── main.jsx
The services folder is the sleeper: every fetch in one layer means auth headers, error handling and base URLs change in one file.
Scaling rule: group by feature, not type
# past ~20 components, flip the axis: src/features/ ├── auth/ # ITS components, hooks, api, tests together ├── results/ └── playground/
Everything about a feature lives together — deleting a feature is deleting a folder.
The consistency laws
- Pick ONE casing (kebab-case files, PascalCase components) and never mix
- index.js re-exports keep imports clean:
import { Button } from "@/components" - A README with setup steps + screenshot beats any structure — write it first, not never