File-system routing

Folders become addresses

A route is an address in your app, like /teas, and the page it shows. Most tools ask you to list your routes in code. Next.js doesn't: its App Router, the router this course teaches, reads the folders inside app, and the folders are the list. That's called file-system routing. If you built the notes app in Your first Next.js app, you already used it: app/new/page.tsx was the page for /new. This lesson gives you the rules behind that.

Here is the tea shop with three pages. Like every example in this lesson, it's a real Next.js 16.4.3 project, built with next build and run with next start, and what it sent back was recorded. Click through its files, then its pages.

1export default function TeasPage() {2  return (3    <main>4      <h1>Our teas</h1>5      <ul>6        <li>Green tea</li>7        <li>Mint tea</li>8      </ul>9    </main>10  );11}

app/teas/page.tsx exports its component with export default on line 1, and line 4 is its heading, Our teas. Nothing in the file says /teas: its place does. The file sits in a folder named teas, inside app, so it's the page for /teas. In the same way, app/page.tsx is / and app/about/page.tsx is /about. app/layout.tsx is the root layout: it goes around every page, and its links on line 10 lead to all three.

Open the Terminal tab. After building, next build prints the routes it found: ○ /, ○ /_not-found, ○ /about and ○ /teas. You never wrote that list. The build made it from the folders, and added /_not-found, the page for addresses that don't exist. The ○ in front of each one means prerendered as static content, as the legend under the table says: every page in this lesson is. In the Browser tab, click Teas and About to switch between the recorded pages.

One folder for each part of the address

The part of a URL after the site's name is its path: in localhost:3000/teas/green, the path is /teas/green. The / characters split a path into parts called segments: here, teas and green. Next.js matches each segment with one folder, in order:

• The root segment is app itself. It stands for /, and its name never shows in the address. That's why app/page.tsx is the page for /, not /app.
• Every folder inside app is one more segment, with the folder's name as the text of the address: app/teas is /teas.
• A folder inside that one adds the next segment: app/teas/green is /teas/green.

Each row is one address from this lesson's recordings: its segments, and the folder its page sits in.

Because a folder's name is the text of the address, name folders the way you want the address to read: short, lowercase words, with hyphens between them, like gift-boxes for /gift-boxes.

Folders inside folders

A route made of several segments is a nested route. The shop wants a page for each tea, so app/teas gets a folder for each: green and mint, each with its own page.tsx. The list at /teas now links to them.

1export default function GreenTeaPage() {2  return (3    <main>4      <h1>Green tea</h1>5      <p>Light and fresh. $4 a box.</p>6    </main>7  );8}

app/teas/green/page.tsx is an ordinary page: a heading on line 4 and a line about the tea on line 5. Its folders, teas then green, make its address /teas/green. In app/teas/page.tsx, lines 9 and 12 link to /teas/green and /teas/mint.

The Terminal lists two new routes, ○ /teas/green and ○ /teas/mint, under ○ /teas. In the Browser, click Green tea. The page shows the layout's links, then Green tea and Light and fresh. $4 a box., and nothing from the /teas page. A nested route doesn't show its parent page; each address shows one page. What pages share goes in a layout, and folders can have layouts of their own, which the next lesson shows.

One folder for each tea works for two teas. For two hundred, you write one folder whose name is a placeholder, and Next.js fills it from the address. That's a dynamic route, a few lessons on, in Dynamic routes.

page.tsx makes a route public

A folder gives a route its place, but not a page. Only a page file makes the route public: an address that visitors can open. The shop's account area shows the difference. It has app/account/orders/page.tsx, so /account/orders is a page. The folder above it, app/account, holds only that folder. Pick a version, then look at what /account answered.

1export default function OrdersPage() {2  return (3    <main>4      <h1>Your orders</h1>5      <p>No orders yet.</p>6    </main>7  );8}

In the first version, /account answered with a page that says 404 and This page could not be found. Open its Network tab: the status is 404, the title is 404: This page could not be found., and the page is the one Next.js made as /_not-found. The route table has ○ /account/orders but no /account. In the second version, app/account/page.tsx adds ○ /account, and the same request answers 200 with Your account.

So next build reads the folders and builds a tree of routes from them. In this shop, every route is a fixed address, so the tree is the list in the Terminal: a request for a path in it gets its page, and any other path gets the 404 page. A route can also be a pattern, with a folder name like [slug] that matches addresses the build never listed; Dynamic routes shows those.

Which names count as a page file? Each button below is the same About page, saved under a different name. Before you click, guess which ones make /about.

