## TLDR - **Flat structure** — best for prototypes and learning projects under 15 files - **Type-based structure** — group by file type: components, hooks, utils; good for simple apps - **Feature-based structure** — group by feature or domain; best for most production apps - **Atomic Design** — break UI into atoms, molecules, organisms; best for design systems - **Bulletproof React** — strict feature-based structure with defined folders for every concern; best for large teams

## Which Structure Should You Use Before diving into each one, here is the quick answer most people are looking for. Pick based on where your project is today, not where you hope it will be in a year. | Project size | Recommended structure | |---|---| | Prototype or side project | Flat or type-based | | Solo founder or 1 to 3 developers | Feature-based | | Team of 4 or more | Feature-based or Bulletproof React | | Building a component library | Atomic Design | | Large enterprise app | Bulletproof React or domain-based monorepo | The one rule that applies at every size: do not over-engineer upfront. A structure that is too complex for where you are today will slow you down more than a slightly messy one. You can always refactor a flat structure into feature folders in an afternoon. Unwinding a premature monorepo takes weeks. Now here is a full breakdown of each approach.

## React Project Structure Best Practices: The Core Idea There is no single correct way to structure a React project. The right structure depends on your project size, team size, and how quickly the codebase is growing. A structure that works for a solo founder building a SaaS is overkill for a weekend project and not enough for a team of twenty. Each approach in this guide is a natural evolution of the previous one. You do not need to pick one and commit forever. Start simple and evolve as the codebase tells you it needs more structure. All examples use TypeScript.

## 1. Flat Structure **Best for:** Prototypes, learning projects, anything under 15 files The simplest structure is no structure at all. Everything lives in `src/` and you create files as you need them. ``` src/ App.tsx Button.tsx Header.tsx useAuth.ts utils.ts types.ts main.tsx ``` This works fine up to around 10 to 15 files. The moment you go past that, you will notice the problem: you open `src/` and see a wall of unrelated files. A `Button` component sits next to a `useWebSocket` hook sits next to a date formatting utility. There is no visual hierarchy to tell you what belongs together. Here is what a breaking point looks like in practice. You want to work on the authentication flow. In a flat structure you end up scanning the entire file list looking for `useAuth.ts`, `AuthContext.tsx`, `LoginForm.tsx`, and `validatePassword.ts` — they are all there, scattered between unrelated files. You spend more time finding things than writing code. **When to move on:** When you have more than 15 files in `src/` and you are spending time scanning to find what you need.

## 2. Type-Based Structure **Best for:** Small to medium apps, solo developers, simple projects The next step is grouping files by what they are — components together, hooks together, utilities together. This is the structure you will see in most tutorials and starter templates. ``` src/ components/ Button.tsx Header.tsx Modal.tsx NavBar.tsx LoginForm.tsx CustomerInvoice.tsx DashboardChart.tsx hooks/ useAuth.ts useFetch.ts useLocalStorage.ts useSubscription.ts utils/ formatDate.ts formatCurrency.ts validateEmail.ts types/ index.ts pages/ Home.tsx Dashboard.tsx Settings.tsx context/ AuthContext.tsx ThemeContext.tsx assets/ logo.svg App.tsx main.tsx ``` This is clean and easy to navigate for small apps. Every developer knows where to look for a hook or a utility. The problem becomes visible as the app grows. Look at the `components/` folder above. `Button` and `LoginForm` and `CustomerInvoice` are all in there together. They have nothing to do with each other — one is a reusable UI primitive, one is a feature-specific form, one is a billing component. To work on the auth feature you need files from `components/`, `hooks/`, `context/`, and `utils/`. All of that is split across four separate folders. The folder structure is organized by what files are, not by what they do together. **Pros:** Simple, easy to explain, no upfront decisions about features **Cons:** `components/` becomes a dumping ground as the app grows, related files are spread across multiple folders, hard to work on a single feature without jumping around, deleting a feature means hunting through every folder **When to move on:** When you find yourself opening three or four different folders just to work on one feature, or when `components/` has more than 20 to 30 files.

