Project structure

A map of the tea shop's project

Creating a Next.js app left you with a folder full of files. This lesson is the map: what each folder and file is for, which of them become addresses on the site, and where your own files can go. Here is the tea shop's project, with two pages and a menu file:

tea-shop/
  app/
    teas/
      page.tsx
      tea-list.tsx
      teas.ts
    layout.tsx
    page.tsx
  public/
    menu.txt
  next.config.ts
  package.json
  tsconfig.json

Lines 2 to 8 are the app folder, with the pages. Lines 9 and 10 are the public folder, with one text file. Lines 11 to 13 are settings files, at the project's top level: directly in tea-shop, not inside another folder. That's a real project. It was built with next build, run with next start, and asked for five addresses. Click the files to read them, and the addresses above the page to switch between them.

1import { getTeas } from "./teas";2import TeaList from "./tea-list";3 4export default async function TeasPage() {5  const teas = await getTeas();6  return (7    <main>8      <h1>Our teas</h1>9      <TeaList teas={teas} />10    </main>11  );12}

app/teas/page.tsx is the page for /teas. Lines 1 and 2 import two files that sit next to it in the same folder: teas.ts, the shop's data, and tea-list.tsx, a component that draws the list. The Browser tab shows the page at /teas with its three teas. Now pick /teas/tea-list or /teas/teas: both answer 404, the page for an address that doesn't exist. A file in app only becomes an address when it's a page.

Each row is one thing at the top level of the project:

The app folder: folders become addresses

The app folder is the App Router: the part of Next.js that turns folders into addresses. A route is one address the site answers, like /teas. The rules, as a first look:

• app itself is the address /, so app/page.tsx is the home page.
• Each folder inside adds a part to the address, called a segment: app/teas is /teas.
• A segment becomes a page only when its folder has a page.tsx. That file's component is what visitors see.
• app/layout.tsx is the root layout: it's around every page. In the recording, every response, even the 404, starts with the layout's links, Home and Teas.

Open the example's Terminal tab. After building, Next.js lists the routes it found: ○ /, ○ /_not-found and ○ /teas. /_not-found is the page Next.js adds for addresses that don't exist. tea-list.tsx and teas.ts aren't in the list.

Dynamic addresses like /teas/mint, nested layouts, and the folders that don't change the address all build on these rules. The Routing and navigation stage teaches them one by one.

Special files: a first look

page.tsx and layout.tsx are two of Next.js's special files: names that mean something in app. Each one gives its folder a job. The file can end in .tsx, .jsx or .js (and route in .ts or .js). Each row is one of them, with the lesson that teaches it:

Here is the tea shop with four more of them added to app. The file shown first is app/not-found.tsx:

1import Link from "next/link";2 3export default function NotFound() {4  return (5    <main>6      <h1>Not on the menu</h1>7      <p>8        <Link href="/teas">See every tea</Link>9      </p>10    </main>11  );12}

• not-found.tsx: the Browser tab opens on /oolong, an address the shop doesn't have. It answered with status 404, and with this file's page: line 6 is the heading Not on the menu, inside the same layout as every page.
• route.ts: app/api/teas/route.ts makes the address /api/teas, which answers with data instead of a page. Pick it, then open the Network tab: the body is the three teas as JSON, with content-type: application/json. The Terminal tab lists it as a route, ○ /api/teas, next to the pages.
• error.tsx: shown in place of a page that throws an error. Nothing here throws, so it never shows. Error files must be Client Components, so line 1 is "use client", and its button calls retry to try the page again.
• loading.tsx: shown while a page waits for something, like data that's made for each request. Every page here is made during the build, so Brewing… never shows either.

The special files in one folder fit inside each other, like boxes. Next.js puts the page inside loading.tsx, that inside error.tsx, and all of it inside the layout:

Because these names mean something, don't give your own files the same names. A component called page.tsx in a folder would turn that folder into an address. Name it for what it is, like tea-list.tsx.

public: files served as they are

Every file in public gets an address: its path inside public, starting at the top of the site. The word public isn't part of it. So public/menu.txt is /menu.txt, and a picture at public/images/green-tea.svg is /images/green-tea.svg.

