mirror of
https://github.com/hanzoai/next.js.git
synced 2026-09-24 17:00:51 +00:00
Docs clean up: delete defining-routes.mdx and pages.mdx (#73863)
Please merge this PR first: https://github.com/vercel/next.js/pull/73859 Closes: - https://linear.app/vercel/issue/DOC-4050/delete-routingdefining-routesmdx - https://linear.app/vercel/issue/DOC-4051/delete-routingpagesmdx The content for this page has already been moved to the Getting Started section or API Reference.
This commit is contained in:
Delba de Oliveira
@@ -1,58 +0,0 @@
|
||||
---
|
||||
title: Defining Routes
|
||||
description: Learn how to create your first route in Next.js.
|
||||
related:
|
||||
description: Learn more about creating pages and layouts.
|
||||
links:
|
||||
- app/building-your-application/routing/pages
|
||||
---
|
||||
|
||||
> We recommend reading the [Routing Fundamentals](/docs/app/building-your-application/routing) page before continuing.
|
||||
|
||||
This page will guide you through how to define and organize routes in your Next.js application.
|
||||
|
||||
## Creating Routes
|
||||
|
||||
Next.js uses a file-system based router where **folders** are used to define routes.
|
||||
|
||||
Each folder represents a **route segment** that maps to a **URL** segment. To create a nested route, you can nest folders inside each other.
|
||||
|
||||
<Image
|
||||
alt="Route segments to path segments"
|
||||
srcLight="/docs/light/route-segments-to-path-segments.png"
|
||||
srcDark="/docs/dark/route-segments-to-path-segments.png"
|
||||
width="1600"
|
||||
height="594"
|
||||
/>
|
||||
|
||||
A special [`page.js` file](/docs/app/building-your-application/routing/pages) is used to make route segments publicly accessible.
|
||||
|
||||
<Image
|
||||
alt="Defining Routes"
|
||||
srcLight="/docs/light/defining-routes.png"
|
||||
srcDark="/docs/dark/defining-routes.png"
|
||||
width="1600"
|
||||
height="687"
|
||||
/>
|
||||
|
||||
In this example, the `/dashboard/analytics` URL path is _not_ publicly accessible because it does not have a corresponding `page.js` file. This folder could be used to store components, stylesheets, images, or other colocated files.
|
||||
|
||||
> **Good to know**: `.js`, `.jsx`, `.ts`, or `.tsx` file extensions can be used for special files.
|
||||
|
||||
## Creating UI
|
||||
|
||||
[Special file conventions](/docs/app/api-reference/file-conventions) are used to create UI for each route segment. The most common are [pages](/docs/app/api-reference/file-conventions/page) to show UI unique to a route, and [layouts](/docs/app/api-reference/file-conventions/layout) to show UI that is shared across multiple routes.
|
||||
|
||||
For example, to create your first page, add a `page.js` file inside the `app` directory and export a React component:
|
||||
|
||||
```tsx filename="app/page.tsx" switcher
|
||||
export default function Page() {
|
||||
return <h1>Hello, Next.js!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/page.js" switcher
|
||||
export default function Page() {
|
||||
return <h1>Hello, Next.js!</h1>
|
||||
}
|
||||
```
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
title: Pages
|
||||
description: Create your first page in Next.js
|
||||
related:
|
||||
links:
|
||||
- app/building-your-application/routing/layouts-and-templates
|
||||
- app/building-your-application/routing/linking-and-navigating
|
||||
---
|
||||
|
||||
A page is UI that is **unique** to a route. You can define a page by default exporting a component from a `page.js` file.
|
||||
|
||||
For example, to create your `index` page, add the `page.js` file inside the `app` directory:
|
||||
|
||||
<Image
|
||||
alt="page.js special file"
|
||||
srcLight="/docs/light/page-special-file.png"
|
||||
srcDark="/docs/dark/page-special-file.png"
|
||||
width="1600"
|
||||
height="444"
|
||||
/>
|
||||
|
||||
```tsx filename="app/page.tsx" switcher
|
||||
// `app/page.tsx` is the UI for the `/` URL
|
||||
export default function Page() {
|
||||
return <h1>Hello, Home page!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/page.js" switcher
|
||||
// `app/page.js` is the UI for the `/` URL
|
||||
export default function Page() {
|
||||
return <h1>Hello, Home page!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
Then, to create further pages, create a new folder and add the `page.js` file inside it. For example, to create a page for the `/dashboard` route, create a new folder called `dashboard`, and add the `page.js` file inside it:
|
||||
|
||||
```tsx filename="app/dashboard/page.tsx" switcher
|
||||
// `app/dashboard/page.tsx` is the UI for the `/dashboard` URL
|
||||
export default function Page() {
|
||||
return <h1>Hello, Dashboard Page!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/dashboard/page.js" switcher
|
||||
// `app/dashboard/page.js` is the UI for the `/dashboard` URL
|
||||
export default function Page() {
|
||||
return <h1>Hello, Dashboard Page!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**:
|
||||
>
|
||||
> - The `.js`, `.jsx`, or `.tsx` file extensions can be used for Pages.
|
||||
> - 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.
|
||||
@@ -3,7 +3,7 @@ title: Layouts and Templates
|
||||
description: Create your first shared layout in Next.js.
|
||||
---
|
||||
|
||||
The special files [layout.js](#layouts) and [template.js](#templates) allow you to create UI that is shared between [routes](/docs/app/building-your-application/routing/defining-routes#creating-routes). This page will guide you through how and when to use these special files.
|
||||
The special files [layout.js](#layouts) and [template.js](#templates) allow you to create UI that is shared between routes. This page will guide you through how and when to use these special files.
|
||||
|
||||
## Layouts
|
||||
|
||||
|
||||
@@ -271,8 +271,6 @@ export async function GET(request) {
|
||||
|
||||
### Dynamic Route Segments
|
||||
|
||||
> We recommend reading the [Defining Routes](/docs/app/building-your-application/routing/defining-routes) page before continuing.
|
||||
|
||||
Route Handlers can use [Dynamic Segments](/docs/app/building-your-application/routing/dynamic-routes) to create request handlers from dynamic data.
|
||||
|
||||
```ts filename="app/items/[slug]/route.ts" switcher
|
||||
|
||||
@@ -215,7 +215,7 @@ The `NextResponse` API allows you to:
|
||||
|
||||
To produce a response from Middleware, you can:
|
||||
|
||||
1. `rewrite` to a route ([Page](/docs/app/building-your-application/routing/pages) or [Route Handler](/docs/app/building-your-application/routing/route-handlers)) that produces a response
|
||||
1. `rewrite` to a route ([Page](/docs/app/api-reference/file-conventions/page) or [Route Handler](/docs/app/building-your-application/routing/route-handlers)) that produces a response
|
||||
2. return a `NextResponse` directly. See [Producing a Response](#producing-a-response)
|
||||
|
||||
</AppOnly>
|
||||
|
||||
@@ -31,7 +31,7 @@ To prevent creating many HTTP requests for each dynamic component, PPR is able t
|
||||
|
||||
### Incremental Adoption (Version 15)
|
||||
|
||||
In Next.js 15, you can incrementally adopt Partial Prerendering in [layouts](/docs/app/building-your-application/routing/layouts-and-templates) and [pages](/docs/app/building-your-application/routing/pages) by setting the [`ppr`](/docs/app/api-reference/config/next-config-js/ppr) option in `next.config.js` to `incremental`, and exporting the `experimental_ppr` [route config option](/docs/app/api-reference/file-conventions/route-segment-config) at the top of the file:
|
||||
In Next.js 15, you can incrementally adopt Partial Prerendering in [layouts](/docs/app/building-your-application/routing/layouts-and-templates) and [pages](/docs/app/api-reference/file-conventions/page) by setting the [`ppr`](/docs/app/api-reference/config/next-config-js/ppr) option in `next.config.js` to `incremental`, and exporting the `experimental_ppr` [route config option](/docs/app/api-reference/file-conventions/route-segment-config) at the top of the file:
|
||||
|
||||
```ts filename="next.config.ts" switcher
|
||||
import type { NextConfig } from 'next'
|
||||
|
||||
@@ -618,7 +618,7 @@ You can now use the `font-sans` and `font-mono` utility classes to apply the fon
|
||||
<AppOnly>
|
||||
When a font function is called on a page of your site, it is not globally available and preloaded on all routes. Rather, the font is only preloaded on the related routes based on the type of file where it is used:
|
||||
|
||||
- If it's a [unique page](/docs/app/building-your-application/routing/pages), it is preloaded on the unique route for that page.
|
||||
- If it's a [unique page](/docs/app/api-reference/file-conventions/page), it is preloaded on the unique route for that page.
|
||||
- If it's a [layout](/docs/app/building-your-application/routing/layouts-and-templates#layouts), it is preloaded on all the routes wrapped by the layout.
|
||||
- If it's the [root layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required), it is preloaded on all routes.
|
||||
|
||||
|
||||
@@ -125,7 +125,7 @@ Refer to the [`next/script`](/docs/app/api-reference/components/script#strategy)
|
||||
|
||||
### Offloading Scripts To A Web Worker (experimental)
|
||||
|
||||
> **Warning:** The `worker` strategy is not yet stable and does not yet work with the [`app`](/docs/app/building-your-application/routing/defining-routes) directory. Use with caution.
|
||||
> **Warning:** The `worker` strategy is not yet stable and does not yet work with the App Router. Use with caution.
|
||||
|
||||
Scripts that use the `worker` strategy are offloaded and executed in a web worker with [Partytown](https://partytown.builder.io/). This can improve the performance of your site by dedicating the main thread to the rest of your application code.
|
||||
|
||||
|
||||
@@ -105,7 +105,7 @@ Moving to the App Router may be the first time using React features that Next.js
|
||||
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).
|
||||
- Use nested folders to define 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/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.
|
||||
@@ -327,7 +327,7 @@ export default function Page() {
|
||||
|
||||
- Pages in the [`app` directory](/docs/app/building-your-application/routing) are [Server Components](/docs/app/building-your-application/rendering/server-components) by default. This is different from the `pages` directory where pages are [Client Components](/docs/app/building-your-application/rendering/client-components).
|
||||
- [Data fetching](/docs/app/building-your-application/data-fetching) has changed in `app`. `getServerSideProps`, `getStaticProps` and `getInitialProps` have been replaced with a simpler API.
|
||||
- The `app` directory uses 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.
|
||||
- The `app` directory uses nested folders to define routes and a special `page.js` file to make a route segment publicly accessible.
|
||||
- | `pages` Directory | `app` Directory | Route |
|
||||
| ----------------- | --------------------- | -------------- |
|
||||
| `index.js` | `page.js` | `/` |
|
||||
|
||||
@@ -306,7 +306,7 @@ On Next.js you declare an entrypoint for your application by creating a `page.ts
|
||||
|
||||
Since this guide is aiming to first set up our Next.js as an SPA (Single Page Application), you need your page entry point to catch all possible routes of your application. For that, create a new `[[...slug]]` directory in your `app` directory.
|
||||
|
||||
This directory is what is called an [optional catch-all route segment](/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments). Next.js uses a file-system based router where [directories are used to define routes](/docs/app/building-your-application/routing/defining-routes#creating-routes). This special directory will make sure that all routes of your application will be directed to its containing `page.tsx` file.
|
||||
This directory is what is called an [optional catch-all route segment](/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments). Next.js uses a file-system based router where folders are used to define routes. This special directory will make sure that all routes of your application will be directed to its containing `page.tsx` file.
|
||||
|
||||
**Create a new `page.tsx` file inside the `app/[[...slug]]` directory with the following content:**
|
||||
|
||||
|
||||
@@ -349,16 +349,9 @@ entrypoint of your application.
|
||||
|
||||
1. **Create a `[[...slug]]` directory in your `app` directory.**
|
||||
|
||||
Since in this guide we're aiming first to set up our Next.js as an SPA (Single Page Application),
|
||||
you need your page entrypoint to catch all possible routes of your application. For that, create a
|
||||
new `[[...slug]]` directory in your `app` directory.
|
||||
Since in this guide we're aiming first to set up our Next.js as an SPA (Single Page Application), you need your page entrypoint to catch all possible routes of your application. For that, create a new `[[...slug]]` directory in your `app` directory.
|
||||
|
||||
This directory is what is called an
|
||||
[optional catch-all route segment](/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments).
|
||||
Next.js uses a file-system based router where
|
||||
[directories are used to define routes](/docs/app/building-your-application/routing/defining-routes#creating-routes).
|
||||
This special directory will make sure that all routes of your application will be directed to its
|
||||
containing `page.tsx` file.
|
||||
This directory is what is called an [optional catch-all route segment](/docs/app/building-your-application/routing/dynamic-routes#optional-catch-all-segments). Next.js uses a file-system based router where folders are used to define routes. This special directory will make sure that all routes of your application will be directed to its containing `page.tsx` file.
|
||||
|
||||
2. **Create a new `page.tsx` file inside the `app/[[...slug]]` directory with the following content:**
|
||||
|
||||
|
||||
@@ -227,7 +227,7 @@ export default function Home() {
|
||||
|
||||
### `scroll`
|
||||
|
||||
**Defaults to `true`.** The default scrolling behavior of `<Link>` in Next.js **is to maintain scroll position**, similar to how browsers handle back and forwards navigation. When you navigate to a new [Page](/docs/app/building-your-application/routing/pages), scroll position will stay the same as long as the Page is visible in the viewport. However, if the Page is not visible in the viewport, Next.js will scroll to the top of the first Page element.
|
||||
**Defaults to `true`.** The default scrolling behavior of `<Link>` in Next.js **is to maintain scroll position**, similar to how browsers handle back and forwards navigation. When you navigate to a new [Page](/docs/app/api-reference/file-conventions/page), scroll position will stay the same as long as the Page is visible in the viewport. However, if the Page is not visible in the viewport, Next.js will scroll to the top of the first Page element.
|
||||
|
||||
When `scroll = {false}`, Next.js will not attempt to scroll to the first Page element.
|
||||
|
||||
@@ -595,7 +595,7 @@ If you'd like to scroll to a specific `id` on navigation, you can append your UR
|
||||
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Next.js will scroll to the [Page](/docs/app/building-your-application/routing/pages) if it is not visible in the viewport upon navigation.
|
||||
> - Next.js will scroll to the [Page](/docs/app/api-reference/file-conventions/page) if it is not visible in the viewport upon navigation.
|
||||
|
||||
</AppOnly>
|
||||
|
||||
@@ -1015,7 +1015,7 @@ export default function Home() {
|
||||
|
||||
<AppOnly>
|
||||
|
||||
The default scrolling behavior of `<Link>` in Next.js **is to maintain scroll position**, similar to how browsers handle back and forwards navigation. When you navigate to a new [Page](/docs/app/building-your-application/routing/pages), scroll position will stay the same as long as the Page is visible in the viewport.
|
||||
The default scrolling behavior of `<Link>` in Next.js **is to maintain scroll position**, similar to how browsers handle back and forwards navigation. When you navigate to a new [Page](/docs/app/api-reference/file-conventions/page), scroll position will stay the same as long as the Page is visible in the viewport.
|
||||
|
||||
However, if the Page is not visible in the viewport, Next.js will scroll to the top of the first Page element. If you'd like to disable this behavior, you can pass `scroll={false}` to the `<Link>` component, or `scroll: false` to `router.push()` or `router.replace()`.
|
||||
|
||||
|
||||
@@ -208,7 +208,7 @@ Examples of scripts that do not need to load immediately and can be fetched with
|
||||
|
||||
### `worker`
|
||||
|
||||
> **Warning:** The `worker` strategy is not yet stable and does not yet work with the [`app`](/docs/app/building-your-application/routing/defining-routes) directory. Use with caution.
|
||||
> **Warning:** The `worker` strategy is not yet stable and does not yet work with the App Router. Use with caution.
|
||||
|
||||
Scripts that use the `worker` strategy are off-loaded to a web worker in order to free up the main thread and ensure that only critical, first-party resources are processed on it. While this strategy can be used for any script, it is an advanced use case that is not guaranteed to support all third-party scripts.
|
||||
|
||||
|
||||
@@ -53,7 +53,7 @@ export default function RootLayout({ children }) {
|
||||
|
||||
#### `children` (required)
|
||||
|
||||
Layout components should accept and use a `children` prop. During rendering, `children` will be populated with the route segments the layout is wrapping. These will primarily be the component of a child [Layout](/docs/app/building-your-application/routing/pages) (if it exists) or [Page](/docs/app/building-your-application/routing/pages), but could also be other special files like [Loading](/docs/app/building-your-application/routing/loading-ui-and-streaming) or [Error](/docs/app/building-your-application/routing/error-handling) when applicable.
|
||||
Layout components should accept and use a `children` prop. During rendering, `children` will be populated with the route segments the layout is wrapping. These will primarily be the component of a child [Layout](/docs/app/api-reference/file-conventions/page) (if it exists) or [Page](/docs/app/api-reference/file-conventions/page), but could also be other special files like [Loading](/docs/app/building-your-application/routing/loading-ui-and-streaming) or [Error](/docs/app/building-your-application/routing/error-handling) when applicable.
|
||||
|
||||
#### `params` (optional)
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ title: page.js
|
||||
description: API reference for the page.js file.
|
||||
---
|
||||
|
||||
The `page` file is used to define a page in your Next.js application.
|
||||
The `page` file allows you to define UI that is **unique** to a route. You can create a page by default exporting a component from the file:
|
||||
|
||||
```tsx filename="app/blog/[slug]/page.tsx" switcher
|
||||
export default function Page({
|
||||
@@ -23,6 +23,13 @@ export default function Page({ params, searchParams }) {
|
||||
}
|
||||
```
|
||||
|
||||
## Good to know
|
||||
|
||||
- The `.js`, `.jsx`, or `.tsx` file extensions can be used for `page`.
|
||||
- A `page` is always the **leaf** of the route subtree.
|
||||
- A `page` file is required to make a route segment **publicly accessible**.
|
||||
- Pages are [Server Components](https://react.dev/reference/rsc/server-components) by default, but can be set to a [Client Component](https://react.dev/reference/rsc/use-client).
|
||||
|
||||
## Reference
|
||||
|
||||
### Props
|
||||
|
||||
@@ -14,7 +14,7 @@ Partial Prerendering (PPR) enables you to combine static and dynamic components
|
||||
|
||||
### Incremental Adoption (Version 15)
|
||||
|
||||
In Next.js 15, you can incrementally adopt Partial Prerendering in [layouts](/docs/app/building-your-application/routing/layouts-and-templates) and [pages](/docs/app/building-your-application/routing/pages) by setting the [`ppr`](/docs/app/api-reference/config/next-config-js/ppr) option in `next.config.js` to `incremental`, and exporting the `experimental_ppr` [route config option](/docs/app/api-reference/file-conventions/route-segment-config) at the top of the file:
|
||||
In Next.js 15, you can incrementally adopt Partial Prerendering in [layouts](/docs/app/building-your-application/routing/layouts-and-templates) and [pages](/docs/app/api-reference/file-conventions/page) by setting the [`ppr`](/docs/app/api-reference/config/next-config-js/ppr) option in `next.config.js` to `incremental`, and exporting the `experimental_ppr` [route config option](/docs/app/api-reference/file-conventions/route-segment-config) at the top of the file:
|
||||
|
||||
```ts filename="next.config.ts" switcher
|
||||
import type { NextConfig } from 'next'
|
||||
|
||||
Reference in New Issue
Block a user