## 3. Feature-Based Structure **Best for:** Most production apps, SaaS products, growing teams Feature-based structure is where most experienced React developers land. Instead of grouping by file type, you group by what the code does. Everything related to authentication lives in `features/auth/`. Everything related to billing lives in `features/billing/`. Each feature folder owns its components, hooks, utils, types, and API calls. ``` src/ features/ auth/ components/ LoginForm.tsx SignupForm.tsx hooks/ useAuth.ts useSession.ts utils/ validatePassword.ts types.ts index.ts billing/ components/ PricingTable.tsx InvoiceList.tsx hooks/ useSubscription.ts api/ billing.ts types.ts index.ts dashboard/ components/ DashboardHeader.tsx MetricsCard.tsx hooks/ useDashboardData.ts types.ts index.ts components/ Button.tsx Input.tsx Modal.tsx Dropdown.tsx hooks/ useDebounce.ts useClickOutside.ts utils/ formatDate.ts formatCurrency.ts types/ index.ts context/ ThemeContext.tsx pages/ index.tsx dashboard.tsx settings.tsx App.tsx main.tsx ``` The key distinction is that `components/` at the top level is now only for truly reusable, generic UI components — things like Button, Input, and Modal that are used across many features. Feature-specific components like `LoginForm` or `PricingTable` live inside their feature folder. Each feature folder has an `index.ts` that acts as the public API for that feature. Code outside the feature only imports from the index, never from internal files directly: ```ts // Good — imports from the public API import { LoginForm } from "@/features/auth"; // Bad — reaching into internals import { LoginForm } from "@/features/auth/components/LoginForm"; ``` This boundary matters. It means you can reorganize the internals of a feature without breaking anything outside it. It also means deleting a feature is clean — one folder, one removal, and the compiler tells you exactly what depended on it. **Feature boundary rules:** Features do not import from each other directly. If two features need the same thing, that thing moves up to the top-level shared folders. Shared code at the top level does not import from features. Pages compose features together — they are the only place where multiple features meet in the same file. A simple test: pick one feature folder and imagine deleting it. If the only things that break are the pages that use it and a clean TypeScript error at the import boundary, your structure is healthy. If half the app breaks, your boundaries leaked. **Pros:** Easy to navigate, features are self-contained, scales well, works naturally with teams where different people own different features, deleting a feature is clean **Cons:** Requires some judgment about what counts as a feature, some edge cases about where shared code lives **When to move on:** When your `features/` folder has 20 or more entries and you can see clear clusters forming around business domains.

## 4. Atomic Design **Best for:** Design systems, component libraries, UI-heavy apps Atomic Design was introduced by Brad Frost and breaks UI components into five levels based on complexity and composability: - **Atoms** — the smallest building blocks: Button, Input, Label, Icon - **Molecules** — simple combinations of atoms: FormField (Label + Input), SearchBar (Input + Button) - **Organisms** — complex UI sections: Header (NavBar + Logo + Button), ProductCard (Image + Text + Button) - **Templates** — page layouts without real content: DashboardTemplate, AuthTemplate - **Pages** — templates with real content wired up ``` src/ components/ atoms/ Button/ Button.tsx Button.test.tsx Button.stories.tsx Input/ Input.tsx Input.test.tsx Icon/ Icon.tsx molecules/ FormField/ FormField.tsx FormField.test.tsx SearchBar/ SearchBar.tsx SearchBar.test.tsx NavItem/ NavItem.tsx organisms/ Header/ Header.tsx Header.test.tsx ProductCard/ ProductCard.tsx Footer/ Footer.tsx templates/ DashboardTemplate/ DashboardTemplate.tsx AuthTemplate/ AuthTemplate.tsx pages/ Home.tsx Dashboard.tsx ``` Atomic Design is genuinely useful when you are building a component library or a design system shared across multiple apps. The hierarchy gives every component a clear contract and forces you to think about reusability at every level. It pairs especially well with Storybook, where the atoms-to-organisms hierarchy maps directly to how you would organize stories. The downside is that it does not map well to business logic. Where does a `CustomerInvoice` component go? It is too complex to be a molecule but not quite a full organism. These classification debates slow teams down without adding real value for logic-heavy applications. The eternal question — "is a SearchBar a Molecule or an Organism?" — has no right answer, and the time spent on it is rarely worth it. **Pros:** Excellent for design systems, clear hierarchy, forces reusability, pairs well with Storybook **Cons:** Classification becomes a debate, does not map naturally to business features, overkill for most product apps **Best used alongside:** Feature-based structure, where Atomic Design governs your shared `components/` folder and feature-based structure governs your business logic. The two are not mutually exclusive.

