Next.js App Router and File-Based Routing Explained

A neighbourhood tool library wants a website: a home page, a list of tools, and a page for each tool. In a plain React single-page app you would install a router, write a route table and keep it in sync with your files. Next.js removes that step. You create folders and special files inside an app/ directory, and the folder names become the URLs. The structure of your project is the route table.

Folders are segments, page.tsx makes them public

Each folder inside app/ is a URL segment, but a folder only becomes a reachable page when it contains a file named page.tsx (or .js, .jsx, .ts). That means you can keep helper files such as components next to your routes without accidentally publishing them. Here is the tool library laid out on disk, with the URL each file creates.

app/
  layout.tsx                -> wraps every page
  page.tsx                  -> /
  not-found.tsx             -> any unmatched URL
  (info)/
    about/
      page.tsx              -> /about
  tools/
    layout.tsx              -> wraps /tools and below
    loading.tsx             -> shown while /tools loads
    error.tsx               -> shown if /tools throws
    page.tsx                -> /tools
    [toolId]/
      page.tsx              -> /tools/drill, /tools/ladder
  api/
    health/
      route.ts              -> GET /api/health (JSON)

Three details are worth noticing. Parentheses make a route group: (info) organises files without appearing in the URL, so /about not /info/about. Square brackets make a dynamic segment: [toolId] matches any single value and hands it to your code as a parameter. And a route.ts file creates an HTTP endpoint instead of a page, so a folder cannot contain both a page and a route at the same level.

The root layout and the first page

Every App Router project needs a root layout at app/layout.tsx. It must render the html and body tags, because Next.js does not add them for you. A layout receives the current page as children, and it stays mounted when you navigate between pages beneath it, so its state and DOM are preserved.

import type { Metadata } from "next";
import Link from "next/link";
import type { ReactNode } from "react";

export const metadata: Metadata = {
  title: { default: "Toolshed", template: "%s | Toolshed" },
  description: "Borrow tools from neighbours instead of buying them.",
};

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <nav>
          <Link href="/">Home</Link> <Link href="/tools">Tools</Link> <Link href="/about">About</Link>
        </nav>
        {children}
      </body>
    </html>
  );
}

import Link from "next/link";

export default function HomePage() {
  return (
    <main>
      <h1>Borrow, do not buy</h1>
      <p>Forty-two neighbours share drills, ladders and a tile cutter.</p>
      <Link href="/tools">Browse the shelf</Link>
    </main>
  );
}

Visiting / renders the navigation bar from the layout with three links on one line, followed by the heading, the sentence and a link. Clicking "Tools" does not reload the whole document: Link fetches what is needed for the new page and swaps it in, and the nav stays exactly where it is. The metadata export sets the tab title to "Toolshed" and, thanks to the template, child pages that export a title of "Drill" will show "Drill | Toolshed".

Dynamic routes, params and not-found

A page inside a dynamic folder receives the segment values through a params prop. In Next.js 15 and later, params is a Promise that you await; in earlier versions it was a plain object. Check the version in your package.json, because the type you write differs, and the examples here use the newer form. Missing records should call notFound(), which renders the nearest not-found.tsx and sends a 404 status.

// lib/tools.ts
export type Tool = { id: string; name: string; deposit: number };

const TOOLS: Tool[] = [
  { id: "drill", name: "Cordless drill", deposit: 20 },
  { id: "ladder", name: "Three-step ladder", deposit: 10 },
  { id: "tile-cutter", name: "Tile cutter", deposit: 35 },
];

export function listTools(): Tool[] {
  return TOOLS;
}

export function findTool(id: string): Tool | undefined {
  return TOOLS.find((tool) => tool.id === id);
}

// app/tools/[toolId]/page.tsx
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { findTool } from "@/lib/tools";

type Props = { params: Promise<{ toolId: string }> };

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { toolId } = await params;
  const tool = findTool(toolId);
  return { title: tool ? tool.name : "Tool not found" };
}

export default async function ToolPage({ params }: Props) {
  const { toolId } = await params;
  const tool = findTool(toolId);
  if (!tool) notFound();

  return (
    <article>
      <h1>{tool.name}</h1>
      <p>Refundable deposit: {tool.deposit} pounds.</p>
    </article>
  );
}

Going to /tools/ladder shows a heading "Three-step ladder" with the deposit line beneath it and the tab title "Three-step ladder | Toolshed". Going to /tools/chainsaw finds no record, so notFound() stops rendering and the not-found page appears with a 404 status. The @/ import alias is configured by the project template in tsconfig.json; if you chose not to enable it, use relative imports.

Files for every state of a route

"use client";

export default function ToolsError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <section>
      <h2>The shelf could not be loaded</h2>
      <p>Please try again. Reference: {error.digest ?? "none"}</p>
      <button type="button" onClick={() => reset()}>Try again</button>
    </section>
  );
}

Common mistakes

• Creating a folder without `page.tsx`. The URL returns 404 because nothing is public until a page file exists.
• A root layout without `html` and `body`. Next.js reports an error that the root layout is missing the required tags, and the page does not render.
• Using `<a href>` for internal links. It works but triggers a full page load and loses the layout state; use Link from next/link.
• Forgetting `"use client"` in `error.tsx`. The build fails, since error boundaries need client-side behaviour and event handlers.
• Accessing `params.toolId` directly in newer versions. Next.js 15 logs a warning that params should be awaited before its properties are used; in later releases it is an error.
• Wrong folder casing. app/Tools/page.tsx creates /Tools, not /tools, and URL matching is case-sensitive on most hosts.

How this shows up in real projects and interviews

In a code review you will mostly be asked to place things correctly: shared chrome in a layout, a per-page title in metadata, empty states in not-found, and loading UI in loading.tsx. Interviewers for React roles that use Next.js often ask how routing differs from React Router and what a layout is. A good answer says routes come from the file system, layouts persist across navigations, and special files provide loading, error and not-found states per segment. Older projects may still use the pages/ directory; both routers can coexist during migration, but new work generally targets app/.