Routing Fundamentals

The skeleton of every application is routing. This page will introduce you to the fundamental concepts of routing for the web and how to handle routing in Next.js.

Terminology

First, you will see these terms being used throughout the documentation. Here's a quick reference:

Tree: A convention for visualizing a hierarchical structure. For example, a component tree with parent and children components, a folder structure, etc.
Subtree:: Part of a tree, starting at a new root (first) and ending at the leaves (last).
Root: The first node in a tree or subtree, such as a root layout.
Leaf: Nodes in a subtree that have no children, such as the last segment in a URL path.
URL Segment: Part of the URL path delimited by slashes.
URL Path: Part of the URL that comes after the domain (composed of segments).

The `app` Directory

In version 13, Next.js introduced a new App Router built on React Server Components, which supports shared layouts, nested routing, loading states, error handling, and more.

The App Router works in a new directory named app. The app directory works alongside the pages directory to allow for incremental adoption. This allows you to opt some routes of your application into the new behavior while keeping other routes in the pages directory for previous behavior. If your application uses the pages directory, please also see the Pages Router documentation.

The App Router takes priority over the Pages Router. Routes across directories should not resolve to the same URL path and will cause a build-time error to prevent a conflict.

By default, components inside app are React Server Components. This is a performance optimization and allows you to easily adopt them, and you can also use Client Components.

Recommendation: Check out the Server and Client Components page if you're new to Server Components.

Roles of Folders and Files

In the App Router:

Folders are used to define routes. A route is a single path of nested folders, following the hierarchy from the root folder down to a final leaf folder that includes a page.js file.

Files are used to create UI that is shown for the route segment. See special files.

Route Segments

Each folder in a route represents a route segment. Each route segment is mapped to a corresponding segment in a URL path.

How Route Segments Map to URL Segments

Nested Routes

To create a nested route, you can nest folders inside each other. For example, you can add a new /dashboard/settings route by nesting two new folders in the app directory.

The /dashboard/settings route is composed of three segments:

/ (Root segment) dashboard (Segment) settings (Leaf segment)

File Conventions

Next.js provides a set of special files to create UI with specific behavior in nested routes:

page.js: Create the unique UI of a route and make the path publicly accessible.
- route.js: Create server-side API endpoints for a route.
layout.js: Create shared UI for a segment and its children. A layout wraps a page or child segment.
- template.js: Similar to layout.js, except a new component instance is mounted on navigation. Use layouts unless you need this behavior.
loading.js: Create loading UI for a segment and its children. loading.js wraps a page or child segment in a React Suspense Boundary, showing the loading UI while they load.
error.js: Create error UI for a segment and its children. error.js wraps a page or child segment in a React Error Boundary, showing the error UI if an error is caught.
- global-error.js: Similar to error.js, but specifically for catching errors in the root layout.js.
not-found.js: Create UI to show when the notFound function is thrown within a route segment or when a URL is not matched by any route.

.js, .jsx, or .tsx file extensions can be used for special files.

Component Hierarchy

The React components defined in special files of a route segment are rendered in a specific hierarchy:

layout.js
template.js
error.js (React error boundary)
loading.js (React suspense boundary)
not-found.js (React error boundary)
page.js or nested layout.js

In a nested route, the components of a segment will be nested inside the components of its parent segment.

Nested File Conventions Component Hierarchy

Colocation

In addition to special files, you have the option to colocate your own files inside folders. For example, stylesheets, tests, components, and more.

Server-Centric Routing with Client-side Navigation

Unlike the pages directory which uses client-side routing, the App Router uses server-centric routing to align with Server Components and data fetching on the server. With server-centric routing, the client does not have to download a route map and the same request for Server Components can be used to look up routes. This optimization is useful for all applications, but has a larger impact on applications with many routes.

Although routing is server-centric, the router uses client-side navigation with the Link Component - resembling the behavior of a Single-Page Application. This means when a user navigates to a new route, the browser will not reload the page. Instead, the URL will be updated and Next.js will only render the segments that change.

Additionally, as users navigate around the app, the router will store the result of the React Server Component payload in an in-memory client-side cache. The cache is split by route segments which allows invalidation at any level and ensures consistency across React's concurrent renders. This means that for certain cases, the cache of a previously fetched segment can be re-used, further improving performance.

Checkout the Linking and Navigating page to learn how to use the Link component.

Partial Rendering

When navigating between sibling routes (e.g. /dashboard/settings and /dashboard/analytics), Next.js will only fetch and render the layouts and pages in routes that change. It will not re-fetch or re-render anything above the segments in the subtree. This means that in routes that share a layout, the layout will be preserved when a user navigates between sibling pages.

Without partial rendering, each navigation would cause the full page to re-render on the server. Rendering only the segment that’s updating reduces the amount of data transferred and execution time, leading to improved performance.

Advanced Routing Patterns

The App Router also provides a set conventions to help you implement more advanced routing patterns. These include:

Parallel Routes: Allow you to simultaneously show two or more pages in the same view that can be navigated independently. You can use them for split views that have their own sub-navigation. E.g. Dashboards.
Intercepting Routes: Allow you to intercept a route and show it in the context of another route. You can use these when keeping the context for the current page is important. E.g. Seeing all tasks while editing one task or expanding a photo in a feed.

These patterns allow you to build richer and more complex UIs, democratizing features that were historically complex for small teams and individual developers to implement.

Project Structure Defining Routes