## 5. Bulletproof React **Best for:** Large teams, enterprise apps, projects where consistency matters more than flexibility Bulletproof React is an opinionated structure from Alan Alickovic that has become one of the most referenced starting points for large-scale React applications. It is a strict version of feature-based structure with a defined folder for every concern so that there is never any ambiguity about where something belongs. ``` src/ assets/ images/ fonts/ components/ ui/ Button.tsx Input.tsx Modal.tsx layouts/ MainLayout.tsx AuthLayout.tsx config/ index.ts features/ auth/ api/ login.ts register.ts components/ LoginForm.tsx SignupForm.tsx hooks/ useAuth.ts useLogin.ts stores/ authStore.ts types/ index.ts utils/ validateToken.ts index.ts billing/ api/ getSubscription.ts createCheckout.ts components/ PricingTable.tsx InvoiceList.tsx hooks/ useSubscription.ts stores/ billingStore.ts types/ index.ts index.ts hooks/ useDebounce.ts useClickOutside.ts lib/ axios.ts queryClient.ts providers/ AppProvider.tsx QueryProvider.tsx routes/ index.tsx protected.tsx stores/ notificationsStore.ts testing/ mocks/ utils/ types/ index.ts utils/ formatDate.ts formatCurrency.ts ``` The key additions over a basic feature-based structure worth explaining: **`lib/`** holds pre-configured wrappers around third-party libraries. Instead of importing axios directly and configuring it in every file that needs it, you create one `lib/axios.ts` that exports a configured instance with your base URL, auth headers, and interceptors already set up. The same goes for your React Query client — `lib/queryClient.ts` exports the one configured instance your whole app uses. The rule is: third-party libraries get wrapped in `lib/`, your own code goes everywhere else. **`providers/`** is separate from `context/` because providers are React components and context is the data layer they expose. `AppProvider.tsx` might compose five or six context providers together and wrap the whole app. Keeping providers separate from the context definitions keeps both files smaller and easier to reason about. **`stores/`** inside each feature holds state management code (Zustand, Redux slices) scoped to that feature. The top-level `stores/` holds global state that does not belong to any single feature, like a notifications store or a global UI state store. **`testing/`** centralizes mocks, test factories, and test utilities that are shared across multiple test files. Individual test files still live next to the code they test — this folder is only for the shared testing infrastructure. **Pros:** Very consistent, easy to onboard new developers, every concern has a home, widely understood in the React community **Cons:** More boilerplate upfront, can feel rigid for small projects, some teams fight the structure when their use case does not fit neatly **When to use:** When you have four or more developers who need to move independently without stepping on each other, or when consistency and onboarding speed matter more than flexibility.

