App Directory Conventions

The App Router has one rule, and every routing question reduces to it: a folder becomes a URL only when it contains a route-producing special file — page or route. Everything else in app/ is either a modifier for a route that already exists, or ordinary code the router ignores. A fresh scaffold already demonstrates the rule:

app/
├── layout.tsx            # wraps everything below it — no URL of its own
├── page.tsx              # /
├── about/
│   └── page.tsx          # /about
├── blog/
│   ├── [slug]/
│   │   └── page.tsx      # /blog/hello-world, /blog/next-15, …
│   └── archive/
│       └── page.tsx      # /blog/archive
└── api/
    └── health/
        └── route.ts      # GET /api/health

Two of those rows are where interviews go. Route groups (marketing) let you stack a different layout over a set of pages without adding a segment to the URL, so (marketing)/about and (dashboard)/about can both exist — which also means two groups accidentally declaring the same URL will collide at build time. Private folders _name are excluded from routing, which is how you keep experiment code inside app/ without publishing it.

The router matches names exactly: page.tsx, page.js, and page.jsx all register, but Page.tsx or pages.tsx do not — a case or plural slip produces a 404 with no warning in development on Windows or macOS, because those filesystems ignore case and Linux does not. The same exactness applies to the special files themselves; there is no partial credit in file-convention routing.

The counterpart is route.ts, which is an endpoint rather than a page:

// app/api/health/route.ts
export async function GET() {
  return Response.json({ ok: true, uptime: process.uptime() })
}

Export HTTP method functions (GET, POST, PATCH, DELETE) and the folder becomes an API route — the App Router's replacement for pages/api/*.ts. Two conventions to respect: it must be .ts/.js, not .tsx, because there is no JSX in it; and a segment serves one purpose, so choose page.tsx for UI or route.ts for an endpoint in a given folder rather than trying to host both.

Notice what does not produce a URL. A folder with no page or route file — app/components/, app/dashboard/widgets/ — renders nothing when visited. That is the biggest behavioral shift from the Pages Router, where every .tsx file in pages/ became a route and shipping pages/components/Button.tsx publicly exposed /components/Button as a live URL. In app/, you may colocate ProductCard.tsx, schema.ts, and helpers.test.ts next to the page that uses them; the router scans for special file names only, so the code stays route-private by default.

The failure mode to hold onto: a folder named for something internal (app/utils/, app/(old)/legacy/) silently stays harmless — until someone drops a page.tsx inside, and the URL appears in production with no configuration change, no route table entry to review, no warning. File location is the public API of your site, which is precisely why Scaffolding with create-next-app puts such weight on choosing app/ (or src/app/) deliberately: that directory is where every URL you will ever ship is declared.

If page and route decide what is served, the remaining special files decide how a segment behaves while it is served. Each one has exactly one job, and each has a granularity that interviewers like to test.

Three details cause most bugs.

error.tsx must be a Client Component. It is an error boundary, and React error boundaries only exist in the browser tree, so the file starts with 'use client' and receives an error object plus a reset() function:

'use client'
export default function Error({
  error,
  reset,
}: { error: Error & { digest?: string }; reset: () => void }) {
  return (
    <div>
      <h2>Could not load this order</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

The second subtlety: an error.tsx catches failures thrown below it — typically the page.tsx in its own folder — but it does not catch errors thrown by the layout.tsx sitting beside it. A crash in the same segment's layout bubbles up to the parent's boundary, which is why a broken root layout takes down every route in the app instead of showing your nicest fallback.

loading.tsx is a Suspense boundary, not a spinner service. It renders the moment a navigation starts, inside the parent's layout, while the child page streams:

/navigation        → /dashboard/orders
┌──────────────────────────────────┐   ← root layout: never re-renders
│ App bar                           │
│ ┌──────────────────────────────┐ │   ← loading.tsx for /dashboard/orders
│ │ ▓▓▓▓▓  ▓▓▓▓▓  ▓▓▓▓▓        │ │      appears instantly
│ └──────────────────────────────┘ │
└──────────────────────────────────┘

Because it lives under the parent layout, the shell stays visible and the user keeps their place — the mechanism behind "instant navigation" in every App Router demo. Drop it in and the whole view blanks until the slow await fetch resolves.

Layouts compose and persist. app/layout.tsx wraps app/dashboard/layout.tsx, which wraps the matched page; each receives its nested UI through a children prop. On client-side navigation, layouts above the matched segment are not re-rendered, so open sidebars, scroll position, and useState survive a route change — a page component, by contrast, unmounts and remounts every time. template.tsx exists for the rare case where you want the opposite: a wrapper that re-creates its subtree on each navigation, for example a component that replays an entrance animation.

Recognizing these names as behavior boundaries rather than routes is the interview payoff: the question "what does loading.tsx actually do?" is answered by naming Suspense, the parent layout, and streaming — not by saying "it shows a spinner". The next file, Environment Variables, moves from file conventions to configuration, but the segment model here is what every later topic builds on.

Once routes are covered, the open question is where everything else goes: buttons used by six pages, the database client, date helpers, generated types. Put shared code in the wrong place and you either create URLs you did not intend or bury route-private logic where nobody can find it.

The safe foundation is that only app/ is scanned for route files, and only page/route inside it register. So this layout cannot produce a single URL outside app/:

src/
├── app/                  # every URL in the product lives here
│   ├── layout.tsx
│   ├── page.tsx
│   └── orders/
│       ├── page.tsx      # /orders
│       ├── order-card.tsx     # colocated: private to /orders
│       └── status.ts          # colocated: private to /orders
├── components/           # shared UI — Button, Modal, DataTable
├── lib/                  # db.ts, stripe.ts, fetch-api.ts
├── hooks/                # use-orders.ts
└── types/                # shared types, generated API models

components/, lib/, hooks/, and types/ sit outside the router's scan, so importing them cannot change a URL. Resolve them through the alias the scaffold created — import { Button } from '@/components/Button' — rather than relative ../../../.. chains that break the moment a file moves.

Colocation inside app/ is equally safe, and it is the App Router's intended style: a helper imported only by app/orders/page.tsx belongs next to it, not in a global folder it will never be reused from. The maintainers' rule of thumb is one level of colocation — files for the current segment live in the segment's folder; promote to src/components/ the moment a second route imports them.

Three mistakes blur this line:

1. Special file names used as ordinary components. A colocated app/dashboard/loading.tsx that you intended as a spinner component is registered as the segment's loading boundary, and error.tsx becomes an error boundary. Name such files skeleton.tsx or order-error.tsx when they are just components.

2. Internal folders that later grow a page. app/admin-utils/ is inert today. The day someone adds app/admin-utils/page.tsx to "test something", /admin-utils is live — public, crawlable, and unauthenticated unless the page defends itself. Treat every new page.tsx as a deliberate publication.

3. Holding shared state in a route folder. A cart context defined in app/cart/context.tsx and imported by app/checkout/ creates a dependency from an unrelated route into another segment's internals. Move it to src/lib/ or src/hooks/ so the import graph reflects reality.

A quick way to reason about any file: if this URL were added to the sitemap tomorrow, would this file be part of the reason? If yes, it belongs to a segment; if no, it belongs outside app/.

One file lives outside this whole discussion: middleware.ts sits at the project root (or at the root of src/), never inside app/, because it is not a route — it runs before matching on every request that qualifies. Similarly, a colocated helpers.test.ts or schema.ts is inert: only the exact special names carry meaning, and even then only the lowercase ones. That exactness is the convention to internalize before moving on to Environment Variables.

Interviewers ask this as "where would you put a component used by two layouts?" — a strong answer names both halves: route-private code is colocated with its segment, cross-cutting code moves to src/components or src/lib, and neither choice can create a route because only page.tsx and route.ts do that. From here the natural next question is how those segments get configured at all, which is exactly Environment Variables — the data clients you just parked in lib/ need a DATABASE_URL that must never reach the browser.