In Next.js the folder tree of app/ is the list of your web addresses, so the default structure groups code by page, not by business area. This post shows the agreements teams have reached to keep large Next.js apps split into separate, scalable domains, with folder examples for each one.
This reflects the state of Next.js and its tools in early 2025 (Next.js 15 with the App Router). Folder conventions and the tools that check them change between major versions, so check the current documentation before you copy a configuration.
The gist
Keep every file inside app/ down to a few lines that read the request and call business code, and put that business code in one folder per business area, outside the app/ folder.
- Give each business area (payments, accounts, catalogue) one folder and a small set of entry files. Pages import only from those entry files (one for code the browser may use, one for code that must stay on the server), so the area can change inside without breaking pages.
- Let business areas meet only in the page. One area should not import another; the page imports both and puts them together.
- Make the linter fail on a wrong import. A linter is a tool that checks code for rule breaks on every change. Rules written only in documentation are easy to break; rules the linter checks are not.
- Pick the lightest structure that works: feature folders for one team, one module per business area for several teams, separate packages when several apps share code, and separate apps only when teams must deploy on their own.
The mental model: two maps, joined by thin files
A growing web app has two different maps. The first map is the list of addresses a visitor can open: /checkout, /account/invoices, /admin/refunds. The second map is the list of business areas the company cares about: payments, user accounts, the product catalogue, search. The two maps don't line up. One business area shows up on many addresses, and one address often shows parts of several business areas.
Next.js builds the first map out of folders. That is useful, but it tempts you to put all code into that same tree, so the second map disappears. The approaches that scale all make the same agreement: the address tree stays thin, the business areas live somewhere else, and each page file only connects the two.
The rest of this post goes in this order: why the default tree stops scaling, what tools Next.js gives you, the shared agreement, three ways to organise the business areas, how to enforce the rules with a linter, and when to split into several packages or several apps.
Why the default structure stops scaling
In the App Router (the routing system in the app/ folder, introduced in Next.js 13), every folder becomes a part of the URL (Uniform Resource Locator, the web address) by default. A folder becomes a public page only when it contains a page.tsx file; an API (Application Programming Interface) endpoint needs a route.ts file. Special files like layout.tsx, loading.tsx and error.tsx sit next to the page and control how it renders.
The problem is what happens to everything else: the components, the data access, the validation, the business rules. Without a plan, they end up in one of two places. Either they go next to the page that first needed them, or into large global folders like components/ and lib/. Here is a typical tree after a year of work:
app/
├── checkout/
│ ├── page.tsx
│ ├── PaymentForm.tsx
│ ├── useCart.ts
│ └── stripe.ts
├── account/
│ └── invoices/
│ ├── page.tsx
│ └── InvoiceTable.tsx ← formats money like checkout, but its own copy
├── admin/
│ └── refunds/
│ └── page.tsx ← imports ../../checkout/stripe.ts
└── api/
└── webhooks/
└── stripe/
└── route.ts ← imports ../../../checkout/stripe.ts
components/ ← 140 files, no owner
lib/ ← utils.ts, helpers.ts, api.ts
Payments is one business area, but its code is now in four folders under app/ and probably in lib/ too. The diagram below shows how one area spreads across the address tree.
This causes three practical problems:
- Nobody owns the code. A team that owns payments can't point to one folder and say "this is ours". Code review rules and ownership files (like GitHub's
CODEOWNERS) need a folder to point at. - A change in one place breaks another. When the refunds page imports a file from the checkout folder, a change to checkout can break refunds. Nothing in the structure warns you.
- Moving a page means moving logic. If the product team renames
/checkoutto/cart/pay, the payment code moves with it, because it lived inside the address folder.
None of this is a bug in Next.js. The framework only decides how addresses work. It leaves the rest to you.
What Next.js gives you to work with
The Next.js documentation on project structure says it directly: Next.js is "unopinionated" about how you organise your files. It gives you a few tools and lists three strategies, but picks none of them for you.
The tools are these:
- Safe colocation. Files inside
app/are not public unless they are apageorroutefile. So you can put a component next to a page without exposing it as an address. - Private folders. A folder whose name starts with an underscore, like
_components, is ignored by the router, together with everything inside it. - Route groups. A folder name in brackets, like
(shop), groups pages and can give them a shared layout, but does not appear in the address.app/(shop)/checkout/page.tsxis still/checkout. - The
src/folder. You can moveapp/intosrc/app/, so application code and configuration files at the project root stay apart. - Path aliases. A setting in
tsconfig.jsonlets you write@/modules/paymentsinstead of../../../modules/payments.
The three strategies the documentation lists are: store project files outside of app, store them in top-level folders inside app, or split them by feature or route. The rest of this post builds on the first one, and here is why. Route groups and private folders help you organise pages, but a route group is still a group of addresses. A business area like payments is not a group of addresses. So it should not live in the address tree at all.
The shared agreement: thin routes, thick modules
Every structure in the next sections follows one rule: a file inside app/ only reads the request, calls code from a business module, and renders the result. It contains no business rules, no database queries and no complex components of its own. People call these "thin routes" or "thin pages".
Here is a thin page for an invoice detail screen. In Next.js 15, params is a promise, so the page awaits it before reading the invoice's identifier (id).
// src/app/(account)/account/invoices/[id]/page.tsx
import { notFound } from 'next/navigation';
import { getInvoice, InvoiceDetail } from '@/modules/billing';
export default async function InvoicePage({
params,
}: {
params: Promise<{ id: string }>;
}) {
const { id } = await params;
const invoice = await getInvoice(id);
if (!invoice) notFound();
return <InvoiceDetail invoice={invoice} />;
}
The page knows about the address ([id], notFound()). The billing module knows how invoices work. If the address changes tomorrow, you move this short file and nothing else.
Thin routes also give each business module one entry point. The module exposes what pages may use through a single index.ts file, often called its public API (the list of things other code is allowed to import). Everything else in the module is private.
// src/modules/billing/index.ts
export { getInvoice, listInvoices } from './server/queries';
export { refundPayment } from './server/actions';
export { InvoiceDetail } from './ui/InvoiceDetail';
export type { Invoice } from './domain/invoice';
With this agreement in place, the remaining question is how to organise the code behind those entry points. The community has settled on three main answers.
Pattern 1: feature folders (Bulletproof React)
The simplest answer is a features/ folder with one subfolder per business area. The best-known version is Bulletproof React, an open-source reference architecture by Alan Alickovic. Its repository includes a Next.js App Router example (apps/nextjs-app) next to a plain React one.
The Bulletproof React project structure puts shared code in top-level folders and business code in features/. Shared code here means things with no business meaning, such as UI (user interface) pieces like buttons and modals:
src/
├── app/ ← Next.js routes: thin pages and layouts
├── components/ ← shared UI pieces: Button, Modal
├── config/
├── features/
│ ├── billing/
│ │ ├── api/ ← data fetching for this feature
│ │ ├── components/
│ │ ├── hooks/
│ │ ├── types/
│ │ └── utils/
│ ├── catalog/
│ └── accounts/
├── hooks/ ← shared hooks
├── lib/ ← configured libraries: database client, auth client
├── stores/
├── testing/
├── types/
└── utils/
Two rules make this structure work:
- Code flows in one direction. The documentation puts it as "shared → features → app": shared folders can be used by anything, features can use shared code, and the
app/folder can use both. A shared component never imports a feature. - Features don't import each other. The documentation says it "might not be a good idea to import across the features". When a page needs billing and accounts, the page in
app/imports both and puts them together. The page is the one place where business areas meet.
The diagram shows which folders may import which.
Feature folders are easy to explain to a new developer, and they fit most single-team apps. Their weak point is that "feature" is vague. Is "invoice table" a feature, or is "billing"? Teams answer that question differently, and over time features/ can fill up with small folders that are really components.
Pattern 2: Feature-Sliced Design
Feature-Sliced Design (FSD) answers the "what is a feature?" question with a fixed set of layers. It is a full methodology with its own documentation, its own linter and a guide for Next.js.
FSD sorts code into seven layers, from the most specific to the most general:
| Layer | What it holds | Example |
|---|---|---|
app | Setup for the whole app: providers, global styles | the theme provider |
processes | Flows across several pages (deprecated, not used in new projects) | — |
pages | One full screen each | the invoice detail screen |
widgets | Large, self-contained blocks of a page | the account sidebar |
features | One user action that brings value | "refund a payment" |
entities | Business things the app works with | invoice, user |
shared | Reusable code with no business meaning | buttons, the client that calls the server |
Each layer is split into slices, one per business area (entities/invoice, features/refund-payment). The main rule: a slice can only import from slices on layers strictly below its own. A feature can use entities and shared code, but never another feature or a page.
This creates a naming conflict. FSD has an app layer and a pages layer, and Next.js uses folders with exactly those names for routing. The FSD guide solves it like this: the Next.js app/ folder stays at the project root, the FSD layers live in src/, and the two FSD layers are renamed to _app and _pages so the router ignores them.
app/ ← Next.js routing only
├── layout.tsx
└── account/
└── invoices/
└── [id]/
└── page.tsx ← one line: re-exports the FSD page
src/
├── _app/ ← FSD app layer: providers, global styles
├── _pages/
│ └── invoice-detail/
│ ├── ui/InvoiceDetailPage.tsx
│ └── index.ts
├── widgets/
│ └── account-sidebar/
├── features/
│ └── refund-payment/
│ ├── ui/RefundButton.tsx
│ ├── api/refund.ts
│ └── index.ts
├── entities/
│ ├── invoice/
│ │ ├── model/invoice.ts
│ │ ├── ui/InvoiceSummary.tsx
│ │ └── index.ts
│ └── user/
└── shared/
├── ui/
└── api/
The route file becomes the thinnest possible version of a thin route. It only re-exports the page and its metadata from the FSD layer:
// app/account/invoices/[id]/page.tsx
export { InvoiceDetailPage as default, metadata } from '@/_pages/invoice-detail';
FSD gives the clearest answer to "where does this file go?", and it comes with tooling, such as the steiger linter, that checks the rules. The cost is learning. A team needs some weeks to agree on what is an entity and what is a feature, and small apps can feel like they have more layers than code.
Pattern 3: domain modules and vertical slices
The third answer starts from the business, not from the frontend. Each business area becomes one module that holds everything it needs: its components, its server code, its rules and its tests. This mixes two older ideas from general software design.
The first idea is Robert C. Martin's Screaming Architecture (2011): the top-level folders of a project should tell you what the system does, not which framework it uses. A health-care app should look like a health-care app, not like a Rails app (Rails is a web framework for the Ruby language). The second is Jimmy Bogard's Vertical Slice Architecture (2018), which groups code by request instead of by technical layer, and sums it up as "minimize coupling between slices, and maximize coupling in a slice".
In a Next.js app, this usually looks like a modules/ folder (some teams call it domains/) next to app/:
src/
├── app/ ← thin routes only
│ ├── (shop)/
│ │ └── checkout/page.tsx
│ ├── (account)/
│ │ └── account/invoices/[id]/page.tsx
│ ├── admin/refunds/page.tsx
│ └── api/webhooks/stripe/route.ts
├── modules/
│ ├── billing/
│ │ ├── domain/ ← pure rules: invoice.ts, money.ts
│ │ ├── server/ ← queries.ts, actions.ts, stripe.ts
│ │ ├── ui/ ← InvoiceDetail.tsx, PaymentForm.tsx
│ │ ├── billing.test.ts
│ │ ├── index.ts ← public API, safe anywhere
│ │ └── server.ts ← public API, server code only
│ ├── catalog/
│ └── accounts/
└── shared/
├── ui/ ← design system pieces
└── lib/ ← database client, logger
Inside each module, three subfolders separate code by where it runs:
domain/holds plain TypeScript with no React and no framework imports: how a refund is calculated, when an invoice is overdue. This is the easiest code to test.server/holds code that must only run on the server: database queries and Server Actions (functions marked'use server'that a form or button can call from the browser).ui/holds the React components, both Server Components (the default in the App Router, rendered on the server) and Client Components (marked'use client', sent to the browser).
The server/ folder needs one more protection. A Client Component that imports a database query by mistake would try to send that code to the browser. The Next.js documentation recommends the server-only package for this. If a file imports it and a Client Component imports that file, the build fails.
// src/modules/billing/server/queries.ts
import 'server-only';
import { db } from '@/shared/lib/db';
import type { Invoice } from '../domain/invoice';
export async function getInvoice(id: string): Promise<Invoice | null> {
return db.invoice.findUnique({ where: { id } });
}
This has a consequence for the public API from earlier. A Client Component that imports anything from @/modules/billing also loads every file that index.ts re-exports, including queries.ts, so the build fails. The usual fix is to give the module two entry files: index.ts for code that is safe in the browser, and server.ts for code that must stay on the server.
// src/modules/billing/index.ts: safe to import anywhere
export { refundPayment } from './server/actions';
export { InvoiceDetail } from './ui/InvoiceDetail';
export type { Invoice } from './domain/invoice';
// src/modules/billing/server.ts: only for Server Components and route files
export { getInvoice, listInvoices } from './server/queries';
The thin invoice page from earlier then imports getInvoice from @/modules/billing/server and InvoiceDetail from @/modules/billing. A Server Action like refundPayment can stay in index.ts, because the 'use server' marker makes the browser receive only a reference to the function, not its code.
Look again at the address tree in this example. It still has four payment-related routes, but each of them is now a few lines that import from @/modules/billing or @/modules/billing/server. Payments has one owner, one folder and one public API. The diagram compares the two layouts.
Domain modules fit apps with several teams, because each module can match a team. Their weak point is the opposite of FSD's: there is less structure inside a module, so two modules can look quite different unless the team agrees on the subfolders.
Making the rules stick: lint the boundaries
All three patterns depend on import rules. Rules that exist only in a README file are easy to break when a team is in a hurry. The teams that keep their structure for years make the linter fail when someone crosses a boundary. There are two common tools for this in a single Next.js app. Both are plugins for ESLint, the most widely used linter for JavaScript and TypeScript.
The first is the import/no-restricted-paths rule from eslint-plugin-import. It is the one the Bulletproof React documentation uses. Each zone names a target (the files being restricted) and a from (the files they may not import). This configuration stops features from importing each other, stops features from importing routes, and stops shared code from importing either:
// eslint.config.mjs (part of the rules object)
'import/no-restricted-paths': [
'error',
{
zones: [
// billing may not import other features
{ target: './src/features/billing', from: './src/features', except: ['./billing'] },
{ target: './src/features/catalog', from: './src/features', except: ['./catalog'] },
// features may not import routes
{ target: './src/features', from: './src/app' },
// shared code may not import features or routes
{
target: ['./src/components', './src/hooks', './src/lib', './src/utils'],
from: ['./src/features', './src/app'],
},
],
},
],
You need one zone per feature for the first rule, which gets long as the app grows. The second tool, eslint-plugin-boundaries, is built for this case. You describe each kind of folder once as an element type, and then write rules between types. This example follows the domain-modules layout from the previous section:
// eslint.config.mjs (part of the config object)
settings: {
'boundaries/elements': [
{ type: 'app', pattern: 'src/app/*' },
{ type: 'module', pattern: 'src/modules/*' },
{ type: 'shared', pattern: 'src/shared/*' },
],
},
rules: {
// which element types may import which
'boundaries/element-types': [
'error',
{
default: 'disallow',
rules: [
{ from: 'app', allow: ['app', 'module', 'shared'] },
{ from: 'module', allow: ['shared'] },
{ from: 'shared', allow: ['shared'] },
],
},
],
// other code may only enter a module through index.ts or server.ts
'boundaries/entry-point': [
'error',
{
default: 'disallow',
rules: [
{ target: ['module'], allow: ['index.ts', 'server.ts'] },
{ target: ['shared'], allow: '**' },
],
},
],
},
The element-types rule only checks imports between elements, so files inside the same module can still import each other freely. The entry-point rule makes index.ts and server.ts the only way into a module, so nothing outside it can depend on its private files. (Later major versions of the plugin renamed some of these rules, so check the README for the version you install.)
When one app is not enough: packages and zones
Folder rules and lint rules work inside one Next.js app. At some size, teams want a stronger separation: separate test runs, separate versions, or code shared between two apps. The next step is a monorepo, one repository that holds several apps and packages.
The Turborepo documentation recommends a split that most JavaScript monorepos now follow: apps/ for applications and services, and packages/ for everything else. Vercel's own next-forge template uses this layout for Next.js. In a domain-driven monorepo, each business module from the previous sections can become its own package:
apps/
├── web/ ← the public Next.js site
├── admin/ ← a second Next.js app for staff
└── docs/
packages/
├── billing/ ← was src/modules/billing
│ ├── src/
│ └── package.json ← name: "@acme/billing"
├── catalog/
├── accounts/
├── ui/ ← shared design system
├── db/
└── eslint-config/
Now a boundary is also a package boundary. Each package lists the packages it depends on in its package.json. With a strict package manager such as pnpm, code can only import packages from that list, so an undeclared dependency fails at install or build time instead of in review. Nx adds one more level: you give each project tags like scope:billing or type:ui, and the @nx/enforce-module-boundaries lint rule checks a list of allowed tag pairs (depConstraints). For example, a project tagged scope:billing may only depend on projects tagged scope:billing or scope:shared.
The last step goes further still. With multi-zones, one website is served by several separate Next.js apps, each owning a set of addresses (for example /shop/* and /blog/*). The main app forwards requests to the other zones with rewrites in next.config.js, and each zone uses assetPrefix so its JavaScript and CSS (Cascading Style Sheets) files don't collide with the others. Each zone can be built and deployed on its own. The cost is that moving between zones is a full page load, and links across zones must be plain <a> tags instead of Next.js's <Link>. Use multi-zones when teams need to deploy separately, not just to keep code tidy.
Choosing a structure
The options above aren't competitors so much as steps. Here is each one in a sentence:
- Feature folders are one
features/folder with one-way import rules. They are quick to adopt and fit one team. - Feature-Sliced Design is seven fixed layers with a strict import order. It is the most precise and needs the most learning.
- Domain modules are one folder per business area, with a public API and a domain/server/UI split. They fit several teams in one app.
- Monorepo packages turn each module into a package with its own dependencies, checked by the package manager and tools like Nx.
- Multi-zones split one website into several apps that deploy on their own.
The table compares them on the questions that usually decide.
| Question | Feature folders | Feature-Sliced Design | Domain modules | Monorepo packages | Multi-zones |
|---|---|---|---|---|---|
| How easy is it to start? | |||||
| Is it clear where a new file goes? | |||||
| Can each team own one folder? | |||||
| What enforces the boundaries? | |||||
| Can teams deploy on their own? | |||||
| Extra cost at run time |
Start with the lightest structure that gives every business area one folder and one public API, and move to the next step only when a real problem pushes you. The decision tree below shows the usual path.
A last point: moving to the next step is cheap if the first step is right. A modules/billing folder with clean entry files and lint rules can become packages/billing in a few hours. A payment flow spread across four route folders can't, because first someone has to find all of it. Whatever you choose, the thin route is the part that matters most. It is what keeps your address tree free to change while your business code stays where it is.
References
- Vercel, Project structure and organization — Next.js documentation
- Vercel, Server and Client Components — Next.js documentation
- Vercel, Multi-zones — Next.js documentation
- Alan Alickovic, Bulletproof React — GitHub
- Alan Alickovic, Project Structure — Bulletproof React docs
- Usage with Next.js — Feature-Sliced Design
- Layers — Feature-Sliced Design reference
- Robert C. Martin, Screaming Architecture — The Clean Code Blog, 2011
- Jimmy Bogard, Vertical Slice Architecture, 2018
- Javier Brea, eslint-plugin-boundaries — GitHub
- Vercel, Structuring a repository — Turborepo documentation
- Vercel, next-forge — GitHub
- Nx, Enforce Module Boundaries — Nx documentation
