Next.js From Zero: Project Structure, Routing and Layouts

React by itself only draws components in the browser. It does not know about URLs, servers, or how to split your code into files that load fast. You have to add all of that yourself. Next.js adds it for you, and it decides a lot of things so you do not have to. The price is that you must learn its rules. This lesson teaches the first and most important rules: the project folders, how files become routes, layouts, dynamic routes, links, and the special files.

This is lesson 0 of ten. You should know basic React (components, props, JSX). If you do not, start with Thinking in React. The next lesson, Server Components and Client Components, explains the biggest idea in this version of Next.js: which code runs on the server and which runs in the browser. Here we stay on the map: where files go and what URL they make.

Words used in this lesson

• Next.js is a framework built on React. It adds routing, server rendering, data fetching, caching, and a build system.
• App Router is the routing system based on the app/ folder. It is the one this series teaches. The older one is the Pages Router (the pages/ folder).
• Route is a URL path your app answers, like /blog/hello.
• Segment is one piece of a URL path between slashes. In /blog/hello the segments are blog and hello.
• Page is the file page.tsx. It is the screen for one URL. A folder with no page file is not a public URL.
• Layout is the file layout.tsx. It wraps pages and nested layouts. It stays on screen when you move between its pages.
• Root layout is the layout in app/layout.tsx. It is required and must contain the <html> and <body> tags.
• Dynamic segment is a folder name in square brackets like [slug]. It matches any value in that place of the URL.
• params is the object with the values of dynamic segments. In this version of Next.js it is a Promise, so you must await it.
• Static rendering (prerendering) means the page is built once at build time and served as ready HTML.
• Dynamic rendering means the page is built on the server for each request.
• Client-side navigation means moving to another page without reloading the whole browser page.
• Prefetching means loading a page in the background before the user clicks, so the click feels instant.
• Special files are files with fixed names (loading, error, not-found, route) that Next.js treats in a particular way.

What Next.js adds to React

Think about what you need for a real website:

1. A way to map URLs to screens (routing).
2. HTML that arrives already filled with content, so the page shows fast and search engines can read it.
3. A place to run server code (read a database, hide a secret key).
4. A bundler that splits your JavaScript so users download only what a page needs.
5. Image, font and metadata helpers.

With plain React you pick and connect all of these yourself: a router, a bundler, a server, and so on. Next.js ships them together and connects them. That is the whole idea. It is a set of decisions made for you.

Next.js has two routers. The Pages Router (the pages/ folder) is older and still supported. The App Router (the app/ folder) is newer and is where all new features go. This series is only about the App Router. If you see getServerSideProps or a pages/ folder in an old tutorial, that is the old way.

Make a project and look at it

The official way to start is create-next-app. I ran it with --yes, which accepts the defaults (TypeScript, Tailwind CSS, ESLint, App Router, Turbopack, and the @/* import alias).

npx create-next-app@16.3.5 demo --yes --use-npm --skip-install

Here is the real list of files it made (I left out the .git folder):

.gitignoreAGENTS.mdCLAUDE.mdREADME.mdapp/favicon.icoapp/globals.cssapp/layout.tsxapp/page.tsxeslint.config.mjsnext-env.d.tsnext.config.tspackage.jsonpostcss.config.mjspublic/file.svg  globe.svg  next.svg  vercel.svg  window.svgtsconfig.json

And its package.json:

{  "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "eslint" },  "dependencies": { "next": "16.3.5", "react": "19.2.8", "react-dom": "19.2.8" },  "devDependencies": { "@tailwindcss/postcss": "^4", "@types/node": "^20", "@types/react": "^19",    "@types/react-dom": "^19", "eslint": "^9", "eslint-config-next": "16.3.5",    "tailwindcss": "^4", "typescript": "^5" }}

Notice two things. First, only three runtime packages: next, react, react-dom. Second, the scripts. These three are the ones you will use all the time:

The file AGENTS.md (and CLAUDE.md that points to it) is new. create-next-app adds it to guide AI coding tools to read the bundled docs. It is plain text and you can edit it.

The default stack is only the default. The project works without Tailwind, and you can use JavaScript instead of TypeScript. The only things that matter for routing are the app folder and its files.

The top-level folders and files

The docs list four top-level folders: app (the App Router), pages (the Pages Router), public (static files served as they are, like /next.svg), and an optional src (a folder that can hold app, if you want your code in src/). The top-level files that matter to us:

• next.config.ts holds configuration (lesson 8).
• proxy.ts is code that runs before a request is handled (lesson 4). In older versions this file was called middleware.ts.
• .env.local holds local environment variables, and must not go into git (lesson 8).
• instrumentation.ts sets up monitoring (lesson 8).

The app folder: folders are URLs

The main rule is short:

Let us build a small app and see. This is the layout I used for the experiments in this lesson:

app/  layout.tsx                  root layout, wraps everything  page.tsx                    /  not-found.tsx               the 404 screen  blog/    layout.tsx                wraps /blog and everything under it    page.tsx                  /blog    [slug]/page.tsx           /blog/hello-world, /blog/anything  (marketing)/about/page.tsx  /about    (the (marketing) part is not in the URL)  shop/[...parts]/page.tsx    /shop/a, /shop/a/b/c  docs/[[...rest]]/page.tsx   /docs, /docs/a, /docs/a/b  _components/secret.tsx      not a route (private folder)

The smallest page is a function that returns JSX, exported as the default export:

// app/page.tsxexport default function Page() {  return <h1>Home</h1>}

I ran next build on this app. The last part of the output is the route table, and it tells a lot:

Route (app)┌ ○ /├ ○ /_not-found├ ○ /about├ ○ /blog├   /blog/[slug]│ ├ ● /blog/hello-world│ └ ● /blog/second-post├ ƒ /docs/[[...rest]]└ ƒ /shop/[...parts]○  (Static)   prerendered as static content●  (SSG)      prerendered as static HTML (uses generateStaticParams)ƒ  (Dynamic)  server-rendered on demand

How to read the symbols:

• ○ Static. The page was built once at build time. A request just gets a ready file.
• ● Also prerendered at build time, but for a dynamic route. It used generateStaticParams to list which values to build (we cover that below).
• ƒ Dynamic. Built on the server for each request.

Look at /docs/[[...rest]] and /shop/[...parts]. They are ƒ because I did not tell Next.js which values to build. It cannot guess, so it waits for a request. Keep this table in mind. You will read it after every build for the rest of this series.

Route groups and private folders

Two naming tricks help you keep order without changing URLs:

• (name) in parentheses is a route group. The folder name is not part of the URL. I put about inside (marketing), and the URL is /about. Groups are useful to give a set of routes their own layout, or just to keep the folder tidy.
• _name with an underscore is a private folder. Next.js ignores it for routing.

Is the private folder needed? Not really. The docs point out that a folder without a page file is not routable anyway, so you can keep helper files next to your pages ("colocation"). I tested it with a file at app/_components/secret.tsx:

$ curl -s -o /dev/null -w "%{http_code}" localhost:3100/_components/secret404

A 404, as expected. Private folders are useful to avoid a name clash with future special files and to keep UI code apart from routing code. Use them if you like the style.

Layouts: shared screens that stay on

A layout wraps its pages and stays on screen while you move between them. The root layout is required, lives at app/layout.tsx, and must contain <html> and <body>. Next.js has no index.html. This file is the shell of every page.

// app/layout.tsximport Link from 'next/link'export default function RootLayout({ children }: { children: React.ReactNode }) {  return (    <html lang="en">      <body>        <nav>          <Link href="/">Home</Link> | <Link href="/blog">Blog</Link>        </nav>        <main>{children}</main>      </body>    </html>  )}

children is the place where the page (or the next nested layout) goes. Layouts nest. If you add app/blog/layout.tsx, it wraps /blog and /blog/[slug], and the root layout wraps it:

// app/blog/layout.tsxexport default function BlogLayout({ children }: { children: React.ReactNode }) {  return <section data-layout="blog"><p>Blog section</p>{children}</section>}

This is the HTML I got from curl for /blog/hello-world. Read it from the outside in:

<body>  <nav><a href="/">Home</a> | <a href="/blog">Blog</a> | <a href="/about">About</a></nav>  <main>    <section data-layout="blog">      <p>Blog section</p>      <h1>Post: <!-- -->hello-world</h1>    </section>  </main></body>

Root layout, then blog layout, then the page. (The <!-- --> is React's way to separate two pieces of text. It is harmless.)

Layouts keep their state

The docs say that on navigation a layout "preserves state, remains interactive and does not re-render". I wanted to see it, not just read it. I put a small button in the root layout. It is a Client Component with a counter (do not worry about the 'use client' line, lesson 1 explains it):

// app/ui/counter.tsx'use client'import { useState } from 'react'export default function Counter() {  const [n, setN] = useState(0)  return <button id="counter" onClick={() => setN(n + 1)}>clicks: {n}</button>}

Then I drove a real Chromium with Playwright: click the button 3 times, click a <Link> to /blog, then click a plain <a href="/about"> link, and print the counter each time. I also counted how many full document requests the browser made.

before nav: clicks: 3 documents so far: 1after Link click to /blog: clicks: 3 documents: 1 url: http://localhost:3100/blogafter plain <a> to /about: clicks: 0 documents: 2

This is the key result:

• With <Link>, the counter stayed at 3 and no new document was loaded (still 1 document). The browser did not reload. Only the changed part was swapped in.
• With a plain <a>, the browser did a full page load (2 documents) and the counter went back to 0.

So layouts are not re-created when you navigate between pages they share. That is why a sidebar, a music player or a half-typed search box can survive navigation.

Dynamic routes

A folder name in square brackets matches any value in that place. Three forms:

I tested these with curl against the production server. The <h1> of each page shows what params held:

/blog/hello-world   200  <h1>Post: hello-world</h1>/shop               404  <h1>Custom 404</h1>/shop/a/b           200  <h1>Shop: ["a","b"]</h1>/docs               200  <h1>Docs: null</h1>/docs/x/y           200  <h1>Docs: ["x","y"]</h1>

The catch-all gives an array. The plain [...parts] does not match /shop alone (404), but [[...rest]] does, and then the value is undefined (I printed null).

params is a Promise

This is a change that trips up many people. In this version, params is a Promise. You must await it:

// app/blog/[slug]/page.tsxexport default async function Page(props: PageProps<'/blog/[slug]'>) {  const { slug } = await props.params  return <h1>Post: {slug}</h1>}

PageProps<'/blog/[slug]'> is a global type helper. You do not import it. Next.js generates the types when you run next dev, next build or next typegen. It reads the route string and gives params the right shape. There is also LayoutProps for layouts.

What if you forget the await? I wrote params.slug without it. TypeScript caught it at build time:

app/syncp/[slug]/typed.tsx(2,22): error TS2339: Property 'slug' does not exist on type 'Promise<{ slug: string; }>'.Failed to type check.

Good. That is another reason to use TypeScript with Next.js: the framework's own changes show up as type errors.

The same rule holds for searchParams (the ?q=shoes part of the URL). It is also a Promise, and reading it makes the page dynamic, because the value only exists when a request arrives. The docs suggest the searchParams prop when you need the value to load data on the server, and the client hook useSearchParams when you only need it in the browser.

generateStaticParams and dynamicParams

If a dynamic route could be built at build time, tell Next.js which values to build. You export generateStaticParams:

export function generateStaticParams() {  return [{ slug: 'hello-world' }, { slug: 'second-post' }]}

That is the reason /blog/hello-world and /blog/second-post have a ● in the route table. They were built to HTML files at build time.

What about a value that is not in the list? By default, Next.js builds it on demand the first time someone asks, then keeps it. I asked for /blog/nope:

/blog/nope          200  <h1>Post: nope</h1>

It worked (200). If you want unknown values to be a 404 instead, set dynamicParams = false on the page. I made a second route to check:

// app/strict/[id]/page.tsxexport const dynamicParams = falseexport function generateStaticParams() { return [{ id: '1' }, { id: '2' }] }

/strict/1   200/strict/3   404

Use dynamicParams = false for a small fixed set of pages. Leave the default for things like products, where new ones appear all the time.

Links and navigation

Use the <Link> component from next/link for links between your own pages. It is a thin wrapper over <a>. You saw above what it gives you: client-side navigation, with no full reload. It also does prefetching: when a link is in view, Next.js loads that page in the background so the click feels instant. The docs say:

• For a static route, the full page is prefetched.
• For a dynamic route, prefetch is skipped, or only the part up to the nearest loading.tsx is prefetched.

A plain <a> has none of this. The docs even show it in a code comment: <Link> is prefetched when it enters the viewport or is hovered, <a> is not. Use <a> for outside links and <Link> for inside links.

import Link from 'next/link'<Link href="/blog">Blog</Link><Link href={`/blog/${post.slug}`}>{post.title}</Link><Link href="/dashboard" prefetch={false}>Dashboard</Link>   // turn prefetch off

Prefetching has a cost. A page full of links (an endless table, for example) will prefetch many routes. The docs suggest prefetch={false} for such lists. You can prefetch on hover only, by switching prefetch from false to null in an onMouseEnter handler.

Other tools for moving around:

• useRouter() (from next/navigation, in a Client Component) lets you navigate from code: router.push('/blog').
• redirect('/login') (from next/navigation) works on the server, for example inside a page or a Server Action.
• usePathname() reads the current path in a Client Component. It is how you highlight the active menu item.
• useLinkStatus() tells a <Link> child whether its navigation is still loading, so you can show a small spinner on slow networks.

In dev, a dynamic route without loading.tsx can feel stuck because the browser waits for the server. The fix is the next section.

The special files

Some file names have a fixed meaning. You already know page and layout. The others add behavior with almost no code.

These nest in a fixed order. The docs list it from the outside in: layout, template, error (an error boundary), loading (a Suspense boundary), not-found (an error boundary), then page. Each wraps the one after it. That is why an error screen shows inside your layout and the navigation stays visible.

loading.tsx

A loading.tsx next to a page wraps that page in a <Suspense> boundary for you. While the page waits for data, Next.js shows the loading file. I made a slow page and gave it a loading file:

// app/slow/page.tsxexport const dynamic = 'force-dynamic'export default async function Page() {  await new Promise(r => setTimeout(r, 1500))   // pretend the database is slow  return <h1>Slow page done</h1>}

// app/slow/loading.tsxexport default function Loading() { return <p>Loading slow page...</p> }

Then I asked for it with curl and printed the timing:

HTTP 200  total 1.530s   time to first byte 0.081s

The first byte came after 0.08 seconds, but the whole response took 1.5 seconds. The server sent the shell and the loading text first, then the finished page when it was ready. In the HTML both strings are present: Loading slow page... and Slow page done. This is streaming. We study it in lesson 6. For now remember: loading.tsx is the cheapest way to make a slow page feel fast.

error.tsx

If a page throws, the nearest error.tsx catches it. It must be a Client Component, because it has a "Try again" button that runs in the browser:

// app/boom/error.tsx'use client'export default function Error({ error, reset }: { error: Error; reset: () => void }) {  return <div><p>Something broke</p><button onClick={reset}>Try again</button></div>}

I made a page that throws new Error('kaboom') and opened it in Chromium. The text on screen was:

Home | Blog | About | About (plain a)clicks: 0Something brokeTry again

The navigation and the counter from the root layout are still there, and only the page area was replaced. In the server log I saw the real error, with a digest (an id):

⨯ Error: kaboom  digest: '2736574463'

The browser never sees the message "kaboom" in production, only the digest, so private details do not leak. You search your logs for the digest to find the real error. The HTTP status of that response was 500.

not-found.tsx

Create app/not-found.tsx and it is used for any unmatched URL, and when you call notFound() from a page. I made one that returns <h1>Custom 404</h1>. All my 404 tests above (/shop, /zzz, /_components/secret) returned it with status 404.

A quick map of the whole thing

Put it together for one URL, /blog/hello-world:

RootLayout (app/layout.tsx)  BlogLayout (app/blog/layout.tsx)    [error boundary from error.tsx, if any]      [Suspense from loading.tsx, if any]        Page (app/blog/[slug]/page.tsx)    params = { slug: "hello-world" }

When you navigate to /blog/second-post, the two layouts are kept. Only the page part is replaced.

Look inside: what the browser receives

You can see what Next.js sends. A curl of a static page gives full HTML with the content already in it (the first load needs no JavaScript to show the text). Look at the response headers of the prerendered /blog/hello-world:

HTTP/1.1 200 OKx-nextjs-cache: HITx-nextjs-prerender: 1x-nextjs-stale-time: 300Cache-Control: s-maxage=31536000Content-Type: text/html; charset=utf-8

x-nextjs-prerender: 1 and x-nextjs-cache: HIT say that this page was prerendered and served from the cache. s-maxage=31536000 lets a CDN keep it for a year (until the next deploy). This is what "static" means for performance: no code runs when the request arrives.

The same page can also be asked for in a second format, the RSC payload, which is what <Link> fetches for client-side navigation. In the build output you can see both next to each other: blog.html for the first visit and blog.rsc for navigation. Lesson 1 explains what is inside.

Common mistakes

Try it

Make a fresh app with npx create-next-app@latest my-app --yes, then:

1. Add app/blog/page.tsx and app/blog/[slug]/page.tsx. What URLs exist now? What does curl localhost:3000/blog/hi return?
2. Add app/blog/layout.tsx with a line of text. Where does that text show up: only on /blog, or on /blog/hi too?
3. Make app/(shop)/cart/page.tsx. What is the URL?
4. Make a folder app/helpers/ that only has format.ts. Is /helpers a route?
5. Add app/blog/[slug]/loading.tsx and an await new Promise(r => setTimeout(r, 2000)) in the page. Click a <Link> to it. What do you see during the wait?
6. Run npm run build. Is /blog/[slug] static or dynamic? Add generateStaticParams returning two slugs and build again. What changed in the table?
7. Throw an error in a page and add error.tsx. Does the layout stay visible?

Answers

1. /blog and /blog/<anything>. For /blog/hi you get the page with params.slug = "hi" (status 200, if you have not set dynamicParams = false).
2. On both. A layout wraps every page below its folder.
3. /cart. The (shop) group does not appear in the URL.
4. No. A folder with no page or route file is not public. It is a safe place for helpers.
5. The loading UI appears at once, and the layout stays. When the wait ends, the real page replaces it.
6. First it is ƒ (dynamic). After generateStaticParams, the two slugs show as ● under /blog/[slug].
7. Yes. The error screen replaces only the page area. The parent layouts stay.

Interview questions

Key takeaways

• Next.js is React plus routing, server rendering, bundling and more. This series uses the App Router (app/), not the old pages/.
• Folders are URL segments. A folder is public only when it has a page (or route) file.
• The root layout is required and holds <html> and <body>. Layouts nest and keep their state when you navigate between their pages. I proved it with a counter.
• Dynamic folders use brackets. params and searchParams are Promises, so always await them. generateStaticParams builds known values ahead of time, and dynamicParams = false makes the rest a 404.
• Use <Link> for internal links to get client-side navigation and prefetching.
• loading.tsx, error.tsx and not-found.tsx give you loading, error and 404 screens by file name. error.tsx must be a Client Component.
• Read the route table from next build. ○ is static, ● is prerendered with generateStaticParams, ƒ is dynamic.
• When you are unsure about this version, read the docs inside node_modules/next/dist/docs/.

What's next

Next: Server Components and Client Components. Every component in the app folder is a Server Component by default, and that changes where your code runs and what the browser downloads. You will see the difference in a real bundle, learn what 'use client' really does, and learn how a careless prop can leak a password hash into the page. Practise now: make the small blog from this lesson and read the route table after next build.