Routing and special files

Read app as a route tree

A page.tsx makes a segment reachable. A layout.tsx wraps that segment and its descendants. Nested folders create nested URL segments, while route groups organise code without appearing in the URL.

The useful part of nested routing is not the folder syntax itself. It is that shared UI can live at the level where it actually belongs.

app/
├─ layout.tsx
├─ page.tsx
├─ (marketing)/
│  ├─ about/page.tsx
│  └─ projects/
│     ├─ page.tsx
│     └─ [slug]/page.tsx
├─ dashboard/
│  ├─ layout.tsx
│  ├─ loading.tsx
│  ├─ error.tsx
│  └─ settings/page.tsx
└─ api/projects/route.ts

The files worth remembering

• page.tsx exposes UI for a route.
• layout.tsx wraps a segment and descendants while preserving shared UI across navigation.
• template.tsx is similar to a layout but creates a new instance on navigation.
• loading.tsx supplies a route-level Suspense fallback.
• error.tsx catches uncaught runtime errors for a segment and is a Client Component.
• global-error.tsx is the last error boundary around the root layout.
• not-found.tsx renders missing-resource UI.
• route.ts creates an HTTP Route Handler.
• default.tsx supplies a fallback for unmatched parallel-route slots.

Dynamic segments are for resource identity

Use [slug] when a URL segment identifies a resource. Catch-all segments such as [...slug] can represent a path of arbitrary depth, while [[...slug]] also allows the empty case.

Do not force every piece of state into the pathname. Resource identity usually belongs in segments; sorting, filtering, search, and pagination often fit search parameters better.

app/projects/[slug]/page.tsx       // /projects/project-a
app/docs/[...segments]/page.tsx      // /docs/react/server
app/shop/[[...category]]/page.tsx    // /shop or /shop/shoes

Route groups organise without changing the URL

A folder wrapped in parentheses is omitted from the public URL. app/(marketing)/about/page.tsx still maps to /about.

They are useful for code organisation and layout boundaries. They are not an access-control mechanism.

Parallel and intercepting routes solve specific UI problems

Parallel routes use named slots such as @activity to render independently routed regions in one layout. Intercepting routes let navigation display another route inside the current context, such as opening a photo in a modal from a gallery while keeping the photo URL directly addressable.

Both are useful when the interaction genuinely needs routing semantics. They also make the route tree harder to reason about, so ordinary nested routes should remain the default.