## Next.js App Router Folder Structure If you are using Next.js, the App Router changes the structure in a few important ways that none of the patterns above fully account for. The `app/` directory handles routing via the file system. Pages, layouts, loading states, and error boundaries all live here as `page.tsx`, `layout.tsx`, `loading.tsx`, and `error.tsx` files. This is separate from your feature and component code. Here is how a feature-based structure maps to a Next.js App Router project: ``` src/ app/ page.tsx (home page) layout.tsx (root layout) dashboard/ page.tsx layout.tsx auth/ login/ page.tsx signup/ page.tsx (protected)/ (route group, no URL segment) billing/ page.tsx features/ auth/ components/ LoginForm.tsx (Client Component) SignupForm.tsx hooks/ useAuth.ts actions/ login.ts (Server Actions) logout.ts types.ts index.ts billing/ components/ PricingTable.tsx actions/ createCheckout.ts (Server Actions) queries/ getSubscription.ts (server-side data fetching) types.ts index.ts dashboard/ components/ MetricsCard.tsx queries/ getDashboardData.ts types.ts index.ts components/ Button.tsx Input.tsx Modal.tsx lib/ db.ts auth.ts utils/ formatDate.ts ``` A few things specific to Next.js App Router worth noting: **Server Components vs Client Components** — By default, all components in the App Router are Server Components. They run on the server, have no interactivity, and can fetch data directly. Client Components need a `"use client"` directive at the top. A good rule of thumb is to keep Server Components in `queries/` and data fetching files, and Client Components in `components/` inside each feature. The component is a Client Component if it uses state, effects, or browser APIs. **Server Actions** — In Next.js 16, Server Actions replace what used to be API routes for mutations. They live in `actions/` inside each feature folder with a `"use server"` directive. Keep them thin — validate input, call a service or database function, revalidate cache. The actual business logic lives elsewhere. **`app/` is for routing only** — Your `app/` directory should contain almost no business logic. Pages import from features, features contain the logic. Pages are thin wrappers that compose feature components together and pass route params down. **Route groups** — Wrap routes in parentheses like `(protected)/` to apply a shared layout without adding a URL segment. Useful for auth-protected routes that share a layout without changing the URL structure.

## Migrating from Type-Based to Feature-Based If you have an existing project using type-based structure and you want to move to feature-based, do it gradually. Do not try to restructure everything in one pull request. **Step 1 — Identify your features.** Look at your `pages/` folder. Each page usually maps to one or two features. Write them down: auth, billing, dashboard, settings. **Step 2 — Create `features/` alongside your existing folders.** Do not delete anything yet. **Step 3 — Migrate one feature at a time.** Start with the most self-contained feature — usually auth. Move its components, hooks, and utils into `features/auth/`. Create an `index.ts` and update imports. Run the app. Fix what broke. **Step 4 — Repeat for each feature.** After a few features are migrated, your old `components/` folder will shrink down to just the genuinely reusable UI components. That is the correct end state. **Step 5 — Clean up.** Once all features are migrated, what remains in `components/`, `hooks/`, and `utils/` at the top level should only be code that is genuinely shared across multiple features. The migration takes longer than a full rewrite but is safer for a production codebase. Each feature migration is a small, reviewable change.

## Tips That Apply to Every Structure **Use absolute imports.** Relative paths like `../../../components/Button` break every time you move a file. Configure path aliases in `tsconfig.json`: ```json { "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./src/*"] } } } ``` For Next.js this works out of the box. For Vite, add the alias to `vite.config.ts` as well: ```ts // vite.config.ts import path from "path"; import { defineConfig } from "vite"; export default defineConfig({ resolve: { alias: { "@": path.resolve(__dirname, "./src"), }, }, }); ``` **Use kebab-case for folder and file names.** `customer-list.tsx` not `CustomerList.tsx` for files. PascalCase is for the component name inside the file, not the file itself. This avoids case-sensitivity bugs when moving between macOS and Linux environments. **Keep index files minimal.** If you use `index.ts` barrel files, only export the public API of a folder. Do not re-export everything — it makes tree shaking harder for your bundler and leaks implementation details. **Put tests next to the code they test.** `Button.test.tsx` next to `Button.tsx` is easier to maintain than a separate `__tests__/` folder. You see immediately when a component has no test, and moving a file also moves its test. **Do not nest more than two or three levels deep.** Deep nesting makes paths long and refactoring painful. If you find yourself at `features/billing/components/invoice/list/item.tsx`, something has gone wrong. Flatten it.

## Managing Your React Project in One Place No matter which folder structure you use, you still need to track what you are building, what is deployed, and how it is performing. If you are a solo developer or small team, AdeptDev consolidates your Kanban board, Vercel deployment tracking, and analytics into one dashboard so you can manage your project without switching between five tabs. Try it free for 7 days at [adeptdev.io](https://adeptdev.io).