Getting Started—What is this, and why does it exist?
Introduction
Learning is so much easier once you know what to learn.
During my first year of coding I spent almost a hundred hours on Zoom with any industry engineer/CTO who would answer my questions on how to maximize my rate of learning. Eventually, one mentor summed up the difference between a good and great developer in a single phrase:
Great engineers read documentation ferociously.
Yes, he really said ferociously. So I did just that. I devoured docs on React, Next.js, Typescript, designs systems, databases—anything in my reach. My rate of learning sky rocketed... until I hit a deeper, but much quieter problem: I knew dozens of APIs for all my favourite libraries, but I still struggled with things that felt super fundamental like Where should this file live? When, why and how do I memoize? How should I write custom hooks? Why did this refactor tank performance? Why are my builds taking so long?
I wrote—no exaggeration—tens of thousands to a hundred thousand lines of code a month on project after project. The trial-and-error process was painful, and wildly educational. therepository exists so you don't have to suffer quite as much. This is a collection of "slightly-advanced fundamentals" that nobody puts in official docs: directory structures, design-engineering-grade components, performance-oriented and boilerplate-reducing hooks, introduction to linting rules that actually matter and a deep dive on why, etc.
Guiding Principals
These are the reasons I believe this to be important, and what I hope sticks.
- Code as craft—Truly beautiful things are beautiful on the inside as well as on the outside. You should be incredibly intentional and write code with care
- Clarity over cleverness—The next person, often a future version of you, should smile, nod, and understand your code quickly, not squint and frown
- Performance-first, scale-ready, and developer-friendly—Today's side-project is tomorrow's prod service; build like it. The most important thing is still to ship fast, but with the right underlying setup, you can also ship elegantly
Who This Is For
I wrote these with a few people in mind.
- Front-end leaning full-stack engineers & design engineering early in their careers looking to level up
- Anyone who senses there is a "right way" to build beautiful, scalable UIs but needs help forming their opinion on what that way is
- Self-taught coders who want to ship performant side-projects, and want to get better quickly
What You'll Find Inside
Patterns & Structures—Practical directory layouts, file naming conventions, scalable module boundaries
Data Modeling—How to set up a PostgreSQL database with the right fundamentals, and Drizzle ORM + Supabase recipes that make TypeScript lovers smile
Developer Experiences—ESLint & Prettier configs explained in plain English so you know why they're used besides making code pretty. Writing code that plays nicely with AI code gen (yes, your LLM appreciates clean code too... I'll explain)
Custom React Hooks—Helpful code snippets that reduce boilerplate for small but useful behaviours with real-world demos.
Closing Note
Great engineering is learnable—and it starts with the right mental models. I’m sharing mine so you can skip the mistakes without skipping the learning. Here’s to writing code that feels as good to read as it does to run.
Disclaimer. Everything written across this entire project is opinionated. This is not the answer, it's just an answer. If you think I'm wrong, please email me and help me be better.
- Marcelo