In the first example, pick /menu.txt and open the Network tab. The server sent the file exactly as it is, as text/plain, with Cache-Control: public, max-age=0. That header lets browsers keep a copy, but tells them to ask the server again every time before they use it: Next.js can't know whether a file in public has changed. A page uses these files by their address, like <img src="/images/green-tea.svg" />.

Three things to know:

• Anyone can download anything in public. Never put secrets there.
• Files in public aren't built: no TypeScript, no bundling. They're sent byte for byte.
• The site's icon and files for search engines, like favicon.ico and robots.txt, have special files of their own in app. That's why create-next-app put favicon.ico in app, not in public.

The optional src folder

Some teams like their own code apart from the settings files. Next.js lets you move app into a folder named src, short for source. It's the --src-dir answer in create-next-app. The app works the same; only the folder moves. The settings stay at the top level, and so does public. One line of tsconfig.json changes, so the @/ alias points into src:

    "paths": {
      "@/*": ["./src/*"]
    }

The middle line maps @/* to ./src/*, so import TeaList from "@/app/teas/tea-list" finds src/app/teas/tea-list.tsx. Without src, it says ./*. Try the four layouts below. Each one was built and run with real Next.js. Before you click, guess what / and /menu.txt answer for each.

1export default function Home() {2  return (3    <main>4      <h1>Tea shop</h1>5      <p>This page is app/page.tsx.</p>6    </main>7  );8}

So, with src:

• app moves into src, and so do your own folders, like components and lib.
• public, next.config.ts, package.json, tsconfig.json and the .env files stay at the top level.
• Keep only one app. If there's one at the top level too, Next.js uses it and ignores src/app.

next.config.ts and the other top-level files

next.config.ts holds Next.js's settings. Next.js reads it every time next dev, next build or next start starts: a build of the default project prints ✓ Running next.config.ts took 63ms. Every recorded example in this course uses the one create-next-app writes without Tailwind, which turns on Cache Components and Partial Prefetching. Add a setting, and Next.js behaves differently. Here the shop gains one:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
  cacheComponents: true,
  partialPrefetching: true,
  poweredByHeader: false,
};

export default nextConfig;

Line 3 makes the settings object, and its type, NextConfig, lets your editor suggest every setting. Lines 5 and 6 are the ones create-next-app wrote. Line 7 is new: poweredByHeader: false. Line 10 exports the object for Next.js. Compare the headers with and without it:

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  /* config options here */5  cacheComponents: true,6  partialPrefetching: true,7};8 9export default nextConfig;

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/1x6obpmlu1_c2.js">
    <script src="/_next/static/chunks/06bs-nf19b2js.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/3l_qmp-61z4yc.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/3oh00mkbkq8u6.js" async=""></script>
    <title>Tea shop</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <nav><a href="/">Home</a> <a href="/teas">Teas</a></nav>
    <!--&-->
    <main>
      <h1>Tea shop</h1>
      <p>Three teas, brewed fresh.</p>
    </main>
    <!--$-->
    <!--/$-->
    <!--/&-->
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/1x6obpmlu1_c2.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
  </body>
</html>

Most settings are for later lessons: redirects, images, and the bundler. A few other files at the top level have a meaning to Next.js too, and each has its lesson later:

• .env, .env.local and others: environment variables, settings like secret keys that your code reads, kept out of git.
• proxy.ts: code that runs before a request reaches a page, to redirect it or check who's signed in. Before Next.js 16 it was called middleware.ts.
• instrumentation.ts: code that runs once when the server starts, for tools that watch the app.

Where your own files go

Your components, data and helpers aren't special files, and Next.js doesn't mind where they go. Keeping a file next to the code that uses it is called colocation. In app, a file next to a page gets no address: only page.tsx and route.ts make addresses. That's why app/teas/tea-list.tsx answered 404.

Having no address isn't the same as staying on the server, though. What a page renders is sent to the browser in its HTML: the recorded /teas holds every tea from teas.ts. And a file that a Client Component imports is sent to the browser as code, wherever it sits (Server Components explains the two kinds). Secrets, like an API key, belong in code that only runs on the server and in environment variables the browser never gets; the Server-only code and environment variables lesson shows how. Each row is one place your files can go:

Many teams keep shared code beside app, in folders like components and lib. The names mean nothing to Next.js. Here the shop does that, and imports with the @/ alias instead of ../:

import { getTeas } from "@/lib/teas";
import TeaList from "@/components/tea-list";

export default async function TeasPage() {
  const teas = await getTeas();
  return (
    <main>
      <h1>Our teas</h1>
      <TeaList teas={teas} />
    </main>
  );
}

Line 1 imports getTeas from lib/teas.ts, and line 2 imports TeaList from components/tea-list.tsx. @/ means the project's top level, from tsconfig.json. The recording below proves both halves: /teas shows the teas, and /components/tea-list and /lib/teas answer 404.

1import { getTeas } from "@/lib/teas";2import TeaList from "@/components/tea-list";3 4export default async function TeasPage() {5  const teas = await getTeas();6  return (7    <main>8      <h1>Our teas</h1>9      <TeaList teas={teas} />10    </main>11  );12}

One more tool, as a first look: a folder whose name starts with an underscore, like _drafts, is a private folder. Next.js leaves it out of routing completely, even a page.tsx inside it:

1export default function Draft() {2  return (3    <main>4      <h1>Autumn menu (draft)</h1>5    </main>6  );7}

The Terminal tab lists /, /_not-found and /teas, and no /_drafts. Asked for it, the server answered 404. Private folders and route groups get a lesson of their own: Route groups and private folders. Whichever way you choose, use it across the whole project, so everyone knows where to look.

Where does this file go?

The shop keeps growing: an About page, a logo, a menu to download, secret keys. Each card is a file it needs. Sort it into the place it belongs:

One way to decide: if visitors open it as a page, it's in app. If they download it as it is, it's in public. If a tool reads it, it's at the top level. The rest is your code, and it goes next to whatever uses it.

Common mix-ups

• "Every file in app becomes a page." No. Only page.tsx makes a page, and route.ts an address for data. /teas/tea-list answered 404.
• "Files in public are at /public/…." No. public/menu.txt is at /menu.txt.
• "With src, everything moves into it." No. public and the settings files stay at the top level. Moved, public stops working.
• "Next.js warns if there are two app folders." No. It quietly uses the top-level one and ignores src/app.
• "A file with no address never reaches the browser." No. What a page renders is in its HTML, and a file a Client Component imports is sent as code. Keep secrets in server-only code and environment variables.
• "Components must go in a components folder." No. The name means nothing to Next.js. Next to the page, or beside app, both work.
• "next.config.ts is where pages are listed." No. Pages come from the folders in app. next.config.ts only holds settings.

Practice exercises

Answer first, then use the hints.

app/
  about/
    page.tsx
  lib/
    format.ts
  teas/
    page.tsx
    price.ts
  layout.tsx
  page.tsx

import { getTeas } from "./teas";
import TeaList from "./tea-list";

export default async function TeasPage() {
  const teas = await getTeas();
  return (
    <main>
      <h1>Our teas</h1>
      <TeaList teas={teas} />
    </main>
  );
}

"paths": {
  "@/*": ["./*"]
}

"paths": {
  "@/*": ["./src/*"]
}

app/
  layout.tsx
  page.tsx
src/
  app/
    layout.tsx
    page.tsx

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
  cacheComponents: true,
  partialPrefetching: true,
};

export default nextConfig;

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
  cacheComponents: true,
  partialPrefetching: true,
  poweredByHeader: false,
};

export default nextConfig;

Check your understanding

For each question, ask which folder a file is in, and whether its name means something to Next.js.

Key takeaways

• app holds the pages; public holds files sent as they are; the top level holds the settings files.
• In app, each folder is a segment of the address, and page.tsx makes it a page. Other files next to it have no address.
• Special files give a folder a job: layout, page, loading, error, not-found and route. They fit inside each other, with the page in the middle.
• public/menu.txt is at /menu.txt. Nothing secret goes in public.
• src is optional: app moves into it; public and the settings stay at the top level. Keep only one app.
• Your own files can go next to the page that uses them, in folders beside app, or in a private _folder.

Coming next: Your first Next.js app. It builds a small notes app from scratch, with two pages, a shared layout, a link, data from the server, and a form that saves.