Structuring a large app

One tea shop, two ways to sort its files

The tea shop has grown. It has teas, reviews, a cart, accounts, and a team for each. Next.js decides what the files in app do, and leaves the rest of your files to you (Project structure showed where each kind goes). In a small app, any order works. In a large one, where a file lives decides how many folders you open for one change, and whether two teams end up changing the same files. Here are the shop's teas and reviews, sorted the way many apps start, by kind of file:

app/
  reviews/
    page.tsx
  teas/
    page.tsx
  layout.tsx
components/
  add-to-cart.tsx
  card.tsx
  review-list.tsx
  tea-card.tsx
lib/
  format.ts
  reviews.ts
  teas.ts

components holds every component and lib every other module. The teas are four files: components/tea-card.tsx, components/add-to-cart.tsx, lib/teas.ts and lib/format.ts. They sit in two folders, between the reviews' files. With ten features, each folder would hold dozens of files from all of them. Now the same files, sorted by feature: a part of the shop that a visitor would name, like the teas or the reviews.

app/
  reviews/
    page.tsx
  teas/
    page.tsx
  layout.tsx
features/
  reviews/
    dal.ts
    review-list.tsx
  teas/
    add-to-cart.tsx
    dal.ts
    format.ts
    tea-card.tsx
ui/
  card.tsx

features/teas holds everything about teas: the card, the button, the module that reads the teas, and a price helper. features/reviews does the same for reviews. ui/card.tsx is the one component both features use, so it sits below them, in a folder for shared UI. And app holds only routes. This version is a real Next.js 16.4.3 project, built with next build and run with next start; what it sent back was recorded. Click a file in the tree to read it.

1import TeaCard from "@/features/teas/tea-card";2import { getTeas } from "@/features/teas/dal";3 4export default async function TeasPage() {5  const teas = await getTeas();6  return (7    <main>8      <h1>Teas</h1>9      {teas.map((tea) => (10        <TeaCard key={tea.id} tea={tea} />11      ))}12    </main>13  );14}

In app/teas/page.tsx, line 1 imports TeaCard from @/features/teas/tea-card, and line 2 imports getTeas from @/features/teas/dal. Line 5 waits for the teas, and lines 9 to 11 draw a card for each. The page is short: it puts the feature's parts together, and the feature does the work. The Browser tab shows the two teas with their buttons. The Terminal tab lists the routes: ○ /_not-found, ○ /reviews and ○ /teas, all prerendered as static content. In the Network tab, /features/teas/tea-card answered 404: a folder outside app is never part of an address.

By kind of file, by feature, or beside the routes

Next.js's docs call the framework unopinionated about how you organize your project, and describe a few common ways. Three of them, for the same shop. Each row is one layout: where the teas' files go, and what that gives you.

The third layout keeps each route's files in its own folder in app, next to its page.tsx. That's called colocation, and its tree looks like this:

app/
  _ui/
    card.tsx
  reviews/
    dal.ts
    page.tsx
    review-list.tsx
  teas/
    add-to-cart.tsx
    dal.ts
    format.ts
    page.tsx
    tea-card.tsx
  layout.tsx

Each layout below is the same shop, built and run on its own. Before you click, guess: does any of them change the routes the build lists?

1import TeaCard from "@/features/teas/tea-card";2import { getTeas } from "@/features/teas/dal";3 4export default async function TeasPage() {5  const teas = await getTeas();6  return (7    <main>8      <h1>Teas</h1>9      {teas.map((tea) => (10        <TeaCard key={tea.id} tea={tea} />11      ))}12    </main>13  );14}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (4/4)  Finalizing page optimization ... Route (app)┌ ○ /_not-found├ ○ /reviews└ ○ /teas ○  (Static)  prerendered as static content

None did. All three builds list ○ /_not-found, ○ /reviews and ○ /teas, and the pages show the same teas and reviews. In the colocated layout, app/teas/tea-card.tsx sits right beside page.tsx, and /teas/tea-card still answered 404, like /teas/dal and /_ui/card. Next.js only gives an address to a folder with a page.tsx or a route.ts in it, and a private folder like _ui never gets one, whatever it holds (Route groups and private folders).