1export default function AboutPage() {2  return (3    <main>4      <h1>About us</h1>5      <p>We sell tea from one small shop.</p>6    </main>7  );8}

$ 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 (5/5)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ○ /about└ ○ /teas ○  (Static)  prerendered as static content

about/page.tsx and about/page.js make a page: the App Router accepts page.js, page.jsx and page.tsx. about/index.tsx and about.tsx don't, and /about answers 404. Those two names come from the Pages Router, Next.js's older router, which reads a pages folder: there, every file is a page, pages/about.tsx is /about, and pages/index.tsx is /. It's still supported, and you'll meet it in older projects. In the App Router, only page files make pages.

Files that never become routes

Since only page files make addresses here, every other file in app has no address. You can keep a page's own parts right next to it, which is called colocation. Here, the teas page takes its list from data.ts and draws each tea with tea-card.tsx, both in app/teas.

1import TeaCard from "./tea-card";2import { teas } from "./data";3 4export default function TeasPage() {5  return (6    <main>7      <h1>Our teas</h1>8      <ul>9        {teas.map((tea) => (10          <TeaCard key={tea.slug} name={tea.name} price={tea.price} />11        ))}12      </ul>13    </main>14  );15}

Lines 1 and 2 of app/teas/page.tsx import the two files beside it. Line 10 draws a TeaCard for each tea in teas. The /teas page shows Green tea: $4 and Mint tea: $3, so both files did their job.

Now pick /teas/tea-card and /teas/data in the Browser tab. The recorder asked for both, and both answered 404. The route table still has one route for the folder, ○ /teas. A component or a data file beside a page is part of that page, and has no address of its own.

Other files in app never become routes either. layout.tsx goes around pages, and other special files, like loading.tsx for a loading screen, each do one job for a route, as the next lessons show. Two folder names change the rules on purpose: a folder whose name starts with _, like _components, is left out of routing with everything in it, and a folder in brackets, like (shop), groups routes without adding a segment. Route groups and private folders, later in this stage, covers both.

Planning the tea shop's folders

When you plan an app, start from the addresses you want, then make a folder for each segment and a page file where the address should open. Each row is one address the recordings in this lesson served, and the file that made it.

Notice /account and /account/orders: they're two pages, so they need two page files, one in each folder. Now sort these files: which ones make a page?

Common mix-ups

• "Every file in app is a page." No. Only page files are. /teas/tea-card and /teas/data answered 404.
• "app/about.tsx makes /about." No. Only folders make segments: the recorded /about answered 404.
• "index.tsx is a folder's page." No. That's the Pages Router. The App Router looks for page.tsx, page.jsx or page.js.
• "A folder is enough to make its address work." No. Without a page file, /account answered 404, though /account/orders worked.
• "A nested page shows its parent page too." No. /teas/green showed only its own page, inside the layout. Shared parts go in layouts.
• "You list the routes somewhere." No. next build reads the folders and prints the list itself.

Practice exercises

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

app/
  about/
    page.tsx
  teas/
    green/
      page.tsx
    mint/
      page.tsx
    page.tsx
  layout.tsx
  page.tsx

export default function TeamPage() {
  return (
    <main>
      <h1>Our team</h1>
      <p>Asha and Ravi pack every box.</p>
    </main>
  );
}

app/
  about/
    page.tsx
  account/
    orders/
      page.tsx
  teas/
    page.tsx
  layout.tsx
  page.tsx

export default function AboutPage() {
  return (
    <main>
      <h1>About us</h1>
      <p>We sell tea from one small shop.</p>
    </main>
  );
}

app/
  teas/
    data.ts
    page.tsx
    tea-card.tsx

export function AboutPage() {
  return (
    <main>
      <h1>About us</h1>
      <p>We sell tea from one small shop.</p>
    </main>
  );
}

export default function AboutPage() {
  return (
    <main>
      <h1>About us</h1>
      <p>We sell tea from one small shop.</p>
    </main>
  );
}

Check your understanding

For each question, walk the folders from app, and ask whether the last one has a page file.

Key takeaways

• The App Router builds its routes from the folders in app. next build prints the list; you never write it.
• Each folder is one segment of the address. app is the root segment, /, so app/teas/green is /teas/green.
• A page.tsx (or page.jsx, or page.js) makes a route public. A folder without one answers 404, even when the folders inside it have pages.
• Each address shows one page, inside the layout. A nested page doesn't show its parent page.
• Every other file in app, like a component or data beside a page, never gets an address. index.tsx and about.tsx are Pages Router names, not App Router pages.

Coming next: Layouts and pages. It shows the root layout in full, layouts inside folders that wrap only their own pages, and the props each one gets.