Three conventions that cut onboarding from weeks to days
Onboarding a new dev to our codebase used to take weeks. We got it down to days.
The stack didn't change: React, Next.js, Node.js, same as always. What changed were the conventions around it. Boring, unglamorous rules that every repo follows without exception.
The 3 that made the biggest difference:
1. One folder structure — every project, no debate.
Same shape everywhere: features grouped by domain, not by file type. A dev who's seen one repo already knows where things live in the next one. Nobody burns a morning hunting for "where does this go?"
2. Business logic never lives in a route or a component.
Controllers handle HTTP, components handle UI and both stay thin. The real logic sits in services you can read, test, and change without touching the plumbing. When requirements shift, you're editing one file, not ten.
3. One source of truth for data shapes.
Shared TypeScript types (or schemas) between client and server. The frontend never guesses what the API returns, and a breaking change lights up at compile time instead of in a user's browser.
Honest limits
- Conventions only work if the whole team holds the line — one "I'll just do it my way" repo undoes the benefit.
- Too many rules is its own tax. Keep the list short enough that people actually remember it.
The tools get the headlines. The conventions do the work.
One question: what's the ONE convention you'd make non-negotiable on every project? Genuinely curious what others swear by.