Understanding File-Based Routing in Next.js

1 · Why File-Based Routing?

Traditional React apps rely on code-driven routers (e.g., React Router). Next.js flips the model: your filesystem is the router. This approach offers:

• Zero configuration—drop a file, get a route.

• Conventions over configuration—team-wide consistency.

• Colocation—components, tests, and styles live next to the page that uses them. nextjs.org

2 · Anatomy of the App Router

Inside the app/ directory (introduced in Next.js 13 and stable in 15) every folder and “special file” has a role:

Only page.js (UI) and route.js (API) are publicly addressable; everything else is just for composition. nextjs.orgnextjs.org

Folder = “segment”

A segment is one level of the URL path. Nest folders to build deeper paths:

app/
├─ dashboard/
│  ├─ layout.js
│  ├─ page.js          →  /dashboard
│  └─ settings/
│     └─ page.js       →  /dashboard/settings

3 · Dynamic Routes

Place the segment name in square brackets to capture a param:

Dynamic segments pair naturally with data fetching in Server Components or Route Handlers. nextjs.org

4 · Route Groups & Colocation

Need to group files without affecting the URL? Wrap the folder name in parentheses:

app/
└─ (marketing)/
   └─ about/
      └─ page.js   → URL is simply /about

You can also colocate non-route files—utilities, styles, tests—inside any segment because only page.js / route.js become public routes. nextjs.org

5 · Pages Router vs App Router Quick-Look

Migrating is incremental—pages/ and app/ can coexist while you move routes. nextjs.org

6 · Route Handlers (API in the App Router)

The App Router replaces pages/api/* with route.js (or .ts). Export the HTTP verbs you need:

// app/api/hello/route.js
export async function GET() {
  return Response.json({ hello: 'world' });
}

Handlers run in the edge runtime by default and share the same path conventions as pages. nextjs.org

7 · Advanced Patterns

• Parallel Routes & Intercepting—render multiple segments side-by-side or hijack a sibling route ((modal)/@modal). nextjs.org

• Middleware (middleware.ts)—regex-based guard runs before the route file system match.

• Internationalized routes—combine middleware.ts with headers() to rewrite /es/blog.

8 · Common Pitfalls & Tips

1. Missing layout.js at the root → your nested layouts may not render; create one early.

2. Dynamic mismatch—[id] folder but forgetting to read params.id in the page component.

3. Client-only code inside Server Components—add "use client" at the top of the file or move logic to a nested Client.tsx.

4. Large asset imports—remember only what page.js returns is shipped; colocated helper files aren’t.

9 · When to Reach for the Pages Router

• You’re maintaining a legacy Next.js 12 project.

• You need quick static pages without learning new conventions.

Otherwise, the App Router’s streaming, layouts, and colocated route handlers make it the forward-compatible choice.

10 · Key Takeaways

• Folder names become URL segments; page.js is the render target.

• Dynamic segments ([id], [...slug]) make paramized paths trivial.

• Layouts, loading, and error files give instant UX scaffolding.

• Route Handlers turn any segment into an API endpoint.

• The App Router is the future; migrate incrementally from pages/.

With these conventions, you can scaffold an entire production app without ever touching a router config. Drop a file, write your component, and ship 🚀