Stop 19 · Frontend System DesignTopics · 1/13

Folder Structure

In short

In week one, any folder layout works. By month six, a bad one means ten minutes of hunting for every file. A clear structure is the cheapest gift you can give future you.

How you organize files and directories in a frontend project — a foundational decision that either keeps a codebase navigable as it grows, or turns it into a maze.

The jaadu stands beside a neat almirah with shirts, books and documents on separate shelves.

Think of it like this

A well-kept hostel almirah

Shirts on one shelf, books on another, documents in one file. Your roommate can find your Aadhaar copy without calling you. A good folder structure works the same way: a new teammate guesses where things live and is usually right.

Watch it happen

A layout anyone can guess

src/

app/ (routes)

components/ui/

features/

cart/

auth/

lib/

1/5Everything lives under src. The top level stays short and readable.

The big ideas

What you need to know

Predictable beats clever

Pick simple rules everyone can guess, like "all routes in app, all shared UI in components/ui".

Keep related files close

A component's styles, tests and helpers can sit next to it instead of in far-off folders.

Use path aliases

An alias like @/components saves you from ../../../ chains that break when files move.

Grow it gradually

Start flat. Add a new folder only when a group of files clearly belongs together.

See it in code

Walk through the code

text

1src/2  app/              # routes and pages3  components/ui/    # shared buttons, inputs, modals4  features/5    cart/           # everything about the cart6    auth/           # everything about login7  hooks/            # hooks used across features8  lib/              # api client, helpers, config9  types/            # shared TypeScript types

1/4Routes and pages.

This is a common layout for a Next.js or Vite app. The exact names matter less than the team agreeing on them and sticking to them.

Save yourself the pain

Common mistakes

Oops

A utils folder with 60 unrelated files in it.

Do this instead

Split helpers by purpose (dates, currency, validation), or move each one next to the feature that uses it.

Oops

Nesting folders six levels deep from day one.

Do this instead

Stay shallow until it hurts. Deep trees make imports long and files hard to find.

Your mission

Give your project a tidy-up

~30 min

Quick check

Which sign best tells you a folder structure is working well?

Go deeper

1Compare 2-3 popular folder structures (by type, by feature, atomic) for the same app.
2Refactor an existing 'everything in one folder' project into a clearer structure.
3Pick a structure and apply it consistently — consistency matters more than the specific choice.