Routing Fundamentals

Next.js 13 introduced a new file-system based router built on top of React Server Components with support for layouts, nested routing, loading states, error handling, and more.

This page will introduce you to the fundamental concepts of the new routing model.

Terminology

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

A tree of folders with a subtree, root, and leaves
  • 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.
Anatomy of a URL
  • URL Path: Part of the URL that comes after the domain.
  • URL Segment: Part of the URL path delimited by slashes.

The app Directory

The new 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.

Good to know: Routes across directories should not resolve to the same URL path and will cause a build-time error to prevent a conflict.

The new app directory with folders as routes

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

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

Folders and Files inside app

In the app directory:

  • 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.
  • 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.

Route segments mapping 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)

Special Files

Next.js provides a set of special files that you can use in your routes. These files are:

A folder of special files with the components they render
  • page.tsx: A file used to define the unique UI of a route and make the path publicly accessible.
  • layout.tsx: A file used to define UI that is shared across multiple pages. A layout accepts another layout or a page as its child. You can nest layouts to create nested routes.
  • loading.tsx: An optional file used to create loading UI for a specific part of an app. It automatically wraps a page or child layout in a React Suspense Boundary, showing your loading component immediately on the first load and when navigating between sibling routes.
  • error.tsx: An optional file used to isolate errors to specific parts of an app, show specific error information, and functionality to attempt to recover from the error. It automatically wraps a page or child layout in a React Error Boundary. Showing your error component whenever an error in a subtree is caught.
  • template.tsx: An optional file, similar to layouts, but on navigation, a new instance of the component is mounted and the state is not shared. You can use templates for cases where you require this behavior, such as enter/exit animations.
  • head.tsx: An optional file used to define the contents of the <head> tag for a given route.

Good to know: js, jsx or tsx file extensions can be used for special files. ts is currently not supported.

Colocation

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

An example folder of colocated files

Server-Centric Routing with Client-side Navigation

Unlike the pages directory which uses client-side routing, the new router in the app directory 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 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, 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.

Partial Rendering

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

In the future, the Next.js Router will provide a set of 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.
  • Conditional Routes: Allow you to conditionally render a route based on a condition. E.g. Showing a page only if the user is logged in.

These patterns and conventions will allow you to build richer, more complex UIs in your Next.js applications.

Next Steps