From 26e8b765aed579f996a5aa624cc9542cb4edc109 Mon Sep 17 00:00:00 2001 From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com> Date: Fri, 13 Dec 2024 13:16:26 +0000 Subject: [PATCH] Docs clean up: Merge and delete content from `routing/index.mdx` (#73859) Please merge this PR first: https://github.com/vercel/next.js/pull/73858 Closes: https://linear.app/vercel/issue/DOC-4049/delete-routingindexmdx The content for this page has already been moved to the `Getting Started` section or `API Reference`. --------- Co-authored-by: Rich Haines --- .../02-project-structure.mdx | 39 ++++- .../01-routing/01-defining-routes.mdx | 4 +- .../01-routing/02-pages.mdx | 2 +- .../01-routing/05-error-handling.mdx | 2 +- .../01-routing/11-parallel-routes.mdx | 2 +- .../01-routing/index.mdx | 155 ------------------ .../11-upgrading/05-app-router-migration.mdx | 6 +- .../03-file-conventions/index.mdx | 2 +- .../10-upgrading/06-version-13.mdx | 2 +- errors/prerender-error.mdx | 2 +- 10 files changed, 45 insertions(+), 171 deletions(-) diff --git a/docs/01-app/01-getting-started/02-project-structure.mdx b/docs/01-app/01-getting-started/02-project-structure.mdx index 15add87f235b5..1681cabb5a64c 100644 --- a/docs/01-app/01-getting-started/02-project-structure.mdx +++ b/docs/01-app/01-getting-started/02-project-structure.mdx @@ -66,10 +66,10 @@ Top-level files are used to configure your application, manage dependencies, run ### Nested routes -| | | -| ---------------------------------------------------------------------------- | -------------------- | -| [`folder`](/docs/app/building-your-application/routing#route-segments) | Route segment | -| [`folder/folder`](/docs/app/building-your-application/routing#nested-routes) | Nested route segment | +| | | +| --------------- | -------------------- | +| `folder` | Route segment | +| `folder/folder` | Nested route segment | ### Dynamic routes @@ -168,13 +168,42 @@ Top-level files are used to configure your application, manage dependencies, run +## 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` + +Component Hierarchy for File Conventions + +In a nested route, the components of a segment will be nested **inside** the components of its parent segment. + +Nested File Conventions Component Hierarchy + ## Organizing your project Apart from [folder and file conventions](/docs/app/getting-started/project-structure), Next.js is **unopinionated** about how you organize and colocate your project files. But it does provide several features to help you organize your project. ### Colocation -In the `app` directory, [nested folder hierarchy](/docs/app/building-your-application/routing#route-segments) defines route structure. Each folder represents a route segment that is mapped to a corresponding segment in a URL path. +In the `app` directory, nested folders define route structure. Each folder represents a route segment that is mapped to a corresponding segment in a URL path. However, even though route structure is defined through folders, a route is **not publicly accessible** until a `page.js` or `route.js` file is added to a route segment. diff --git a/docs/01-app/03-building-your-application/01-routing/01-defining-routes.mdx b/docs/01-app/03-building-your-application/01-routing/01-defining-routes.mdx index 01bb4bc688ea8..2037ef356d5ea 100644 --- a/docs/01-app/03-building-your-application/01-routing/01-defining-routes.mdx +++ b/docs/01-app/03-building-your-application/01-routing/01-defining-routes.mdx @@ -15,7 +15,7 @@ This page will guide you through how to define and organize routes in your Next. Next.js uses a file-system based router where **folders** are used to define routes. -Each folder represents a [**route** segment](/docs/app/building-your-application/routing#route-segments) that maps to a **URL** segment. To create a [nested route](/docs/app/building-your-application/routing#nested-routes), you can nest folders inside each other. +Each folder represents a **route segment** that maps to a **URL** segment. To create a nested route, you can nest folders inside each other. Route segments to path segments **Good to know**: > > - The `.js`, `.jsx`, or `.tsx` file extensions can be used for Pages. -> - A page is always the [leaf](/docs/app/building-your-application/routing#terminology) of the [route subtree](/docs/app/building-your-application/routing#terminology). +> - A page is always the **leaf** of the route subtree. > - A `page.js` file is required to make a route segment publicly accessible. > - Pages are [Server Components](/docs/app/building-your-application/rendering/server-components) by default, but can be set to a [Client Component](/docs/app/building-your-application/rendering/client-components). > - Pages can fetch data. View the [Data Fetching](/docs/app/building-your-application/data-fetching) section for more information. diff --git a/docs/01-app/03-building-your-application/01-routing/05-error-handling.mdx b/docs/01-app/03-building-your-application/01-routing/05-error-handling.mdx index 7c28e397dce38..9a80e88c2deb1 100644 --- a/docs/01-app/03-building-your-application/01-routing/05-error-handling.mdx +++ b/docs/01-app/03-building-your-application/01-routing/05-error-handling.mdx @@ -215,7 +215,7 @@ If you want errors to bubble up to the parent error boundary, you can `throw` wh ### Handling Errors in Nested Routes -Errors will bubble up to the nearest parent error boundary. This allows for granular error handling by placing `error.tsx` files at different levels in the [route hierarchy](/docs/app/building-your-application/routing#component-hierarchy). +Errors will bubble up to the nearest parent error boundary. This allows for granular error handling by placing `error.tsx` files at different levels in the [route hierarchy](/docs/app/getting-started/project-structure#component-hierarchy). Nested Error Component Hierarchy **Good to know**: > diff --git a/docs/01-app/03-building-your-application/01-routing/index.mdx b/docs/01-app/03-building-your-application/01-routing/index.mdx index 366549e83ad0d..79b3344dd5517 100644 --- a/docs/01-app/03-building-your-application/01-routing/index.mdx +++ b/docs/01-app/03-building-your-application/01-routing/index.mdx @@ -3,158 +3,3 @@ title: Routing Fundamentals nav_title: Routing description: Learn the fundamentals of routing for front-end applications. --- - -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: - -Terminology for Component Tree - -- **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. - -Terminology for URL Anatomy - -- **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` Router - -In version 13, Next.js introduced a new **App Router** built on [React Server Components](/docs/app/building-your-application/rendering/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](/docs/pages/building-your-application/routing) documentation. - -> **Good to know**: 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. - -Next.js App Directory - -By default, components inside `app` are [React Server Components](/docs/app/building-your-application/rendering/server-components). This is a performance optimization and allows you to easily adopt them, and you can also use [Client Components](/docs/app/building-your-application/rendering/client-components). - -> **Recommendation:** Check out the [Server](/docs/app/building-your-application/rendering/server-components) page if you're new to Server Components. - -## Roles of Folders and Files - -Next.js uses a file-system based router where: - -- **Folders** are used to define routes. A route is a single path of nested folders, following the file-system hierarchy from the **root folder** down to a final **leaf folder** that includes a `page.js` file. See [Defining Routes](/docs/app/building-your-application/routing/defining-routes). -- **Files** are used to create UI that is shown for a route segment. See [special files](#file-conventions). - -## 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: - -| | | -| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| [`layout`](/docs/app/building-your-application/routing/layouts-and-templates#layouts) | Shared UI for a segment and its children | -| [`page`](/docs/app/building-your-application/routing/pages) | Unique UI of a route and make routes publicly accessible | -| [`loading`](/docs/app/building-your-application/routing/loading-ui-and-streaming) | Loading UI for a segment and its children | -| [`not-found`](/docs/app/api-reference/file-conventions/not-found) | Not found UI for a segment and its children | -| [`error`](/docs/app/building-your-application/routing/error-handling) | Error UI for a segment and its children | -| [`global-error`](/docs/app/building-your-application/routing/error-handling) | Global Error UI | -| [`route`](/docs/app/building-your-application/routing/route-handlers) | Server-side API endpoint | -| [`template`](/docs/app/building-your-application/routing/layouts-and-templates#templates) | Specialized re-rendered Layout UI | -| [`default`](/docs/app/api-reference/file-conventions/default) | Fallback UI for [Parallel Routes](/docs/app/building-your-application/routing/parallel-routes) | - -> **Good to know**: `.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` - -Component Hierarchy for File Conventions - -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 (e.g. components, styles, tests, etc) inside folders in the `app` directory. - -This is because while folders define routes, only the contents returned by `page.js` or `route.js` are publicly addressable. - -An example folder structure with colocated files - -Learn more about [Project Organization and Colocation](/docs/app/getting-started/project-structure#colocation). - -## Advanced Routing Patterns - -The App Router also provides a set of conventions to help you implement more advanced routing patterns. These include: - -- [Parallel Routes](/docs/app/building-your-application/routing/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](/docs/app/building-your-application/routing/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. - -## Next Steps - -Now that you understand the fundamentals of routing in Next.js, follow the links below to create your first routes: diff --git a/docs/01-app/03-building-your-application/11-upgrading/05-app-router-migration.mdx b/docs/01-app/03-building-your-application/11-upgrading/05-app-router-migration.mdx index 8b513f0209ffd..51e6222731af8 100644 --- a/docs/01-app/03-building-your-application/11-upgrading/05-app-router-migration.mdx +++ b/docs/01-app/03-building-your-application/11-upgrading/05-app-router-migration.mdx @@ -45,7 +45,7 @@ After you've updated, see the following sections for next steps: Next.js 13 introduced the new [App Router](/docs/app/building-your-application/routing) with new features and conventions. The new Router is available in the `app` directory and co-exists with the `pages` directory. -Upgrading to Next.js 13 does **not** require using the new [App Router](/docs/app/building-your-application/routing#the-app-router). You can continue using `pages` with new features that work in both directories, such as the updated [Image component](#image-component), [Link component](#link-component), [Script component](#script-component), and [Font optimization](#font-optimization). +Upgrading to Next.js 13 does **not** require using the App Router. You can continue using `pages` with new features that work in both directories, such as the updated [Image component](#image-component), [Link component](#link-component), [Script component](#script-component), and [Font optimization](#font-optimization). ### `` Component @@ -100,13 +100,13 @@ See the [Font Optimization](/docs/app/building-your-application/optimizing/fonts > **🎥 Watch:** Learn how to incrementally adopt the App Router → [YouTube (16 minutes)](https://www.youtube.com/watch?v=YQMSietiFm0). -Moving to the App Router may be the first time using React features that Next.js builds on top of such as Server Components, Suspense, and more. When combined with new Next.js features such as [special files](/docs/app/building-your-application/routing#file-conventions) and [layouts](/docs/app/building-your-application/routing/layouts-and-templates#layouts), migration means new concepts, mental models, and behavioral changes to learn. +Moving to the App Router may be the first time using React features that Next.js builds on top of such as Server Components, Suspense, and more. When combined with new Next.js features such as [special files](/docs/app/api-reference/file-conventions) and [layouts](/docs/app/api-reference/file-conventions/layout), migration means new concepts, mental models, and behavioral changes to learn. We recommend reducing the combined complexity of these updates by breaking down your migration into smaller steps. The `app` directory is intentionally designed to work simultaneously with the `pages` directory to allow for incremental page-by-page migration. - The `app` directory supports nested routes _and_ layouts. [Learn more](/docs/app/building-your-application/routing). - Use nested folders to [define routes](/docs/app/building-your-application/routing/defining-routes) and a special `page.js` file to make a route segment publicly accessible. [Learn more](#step-4-migrating-pages). -- [Special file conventions](/docs/app/building-your-application/routing#file-conventions) are used to create UI for each route segment. The most common special files are `page.js` and `layout.js`. +- [Special file conventions](/docs/app/api-reference/file-conventions) are used to create UI for each route segment. The most common special files are `page.js` and `layout.js`. - Use `page.js` to define UI unique to a route. - Use `layout.js` to define UI that is shared across multiple routes. - `.js`, `.jsx`, or `.tsx` file extensions can be used for special files. diff --git a/docs/01-app/04-api-reference/03-file-conventions/index.mdx b/docs/01-app/04-api-reference/03-file-conventions/index.mdx index 6035ac98ecd8d..d98cc138c5c3f 100644 --- a/docs/01-app/04-api-reference/03-file-conventions/index.mdx +++ b/docs/01-app/04-api-reference/03-file-conventions/index.mdx @@ -1,4 +1,4 @@ --- title: File Conventions -description: API Reference for Next.js Special Files. +description: API Reference for Next.js File Conventions. --- diff --git a/docs/02-pages/02-building-your-application/10-upgrading/06-version-13.mdx b/docs/02-pages/02-building-your-application/10-upgrading/06-version-13.mdx index 337008d8f26dc..9457f9affe399 100644 --- a/docs/02-pages/02-building-your-application/10-upgrading/06-version-13.mdx +++ b/docs/02-pages/02-building-your-application/10-upgrading/06-version-13.mdx @@ -37,7 +37,7 @@ bun add next@13 react@latest react-dom@latest eslint-config-next@13 ## Migrating shared features -Next.js 13 introduces a new [`app` directory](/docs/app/building-your-application/routing) with new features and conventions. However, upgrading to Next.js 13 does **not** require using the new [`app` directory](/docs/app/building-your-application/routing#the-app-router). +Next.js 13 introduces a new [`app` directory](/docs/app/building-your-application/routing) with new features and conventions. However, upgrading to Next.js 13 does **not** require using the new `app` Router. You can continue using `pages` with new features that work in both directories, such as the updated [Image component](#image-component), [Link component](#link-component), [Script component](#script-component), and [Font optimization](#font-optimization). diff --git a/errors/prerender-error.mdx b/errors/prerender-error.mdx index afa5106ff1774..4996def83a185 100644 --- a/errors/prerender-error.mdx +++ b/errors/prerender-error.mdx @@ -33,7 +33,7 @@ styles/ #### App Router (Next.js 13+) -The App Router allows [colocation](/docs/app/building-your-application/routing#colocation) of pages and other files in the same folder. This provides a more intuitive project structure. +The App Router allows [colocation](/docs/app/getting-started/project-structure#colocation) of pages and other files in the same folder. This provides a more intuitive project structure. Example folder structure: