Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 72 ยท Routing

File-Based Routing

Learn how Next.js maps folders and page.tsx files to URLs, how nested routes work, what conflicts to avoid and how a URL is matched to a folder.

In many frameworks you maintain a list of routes: a file or object that says "this URL shows that component". Next.js drops the list. The file system is the router. You create folders, put a page.tsx in the ones that should be pages, and the folder names become the URL.

This idea sounds small, but it shapes everything else in the Routing chapter. Once you can read a folder tree as a list of URLs (and the other way around), dynamic segments, route groups and parallel routes are just extra naming rules on top. In this lesson you will learn the core mapping and the rules that surround it. The code and trees are real and read-only, and the two live examples are stand-ins that implement the same matching in a few lines so you can experiment.

Folders become segments

A route segment is one piece of a URL between slashes. In /blog/archive, the segments are blog and archive. In the App Router, each folder under app is one segment:

TEXT
app/
  page.tsx                 /
  about/
    page.tsx               /about
  blog/
    page.tsx               /blog
    archive/
      page.tsx             /blog/archive

Nesting folders nests URLs. To create /blog/archive, make a blog folder, an archive folder inside it and a page.tsx inside that. There is no configuration to edit and nothing to register: save the file and the route exists, even while the dev server is running.

From URL to file

Split the URL /blog/archive becomes blog, archive.
Walk the folders Open app, then blog, then archive.
Find page.tsx That file is the page to render.

No page file at the end means no page.

1 / 2
flowchart TD
    A["app/page.tsx<br/>/"]
    B["app/about/page.tsx<br/>/about"]
    C["app/blog/page.tsx<br/>/blog"]
    D["app/blog/archive/page.tsx<br/>/blog/archive"]
    R["app folder"] --> A
    R --> B
    R --> C
    C --> D

Each page file is a leaf; its URL is the path of folders above it.

The rules in detail

The root page. app/page.tsx has no folder above it, so its URL is /. There is no index file name in the App Router; the file is always called page.

A page file makes a route public. A folder such as app/blog/archive with no page file is not a route. Visiting /blog/archive shows a "not found" page, even though deeper folders may be pages. This is useful: you can have a folder purely to group a family of routes.

Only some file names count. page creates a UI route, and route creates an HTTP endpoint (see Route Handlers). Every other file in the folder is ignored by the router, which is what lets you colocate components, styles and tests next to the page, as you saw in Project Structure.

Page and route cannot share a URL. Putting both page.tsx and route.ts in the same folder is an error, because both would answer a GET request for the same path. Give the endpoint its own folder, such as app/api/status/route.ts.

Query strings and hashes are not part of the route. /blog?page=2 and /blog#top both match app/blog/page.tsx. The part after the ? is read separately, as you will see in Search Params and Navigation Hooks.

Trailing slashes are removed by default. A request for /about/ is redirected to /about. The trailingSlash option in next.config.ts reverses the preference if you need it.

Folder names become URLs, so choose them well. Use lowercase letters and hyphens, such as terms-of-service. Treat URLs as case-sensitive, so /About is not /about on most systems, and avoid spaces and special characters. Renaming a folder changes the URL, which can break links and rankings on a live site.

Conflicts

Two different files must never produce the same URL. You will meet this most often with route groups, which hide a folder name from the URL: app/(shop)/pricing/page.tsx and app/(blog)/pricing/page.tsx would both be /pricing. Next.js reports this as an error rather than guessing which one you meant. The same is true if you keep both app/page.tsx and pages/index.tsx from the older Pages Router: pick one owner per URL.

Static segments are fixed text

Every segment you have seen so far is static: the folder name is the literal text in the URL. That is why app/about only matches /about. The next two lessons introduce segments that match many values: Dynamic Routes uses [slug], and Catch-All and Optional Catch-All Routes uses [...slug]. When a URL could match both a static and a dynamic folder, the static one wins, so /blog/archive can coexist with /blog/[slug].

Creating a route does not link it anywhere. You add links with the Link component (and sometimes with a router hook), which gives you client-side navigation and prefetching. A taste of it:

TSX
// app/page.tsx (read-only)
import Link from 'next/link';

export default function Home() {
  return (
    <nav>
      <Link href="/about">About</Link>
      <Link href="/blog/archive">Archive</Link>
    </nav>
  );
}

The whole topic has its own lesson: Linking and Navigation.

Try it: a mini file router

Real framework or stand-in? Real Next.js walks your actual folders at build time and in development, and supports many more segment kinds. The Node.js program below does only the static part, but its rules match the text above: a page or route file creates a route, group folders vanish from the URL, other files are ignored, and duplicate URLs are reported. It runs on a list of strings, not on real files.

The first example turns a list of files into a route table, reports conflicts and then matches some requested URLs. It also normalizes URLs the way we described: no query string, no hash and no trailing slash.

Node.js From file paths to a route table

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Four results are worth studying. /blog/archive?page=2 still lands on the archive page, because the query string is stripped before matching. /blog/archive/old-post is a 404, because old-post.tsx is a colocated file and not a page. /cart works even though the file lives in (shop)/cart, because the group folder is dropped from the URL. And the conflict message at the top shows what happens when two files claim /pricing: the program keeps the first and reports the second, where real Next.js stops with an error. Building a tiny model and reading its output is a good habit whenever you are unsure of a rule.

The second example is an interactive version. Type a URL and see which file would render.

Type a URL, find the file

Try /cart, /about/, /blog?x=1 and /blog/archive/2024. The last one fails because nothing matches a third segment yet. You will fix that with a dynamic segment in the next lesson.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which file creates the page for the URL /blog/archive?

    Each folder is a URL segment and the page file inside the last folder is the page. A file named archive.tsx is not recognized by the router.
  2. 2. A folder app/team exists and contains only components. What does visiting /team show?

    A folder is only a route once it contains a page or route file. Components next to it do not matter to the router.
  3. 3. How is /blog?page=2 matched?

    Routing is decided by the path only. The query string is read separately by the page.
  4. 4. What happens if app/(shop)/pricing/page.tsx and app/(blog)/pricing/page.tsx both exist?

    Group folders are left out of the URL, so both files claim /pricing. Two files for one URL is an error.
  5. 5. Why can you safely put helper files next to page.tsx?

    Colocation is safe because a file must be named page or route to become reachable.

Summary

  • Folders under app are URL segments, and a page file makes the folder a public page; a route file makes it an HTTP endpoint.
  • app/page.tsx is the home page at /, and nested folders create nested URLs.
  • A folder without page or route is not a route, and other files next to a page are ignored by the router.
  • Query strings and hashes are not part of matching, and trailing slashes are removed by default.
  • Two files that resolve to the same URL are an error, and page and route cannot share a folder.
  • Static segments match fixed text; dynamic and catch-all segments, covered next, match many values.

Next: Dynamic Routes