Understanding Next.js Routing

File-based routing in Next.js is simple — until it isn't.

If you've ever stared at a 404 and wondered why your page won't load, the problem is almost never React.
It's usually how your files are organized.

Let me break down how Next.js routing actually works.

The App Router Mindset

Since Next.js 13, the app/ directory uses file-based routing.
The structure of your folders becomes the structure of your URLs.

There's one rule that makes everything click:

Folders define routes. Files define UI.

That's it.
Every folder inside app/ becomes a segment of your URL.

Notice the special files:

• page.tsx → defines the UI for that route
• [slug] → a dynamic segment (changes per URL)
• Folders without a page.tsx? → not routable

Static vs. Dynamic Routes

Static routes are easy. You create a folder, add page.tsx, done.

Dynamic routes are where people get confused.
The [slug] syntax means "this part of the URL is a variable."

In Next.js 15, params and searchParams are Promises — you must await them. This unlocks streaming and better caching.

Catch-all and Optional Catch-all

Sometimes you don't know how deep a URL goes.
Think documentation sites: /docs/getting-started/installation.

| Syntax | Matches | Example | |---|---|---| | [...slug] | /docs/a/b/c (at least one) | Catch-all | | [[...slug]] | /docs, /docs/a/b (zero or more) | Optional catch-all |

Layouts Wrap Your Pages

Here's something that confused me at first:

Layouts don't replace pages. They wrap them.

layout.tsx renders around every page.tsx inside the same folder (and all subfolders). This is perfect for headers, sidebars, and footers that shouldn't reload on navigation.

Loading and Error States

Two more special files make your app feel instant:

• loading.tsx shows while page.tsx is fetching data
• error.tsx catches errors for that segment (must be a Client Component)

Navigation With Link

For client-side navigation (no full reload), use next/link:

For programmatic navigation (after a form submit, for example), reach for useRouter:

Route Groups: Organization Without URL Changes

Sometimes you want to group routes for layout purposes without affecting the URL.

Wrap a folder name in parentheses: (group).

(marketing) and (dashboard) are not in the URL.
They only exist to share layouts.

The Mental Model That Helped Me

When I stopped memorizing syntax and started thinking in segments, everything clicked:

1. Folder = URL segment
2. page.tsx = the content of that segment
3. layout.tsx = the wrapper around all pages in that segment
4. [param] = a variable part of the URL
5. loading.tsx / error.tsx = what users see while waiting or when it breaks

Your Next Step

Open your app/ directory and map every folder to its URL.
Then create one new route with:

• A page.tsx
• A loading.tsx
• A dynamic [slug] segment

Once you build that tiny structure and watch the URLs resolve, the "magic" of Next.js routing becomes a tool you actually control.