So pick the layout for the people who read the code, not for Next.js. Small apps do well by kind of file. When components and lib fill with files from every part of the shop, sort by feature. The layouts also mix: the docs describe keeping code that the whole app shares at the top and splitting the rest by route, and route groups, folders in round brackets like (shop), sort the routes themselves by section or by team without changing an address.

A data access module for each feature

Every feature reads data somewhere. Give each one a single server-only way in, here features/teas/dal.ts: the teas' data access layer, or DAL, the name Next.js's data security guide gives the code that every read of your data goes through. Here it's one file; in a bigger feature it can be several modules behind one entry file, each starting with import "server-only". Authorization and the data access layer built one for orders, with a check of who is asking in every function. Teas are public, so this one only reads and picks fields:

1import "server-only";2 3// A stand-in for the teas table. `cost` is what the shop pays: staff only.4const rows = [5  { id: "green", name: "Green tea", price: 4, cost: 1.2 },6  { id: "mint", name: "Mint tea", price: 3, cost: 0.9 },7];8 9export type Tea = { id: string; name: string; price: number };10 11export async function getTeas(): Promise<Tea[]> {12  return rows.map(({ id, name, price }) => ({ id, name, price }));13}14 

• Line 1, import "server-only", makes the build stop if a Client Component's code imports this file (Server-only code showed the error).
• Lines 4 to 7 stand in for the teas table. Each row has a cost, what the shop pays for the tea, which only staff may see.
• Line 9 names the shape the rest of the app gets: Tea, with an id, a name and a price.
• Line 12 returns those three fields and leaves cost behind. An object made only to carry data out of a layer like this is a DTO, a data transfer object.

With one way in for each feature, the questions "where are the teas read?" and "which fields can a page get?" each have one answer. features/reviews/dal.ts does the same for reviews, and leaves each reviewer's email behind. Not every file in the feature belongs in it, though. Each row is one piece of the teas feature, and the file it goes in:

The Add to cart button shows the price, so it needs formatPrice. Here are three versions of the teas feature. Before you click, guess which ones build.

1import TeaCard from "@/features/teas/tea-card";2import { getTeas } from "@/features/teas/dal";3 4export default async function TeasPage() {5  const teas = await getTeas();6  return (7    <main>8      <h1>Teas</h1>9      {teas.map((tea) => (10        <TeaCard key={tea.id} tea={tea} />11      ))}12    </main>13  );14}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (4/4)  Finalizing page optimization ... Route (app)┌ ○ /_not-found├ ○ /reviews└ ○ /teas ○  (Static)  prerendered as static content

What the build did in each version:

• The page imports it: the teas page is a Server Component, so dal.ts stays on the server. This is the overview's shop.
• The button imports a helper from it: someone put formatPrice in dal.ts, and the button imported it from there. The build stopped: 'server-only' cannot be imported from a Client Component module. (The first of its two messages mentions the Pages Router, which this app doesn't use.) The import trace under it starts with ./features/teas/dal.ts [Client Component Browser] and ./features/teas/add-to-cart.tsx [Client Component Browser]: a Client Component's imports go to the browser with it, the whole module, not only the function it uses.
• The button imports through a barrel: a barrel file is a file that only re-exports other files, so the rest of the app can import a feature from one place. This one, features/teas/index.ts, re-exports the whole feature, and line 2 re-exports dal.ts. The button imported only formatPrice, from @/features/teas, and the build stopped with the same error. This time the trace runs through ./features/teas/index.ts [Client Component Browser].

1export { default as AddToCart } from "./add-to-cart";2export { getTeas, type Tea } from "./dal";3export { formatPrice } from "./format";4export { default as TeaCard } from "./tea-card";5 

Line 1 re-exports the button, a Client Component, and line 2 the data module, which may only run on the server. When the button imports from this barrel, the compiler follows the barrel's imports to build the client's module graph, the list of modules the browser code depends on, and line 2 puts dal.ts in it. The server-only check looks at that graph, so the build stopped, although the button never uses getTeas. That's a separate question from how many bytes ship: a bundler may leave out exports nobody uses, but only when it can tell that dropping them changes nothing. Two fixes work: a client file imports the file it needs (./format), or a feature keeps no server-only module in a barrel that client code uses. The overview's shop has no barrel at all. Barrels can cost bytes too: Bundle size recorded a barrel of the shop's own files bringing a whole Markdown library to a page that only needed a button.

Shared UI: plain components and client leaves

Components that every feature uses, like a card, a button with the shop's colors, or a dialog, go in one shared folder, here ui/. A large app's shared components, with the rules for how they look, are often called its design system. Here is the shop's Card:

1import type { ReactNode } from "react";2 3export default function Card({ title, children }: { title: string; children: ReactNode }) {4  return (5    <article className="ui-card">6      <h2>{title}</h2>7      {children}8    </article>9  );10}11 

Line 1 imports the ReactNode type, for anything React can render. Line 3 takes a title and children, and lines 5 to 8 frame them in an <article> with the class ui-card. It has no state and no event handlers, so it needs no "use client". A component like this works on both sides: a Server Component renders it on the server, with its code kept there, and a Client Component that imports it sends its code to the browser.

The part that does need the browser, the Add to cart button, has "use client" in its own small file, at the bottom of the tree. Such a component, with no components of yours below it, is a leaf. The directive marks where the client part starts, and everything the file imports goes with it (Client Components calls this keeping the boundary low). Try both versions of the Card:

1import type { ReactNode } from "react";2 3export default function Card({ title, children }: { title: string; children: ReactNode }) {4  return (5    <article className="ui-card">6      <h2>{title}</h2>7      {children}8    </article>9  );10}

Each row is one text the recorder looked for in the JavaScript files /teas loads, in each version:

Both pages look the same. The recorder searched the JavaScript files /teas loads: the button's text, Add for, is in them both times. The Card's class name, ui-card, is only there once card.tsx starts with "use client": its code now goes to every page that uses a card, where it has nothing to do. So keep shared components plain, and give the directive only to the ones that need state, effects or event handlers.

Two more things change as a design system grows. A component from an npm package that uses hooks but has no directive needs a small file of yours with "use client" that re-exports it, as Client Components showed. And when several apps share the same components, the folder becomes a package of its own; the Monorepos lesson builds one.

Imports that survive a move: @/

Every import in the overview's pages starts with @/. That's a path alias: a short name for a folder, set in tsconfig.json. create-next-app writes this one, and every recorded project here has it:

1{2  "compilerOptions": {3    "target": "ES2017",4    "lib": ["dom", "dom.iterable", "esnext"],5    "allowJs": true,6    "skipLibCheck": true,7    "strict": true,8    "noEmit": true,9    "esModuleInterop": true,10    "module": "esnext",11    "moduleResolution": "bundler",12    "resolveJsonModule": true,13    "isolatedModules": true,14    "jsx": "react-jsx",15    "incremental": true,16    "plugins": [17      {18        "name": "next"19      }20    ],21    "paths": {22      "@/*": ["./*"]23    }24  },25  "include": [26    "next-env.d.ts",27    "**/*.ts",28    "**/*.tsx",29    ".next/types/**/*.ts",30    ".next/dev/types/**/*.ts",31    "**/*.mts"32  ],33  "exclude": ["node_modules"]34}35 

Lines 21 to 23 map @/* to ./*, the project's top folder. So @/features/teas/dal means the file features/teas/dal.ts, from any folder. Next.js reads the setting too, which is why the recorded builds found every file. Without it, app/teas/page.tsx would import ../../features/teas/dal. Move the page into a route group, to app/(shop)/teas/page.tsx, and that path breaks; the alias doesn't change.

A rule many teams follow, and the recorded files do: ./ for files in the same folder, like ./add-to-cart inside features/teas, and @/ for everything else. Then a feature can move as a whole without breaking its own imports, and an import line says where a file lives.

Rules a team can check

A layout only works while everyone follows it. Rules written in a README get forgotten; rules a tool checks don't. The shop's most important rule is about direction: app may import features, features may import ui, and ui imports neither, so a shared component never depends on one feature. ESLint, the linter create-next-app can set up, has a rule for this in its core, no-restricted-imports:

1import { defineConfig, globalIgnores } from "eslint/config";2import nextVitals from "eslint-config-next/core-web-vitals";3import nextTs from "eslint-config-next/typescript";4 5const eslintConfig = defineConfig([6  ...nextVitals,7  ...nextTs,8  {9    // Shared UI knows nothing about features or routes.10    files: ["ui/**"],11    rules: {12      "no-restricted-imports": ["error", {13        patterns: [{14          group: ["@/features/*", "@/app/*"],15          message: "ui/ is shared by every feature: pass data in as props.",16        }],17      }],18    },19  },20  // Override default ignores of eslint-config-next.21  globalIgnores([22    // Default ignores of eslint-config-next:23    ".next/**",24    "out/**",25    "build/**",26    "next-env.d.ts",27  ]),28]);29 30export default eslintConfig;31 

Lines 1 to 7, and the ignores after the block, are the config create-next-app writes when you pick ESLint. Lines 8 to 19 add a block. Line 10 says it's for files in ui/. Line 12 turns on no-restricted-imports as an error. Line 14 lists the imports it refuses: any path under @/features/ or @/app/. Line 15 is the message the report shows. Now someone adds a price tag to ui that formats the price with the teas' helper:

1import { formatPrice } from "@/features/teas/format";2 3export default function PriceTag({ price }: { price: number }) {4  return <span className="ui-price">{formatPrice(price)}</span>;5}

$ npx eslint ./my-app/ui/price-tag.tsx  1:1  error  '@/features/teas/format' import is restricted from being used by a pattern. ui/ is shared by every feature: pass data in as props  no-restricted-imports ✖ 1 problem (1 error, 0 warnings) $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (4/4)  Finalizing page optimization ... Route (app)┌ ○ /_not-found├ ○ /reviews└ ○ /teas ○  (Static)  prerendered as static content

Line 1 of ui/price-tag.tsx imports formatPrice from @/features/teas/format. The Terminal tab starts with $ npx eslint ., which the recorder ran before the build: '@/features/teas/format' import is restricted from being used by a pattern. ui/ is shared by every feature: pass data in as props, on line 1, column 1 of /my-app/ui/price-tag.tsx (/my-app is the project's folder), then ✖ 1 problem (1 error, 0 warnings). ESLint ended with exit code 1. Then $ next build built every route anyway: since Next.js 16, next build doesn't run ESLint (Accessibility recorded the same). Run npx eslint . yourself, in the checks that run on every change, beside your tests (Testing Next.js apps).

The fix follows the message. PriceTag takes the text to show, and the tea card, inside the teas feature, formats the price:

1export default function PriceTag({ text }: { text: string }) {2  return <span className="ui-price">{text}</span>;3}

$ npx eslint .  $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (4/4)  Finalizing page optimization ... Route (app)┌ ○ /_not-found├ ○ /reviews└ ○ /teas ○  (Static)  prerendered as static content

Now ui/price-tag.tsx imports nothing, and features/teas/tea-card.tsx passes text={formatPrice(tea.price)} on line 10. ESLint printed nothing and ended with exit code 0, and the page is unchanged: $4, then Add for $4.

Each row is one rule the shop keeps, and what checks it:

Core ESLint's rule is enough for a few folders. For many layers, there are third-party plugins, such as eslint-plugin-boundaries, which let you name each kind of folder and list which may import which. None of the recorded examples uses one, so check its docs before you rely on it. Whatever the tool, the rules belong in the repository, next to the code they protect, so a new teammate learns them from the first report.

The tea shop's folders, sorted

Here is the whole shop by feature, as recorded in the overview. Pages and layouts stay in app; each feature has its components, its data module and its helpers; ui holds what both features use. The shop keeps adding code. Sort each new file into the folder it belongs in:

One way to decide: if visitors open it at an address, it's in app. If only one feature uses it, it lives in that feature. If two features use it and it knows nothing about either, it's shared UI. Code that knows about one feature but is needed by another usually means the second feature should get the data from a page, as props.

Common mix-ups

• "Next.js wants feature folders." No. The three layouts built with the same routes. Next.js only reads the routing files in app; the rest is for the people who read the code.
• "Every file in app is a page." No. Only a page.tsx or a route.ts makes an address. /teas/tea-card answered 404, with tea-card.tsx right beside the page.
• "A file with no address is private." No. A Client Component that imports it sends its code to the browser, and whatever a page renders is in its HTML and RSC payload.
• "A helper with no secrets can live in the data module." Not if a Client Component needs it. Importing one function brings the whole module, and server-only stops the build. Keep helpers in their own files.
• "A barrel file is only a shortcut." No. Importing anything from it puts everything it re-exports in the importer's module graph: a server-only module in a client file's barrel stops the build, and an unused library can add bytes when the bundler can't leave it out.
• "Shared UI components need "use client"." No. A component without state or event handlers works in Server and Client Components. The directive only sent the Card's code to the browser.
• "next build checks my lint rules." No. Since Next.js 16 it doesn't run ESLint; the recorded build passed right after ESLint reported an error.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

app/
  _ui/
    card.tsx
  reviews/
    dal.ts
    page.tsx
    review-list.tsx
  teas/
    add-to-cart.tsx
    dal.ts
    format.ts
    page.tsx
    tea-card.tsx
  layout.tsx

app/
  reviews/
    page.tsx
  teas/
    page.tsx
  layout.tsx
components/
  add-to-cart.tsx
  card.tsx
  review-list.tsx
  tea-card.tsx
lib/
  format.ts
  reviews.ts
  teas.ts

import ReviewList from "@/features/reviews/review-list";
// Import getReviews from the reviews feature's data module.

export default async function ReviewsPage() {
  const reviews = await getReviews();
  return (
    <main>
      <h1>Reviews</h1>
      <ReviewList reviews={reviews} />
    </main>
  );
}

import ReviewList from "@/features/reviews/review-list";
import { getReviews } from "@/features/reviews/dal";

export default async function ReviewsPage() {
  const reviews = await getReviews();
  return (
    <main>
      <h1>Reviews</h1>
      <ReviewList reviews={reviews} />
    </main>
  );
}

import { formatPrice } from "@/features/teas/format";

export default function PriceTag({ price }: { price: number }) {
  return <span className="ui-price">{formatPrice(price)}</span>;
}

import "server-only";

// A stand-in for the teas table. `cost` is what the shop pays: staff only.
const rows = [
  { id: "green", name: "Green tea", price: 4, cost: 1.2 },
  { id: "mint", name: "Mint tea", price: 3, cost: 0.9 },
];

export type Tea = { id: string; name: string; price: number };

export function formatPrice(price: number) {
  return `$${price}`;
}

export async function getTeas(): Promise<Tea[]> {
  return rows.map(({ id, name, price }) => ({ id, name, price }));
}

export function formatPrice(price: number) {
  return `$${price}`;
}

export { default as AddToCart } from "./add-to-cart";
export { getTeas, type Tea } from "./dal";
export { formatPrice } from "./format";
export { default as TeaCard } from "./tea-card";

"use client";

import { useState } from "react";
import { formatPrice } from "./format";

export default function AddToCart({ price }: { price: number }) {
  const [added, setAdded] = useState(false);
  return (
    <button type="button" onClick={() => setAdded(true)}>
      {added ? "Added" : `Add for ${formatPrice(price)}`}
    </button>
  );
}

Check your understanding

For each question, ask which files make addresses, and where each module's code runs.

Key takeaways

• Next.js gives addresses only to routing files in app. Sorting the rest by kind of file, by feature or beside the routes changed no route in the recordings.
• For a growing app, keep app for routes and group the other files by feature, with shared UI in a folder of its own.
• Give each feature one server-only way in for its data, a module or a few behind one entry, that returns only the fields pages need. Keep helpers that the browser needs in their own files.
• A barrel puts everything it re-exports in the module graph of whoever imports it: a server-only module behind it stops the build of any client file that uses it, even if nothing ships.
• Keep shared components plain, and put "use client" on the small leaves that need the browser.
• Import with @/ across folders, and let ESLint check which folder may import which. Run it yourself: next build doesn't.

Coming next: Next.js as a backend for your frontend. The shop's Next.js app stands in front of other teams' services: Route Handlers as a public API, rewrites, and calling several services at once.