Next.js Routing

Next.js Routing: How the App Router Maps Folders to URLs

Next.js routing uses folders inside the app/ directory to define URL paths without a central router config file. Every folder represents a URL segment, and a page.tsx file inside that folder makes the route reachable in a browser.

If a folder does not contain a page.tsx file, users cannot visit that path directly. This lets you keep helper components or styles close to a route safely.

flowchart TD
    app["app/"] --> home["page.tsx -> /"]
    app --> about["about/"]
    about --> aboutPage["page.tsx -> /about"]
    app --> blog["blog/"]
    blog --> slug["[slug]/"]
    slug --> slugPage["page.tsx -> /blog/:slug"]

Mapping Static Routes

To create a static URL like /pricing or /dashboard/settings, create matching nested folders inside app/ and add a page.tsx file to each endpoint.

Creating Dynamic Route Segments

Dynamic routes match changing URL values such as blog slugs, product IDs, or user handles. Wrap the folder name in square brackets, like [slug], and await params inside your async Server Component.

// app/blog/[slug]/page.tsx
interface BlogPageProps {
  params: Promise<{ slug: string }>;
}

export default async function BlogPostPage({ params }: BlogPageProps) {
  const { slug } = await params;

  return (
    <article className="max-w-3xl mx-auto p-6">
      <h2 className="text-2xl font-bold capitalize">{slug.replaceAll('-', ' ')}</h2>
      <p className="mt-3 text-gray-600">Loaded dynamic route for slug: {slug}</p>
    </article>
  );
}

Organizing Routes with Route Groups

Route groups let you split routes into logical areas without changing the public URL. Wrap a folder name in parentheses, such as (marketing) or (account), and Next.js omits that folder name from the URL path.

app/
├── (marketing)/
│   ├── layout.tsx
│   ├── about/page.tsx      -> /about
│   └── pricing/page.tsx    -> /pricing
└── (account)/
    ├── layout.tsx
    └── profile/page.tsx    -> /profile

Common Mistakes

• Forgetting to await params in Next.js 15+: Dynamic params is a Promise in modern App Router pages, so read it with await params.
• Naming page files after the route: Name the file page.tsx inside app/about/, not app/about.tsx.
• Conflicting dynamic and static paths at the same level: Avoid placing two dynamic folders with different parameter names inside the same parent folder.

Frequently Asked Questions

What happens if a folder inside app/ has no page.tsx file?

The folder does not expose a public URL route. You can safely store local components, types, or test files inside it.

How do catch-all routes work in Next.js?

Use [...slug] in a folder name to match multiple nested segments, such as /docs/auth/tokens, as an array of strings.

Why use route groups instead of regular folders?

Route groups let different sections use separate layout.tsx shells while keeping clean, short public URLs.