vercel · delbaoliveira · Apr 15, 2025 · Apr 15, 2025 · Apr 15, 2025 · Apr 15, 2025
diff --git a/.../11-upgrading/05-app-router-migration.mdx → ...guides/migrating/app-router-migration.mdx b/.../11-upgrading/05-app-router-migration.mdx → ...guides/migrating/app-router-migration.mdx
@@ -1,6 +1,6 @@
 ---
-title: App Router Incremental Adoption Guide
-nav_title: App Router Migration
+title: How to migrate from Pages to the App Router
+nav_title: App Router
 description: Learn how to upgrade your existing Next.js application from the Pages Router to the App Router.
 ---
 

diff --git a/...11-upgrading/06-from-create-react-app.mdx → ...uides/migrating/from-create-react-app.mdx b/...11-upgrading/06-from-create-react-app.mdx → ...uides/migrating/from-create-react-app.mdx
@@ -1,6 +1,6 @@
 ---
-title: Migrating from Create React App
-nav_title: Migrating from CRA
+title: How to migrate from Create React App to Next.js
+nav_title: Create React App
 description: Learn how to migrate your existing React application from Create React App to Next.js.
 ---
 

diff --git a/...application/11-upgrading/07-from-vite.mdx → .../01-app/02-guides/migrating/from-vite.mdx b/...application/11-upgrading/07-from-vite.mdx → .../01-app/02-guides/migrating/from-vite.mdx
@@ -1,5 +1,6 @@
 ---
-title: Migrating from Vite
+title: How to migrate from Vite to Next.js
+nav_title: Vite
 description: Learn how to migrate your existing React application from Vite to Next.js.
 ---
 

diff --git a/docs/01-app/02-guides/migrating/index.mdx b/docs/01-app/02-guides/migrating/index.mdx
@@ -0,0 +1,4 @@
+---
+title: Migrating
+description: Learn how to migrate from popular frameworks to Next.js
+---
diff --git a/docs/01-app/02-guides/single-page-applications.mdx b/docs/01-app/02-guides/single-page-applications.mdx
@@ -295,7 +295,7 @@ This can be useful for third-party libraries that rely on browser APIs like `win
 
 ### Shallow routing on the client
 
-If you are migrating from a strict SPA like [Create React App](/docs/app/building-your-application/upgrading/from-create-react-app) or [Vite](/docs/app/building-your-application/upgrading/from-vite), you might have existing code which shallow routes to update the URL state. This can be useful for manual transitions between views in your application _without_ using the default Next.js file-system routing.
+If you are migrating from a strict SPA like [Create React App](/docs/app/guides/migrating/from-create-react-app) or [Vite](/docs/app/guides/migrating/from-vite), you might have existing code which shallow routes to update the URL state. This can be useful for manual transitions between views in your application _without_ using the default Next.js file-system routing.
 
 Next.js allows you to use the native [`window.history.pushState`](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) and [`window.history.replaceState`](https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState) methods to update the browser's history stack without reloading the page.
 
@@ -418,7 +418,7 @@ After running `next build`, Next.js will create an `out` folder with the HTML/CS
 
 You can incrementally migrate to Next.js by following our guides:
 
-- [Migrating from Create React App](/docs/app/building-your-application/upgrading/from-create-react-app)
-- [Migrating from Vite](/docs/app/building-your-application/upgrading/from-vite)
+- [Migrating from Create React App](/docs/app/guides/migrating/from-create-react-app)
+- [Migrating from Vite](/docs/app/guides/migrating/from-vite)
 
-If you are already using a SPA with the Pages Router, you can learn how to [incrementally adopt the App Router](/docs/app/building-your-application/upgrading/app-router-migration).
+If you are already using a SPA with the Pages Router, you can learn how to [incrementally adopt the App Router](/docs/app/guides/migrating/app-router-migration).
diff --git a/docs/01-app/03-building-your-application/01-routing/03-layouts-and-templates.mdx b/docs/01-app/03-building-your-application/01-routing/03-layouts-and-templates.mdx
@@ -141,7 +141,7 @@ The two layouts would be nested as such:
 > - Layouts do not have access to the route segments below itself. To access all route segments, you can use [`useSelectedLayoutSegment`](/docs/app/api-reference/functions/use-selected-layout-segment) or [`useSelectedLayoutSegments`](/docs/app/api-reference/functions/use-selected-layout-segments) in a Client Component.
 > - You can use [Route Groups](/docs/app/building-your-application/routing/route-groups) to opt specific route segments in and out of shared layouts.
 > - You can use [Route Groups](/docs/app/building-your-application/routing/route-groups) to create multiple root layouts. See an [example here](/docs/app/getting-started/project-structure#creating-multiple-root-layouts).
-> - **Migrating from the `pages` directory:** The root layout replaces the [`_app.js`](/docs/pages/building-your-application/routing/custom-app) and [`_document.js`](/docs/pages/building-your-application/routing/custom-document) files. [View the migration guide](/docs/app/building-your-application/upgrading/app-router-migration#migrating-_documentjs-and-_appjs).
+> - **Migrating from the `pages` directory:** The root layout replaces the [`_app.js`](/docs/pages/building-your-application/routing/custom-app) and [`_document.js`](/docs/pages/building-your-application/routing/custom-document) files. [View the migration guide](/docs/app/guides/migrating/app-router-migration#migrating-_documentjs-and-_appjs).
 
 ## Templates
 

diff --git a/docs/01-app/03-building-your-application/01-routing/10-dynamic-routes.mdx b/docs/01-app/03-building-your-application/01-routing/10-dynamic-routes.mdx
@@ -79,7 +79,7 @@ export async function generateStaticParams() {
 
 The primary benefit of the `generateStaticParams` function is its smart retrieval of data. If content is fetched within the `generateStaticParams` function using a `fetch` request, the requests are [automatically memoized](/docs/app/building-your-application/caching#request-memoization). This means a `fetch` request with the same arguments across multiple `generateStaticParams`, Layouts, and Pages will only be made once, which decreases build times.
 
-Use the [migration guide](/docs/app/building-your-application/upgrading/app-router-migration#dynamic-paths-getstaticpaths) if you are migrating from the `pages` directory.
+Use the [migration guide](/docs/app/guides/migrating/app-router-migration#dynamic-paths-getstaticpaths) if you are migrating from the `pages` directory.
 
 See [`generateStaticParams` server function documentation](/docs/app/api-reference/functions/generate-static-params) for more information and advanced use cases.
 

diff --git a/docs/01-app/03-building-your-application/06-optimizing/14-local-development.mdx b/docs/01-app/03-building-your-application/06-optimizing/14-local-development.mdx
@@ -30,7 +30,7 @@ npm install next@latest
 npm run dev --turbopack
 ```
 
-[Learn more about Turbopack](/blog/turbopack-for-development-stable). See our [upgrade guides](/docs/app/building-your-application/upgrading) and codemods for more information.
+[Learn more about Turbopack](/blog/turbopack-for-development-stable). See our [upgrade guides](/docs/app/guides/upgrading) and codemods for more information.
 
 ### 3. Check your imports
 

diff --git a/...01-app/03-building-your-application/07-configuring/03-environment-variables.mdx b/...01-app/03-building-your-application/07-configuring/03-environment-variables.mdx
@@ -186,7 +186,7 @@ Next.js can support both build time and runtime environment variables.
 
 <PagesOnly>
 
-To read runtime environment variables, we recommend using `getServerSideProps` or [incrementally adopting the App Router](/docs/app/building-your-application/upgrading/app-router-migration).
+To read runtime environment variables, we recommend using `getServerSideProps` or [incrementally adopting the App Router](/docs/app/guides/migrating/app-router-migration).
 
 </PagesOnly>
 
@@ -227,7 +227,7 @@ This allows you to use a singular Docker image that can be promoted through mult
 **Good to know:**
 
 - You can run code on server startup using the [`register` function](/docs/app/building-your-application/optimizing/instrumentation).
-- We do not recommend using the [`runtimeConfig`](/docs/pages/api-reference/config/next-config-js/runtime-configuration) option, as this does not work with the standalone output mode. Instead, we recommend [incrementally adopting](/docs/app/building-your-application/upgrading/app-router-migration) the App Router if you need this feature.
+- We do not recommend using the [`runtimeConfig`](/docs/pages/api-reference/config/next-config-js/runtime-configuration) option, as this does not work with the standalone output mode. Instead, we recommend [incrementally adopting](/docs/app/guides/migrating/app-router-migration) the App Router if you need this feature.
 
 ## Environment Variables on Vercel
 

diff --git a/docs/01-app/03-building-your-application/10-deploying/index.mdx b/docs/01-app/03-building-your-application/10-deploying/index.mdx
@@ -114,7 +114,7 @@ Next.js can support both build time and runtime environment variables.
 
 <PagesOnly>
 
-To read runtime environment variables, we recommend using `getServerSideProps` or [incrementally adopting the App Router](/docs/app/building-your-application/upgrading/app-router-migration).
+To read runtime environment variables, we recommend using `getServerSideProps` or [incrementally adopting the App Router](/docs/app/guides/migrating/app-router-migration).
 
 </PagesOnly>
 
@@ -155,7 +155,7 @@ This allows you to use a singular Docker image that can be promoted through mult
 > **Good to know:**
 >
 > - You can run code on server startup using the [`register` function](/docs/app/building-your-application/optimizing/instrumentation).
-> - We do not recommend using the [runtimeConfig](/docs/pages/api-reference/config/next-config-js/runtime-configuration) option, as this does not work with the standalone output mode. Instead, we recommend [incrementally adopting](/docs/app/building-your-application/upgrading/app-router-migration) the App Router.
+> - We do not recommend using the [runtimeConfig](/docs/pages/api-reference/config/next-config-js/runtime-configuration) option, as this does not work with the standalone output mode. Instead, we recommend [incrementally adopting](/docs/app/guides/migrating/app-router-migration) the App Router.
 
 ### Caching and ISR
 

diff --git a/docs/01-app/03-building-your-application/11-upgrading/index.mdx b/docs/01-app/03-building-your-application/11-upgrading/index.mdx
diff --git a/docs/01-app/03-building-your-application/index.mdx b/docs/01-app/03-building-your-application/index.mdx
@@ -11,12 +11,12 @@ The sections and pages are organized sequentially, from basic to advanced, so yo
 
 <AppOnly>
 
-If you're new to Next.js, we recommend starting with the [Routing](/docs/app/building-your-application/routing), [Rendering](/docs/app/building-your-application/rendering), [Data Fetching](/docs/app/building-your-application/data-fetching) and [Styling](/docs/app/building-your-application/styling) sections, as they introduce the fundamental Next.js and web concepts to help you get started. Then, you can dive deeper into the other sections such as [Optimizing](/docs/app/building-your-application/optimizing) and [Configuring](/docs/app/building-your-application/configuring). Finally, once you're ready, checkout the [Deploying](/docs/app/building-your-application/deploying) and [Upgrading](/docs/app/building-your-application/upgrading) sections.
+If you're new to Next.js, we recommend starting with the [Routing](/docs/app/building-your-application/routing), [Rendering](/docs/app/building-your-application/rendering), [Data Fetching](/docs/app/building-your-application/data-fetching) and [Styling](/docs/app/building-your-application/styling) sections, as they introduce the fundamental Next.js and web concepts to help you get started. Then, you can dive deeper into the other sections such as [Optimizing](/docs/app/building-your-application/optimizing) and [Configuring](/docs/app/building-your-application/configuring). Finally, once you're ready, checkout the [Deploying](/docs/app/building-your-application/deploying) and [Upgrading](/docs/app/guides/upgrading) sections.
 
 </AppOnly>
 
 <PagesOnly>
 
-If you're new to Next.js, we recommend starting with the [Routing](/docs/pages/building-your-application/routing), [Rendering](/docs/pages/building-your-application/rendering), [Data Fetching](/docs/pages/building-your-application/data-fetching) and [Styling](/docs/pages/building-your-application/styling) sections, as they introduce the fundamental Next.js and web concepts to help you get started. Then, you can dive deeper into the other sections such as [Optimizing](/docs/pages/building-your-application/optimizing) and [Configuring](/docs/pages/building-your-application/configuring). Finally, once you're ready, checkout the [Deploying](/docs/pages/building-your-application/deploying) and [Upgrading](/docs/pages/building-your-application/upgrading) sections.
+If you're new to Next.js, we recommend starting with the [Routing](/docs/pages/building-your-application/routing), [Rendering](/docs/pages/building-your-application/rendering), [Data Fetching](/docs/pages/building-your-application/data-fetching) and [Styling](/docs/pages/building-your-application/styling) sections, as they introduce the fundamental Next.js and web concepts to help you get started. Then, you can dive deeper into the other sections such as [Optimizing](/docs/pages/building-your-application/optimizing) and [Configuring](/docs/pages/building-your-application/configuring). Finally, once you're ready, checkout the [Deploying](/docs/pages/building-your-application/deploying) and [Upgrading](/docs/pages/guides/upgrading) sections.
 
 </PagesOnly>
diff --git a/docs/01-app/05-api-reference/02-components/link.mdx b/docs/01-app/05-api-reference/02-components/link.mdx
@@ -336,7 +336,7 @@ Prefetching happens when a `<Link />` component enters the user's viewport (init
 The following values can be passed to the `prefetch` prop:
 
 - **`true` (default)**: The full route and its data will be prefetched.
-- `false`: Prefetching will not happen when entering the viewport, but will happen on hover. If you want to completely remove fetching on hover as well, consider using an `<a>` tag or [incrementally adopting](/docs/app/building-your-application/upgrading/app-router-migration) the App Router, which enables disabling prefetching on hover too.
+- `false`: Prefetching will not happen when entering the viewport, but will happen on hover. If you want to completely remove fetching on hover as well, consider using an `<a>` tag or [incrementally adopting](/docs/app/guides/migrating/app-router-migration) the App Router, which enables disabling prefetching on hover too.
 
 ```tsx filename="pages/index.tsx" switcher
 import Link from 'next/link'

diff --git a/docs/01-app/05-api-reference/03-file-conventions/route-segment-config.mdx b/docs/01-app/05-api-reference/03-file-conventions/route-segment-config.mdx
@@ -65,7 +65,7 @@ export const dynamic = 'auto'
 
 > **Good to know**:
 >
-> - Instructions on [how to migrate](/docs/app/building-your-application/upgrading/app-router-migration#step-6-migrating-data-fetching-methods) from `getServerSideProps` and `getStaticProps` to `dynamic: 'force-dynamic'` and `dynamic: 'error'` can be found in the [upgrade guide](/docs/app/building-your-application/upgrading/app-router-migration#step-6-migrating-data-fetching-methods).
+> - Instructions on [how to migrate](/docs/app/guides/migrating/app-router-migration#step-6-migrating-data-fetching-methods) from `getServerSideProps` and `getStaticProps` to `dynamic: 'force-dynamic'` and `dynamic: 'error'` can be found in the [upgrade guide](/docs/app/guides/migrating/app-router-migration#step-6-migrating-data-fetching-methods).
 
 ### `dynamicParams`
 

diff --git a/docs/01-app/05-api-reference/04-functions/use-router.mdx b/docs/01-app/05-api-reference/04-functions/use-router.mdx
@@ -61,7 +61,7 @@ export default function Page() {
 - The `query` object has been removed and is replaced by [`useSearchParams()`](/docs/app/api-reference/functions/use-search-params)
 - `router.events` has been replaced. [See below.](#router-events)
 
-[View the full migration guide](/docs/app/building-your-application/upgrading/app-router-migration).
+[View the full migration guide](/docs/app/guides/migrating/app-router-migration).
 
 ## Examples
 

diff --git a/docs/01-app/05-api-reference/05-config/01-next-config-js/appDir.mdx b/docs/01-app/05-api-reference/05-config/01-next-config-js/appDir.mdx
@@ -7,4 +7,4 @@ description: Enable the App Router to use layouts, streaming, and more.
 
 The App Router ([`app` directory](/docs/app/building-your-application/routing)) enables support for [layouts](/docs/app/building-your-application/routing/layouts-and-templates), [Server Components](/docs/app/building-your-application/rendering/server-components), [streaming](/docs/app/building-your-application/routing/loading-ui-and-streaming), and [colocated data fetching](/docs/app/building-your-application/data-fetching).
 
-Using the `app` directory will automatically enable [React Strict Mode](https://react.dev/reference/react/StrictMode). Learn how to [incrementally adopt `app`](/docs/app/building-your-application/upgrading/app-router-migration#migrating-from-pages-to-app).
+Using the `app` directory will automatically enable [React Strict Mode](https://react.dev/reference/react/StrictMode). Learn how to [incrementally adopt `app`](/docs/app/guides/migrating/app-router-migration#migrating-from-pages-to-app).
diff --git a/.../10-upgrading/02-app-router-migration.mdx → ...guides/migrating/app-router-migration.mdx b/.../10-upgrading/02-app-router-migration.mdx → ...guides/migrating/app-router-migration.mdx
@@ -1,7 +1,8 @@
 ---
-title: From Pages to App
+title: How to migrate from Pages to the App Router
+nav_title: App Router
 description: Learn how to upgrade your existing Next.js application from the Pages Router to the App Router.
-source: app/building-your-application/upgrading/app-router-migration
+source: app/guides/migrating/app-router-migration
 ---
 
 {/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
diff --git a/...10-upgrading/04-from-create-react-app.mdx → ...uides/migrating/from-create-react-app.mdx b/...10-upgrading/04-from-create-react-app.mdx → ...uides/migrating/from-create-react-app.mdx
@@ -1,7 +1,8 @@
 ---
-title: Migrating from Create React App
+title: How to migrate from Create React App to Next.js
+nav_title: Create React App
 description: Learn how to migrate your existing React application from Create React App to Next.js.
-source: app/building-your-application/upgrading/from-create-react-app
+source: app/guides/migrating/from-create-react-app
 ---
 
 {/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
diff --git a/...application/10-upgrading/03-from-vite.mdx → ...2-pages/02-guides/migrating/from-vite.mdx b/...application/10-upgrading/03-from-vite.mdx → ...2-pages/02-guides/migrating/from-vite.mdx
@@ -1,7 +1,8 @@
 ---
-title: Migrating from Vite
+title: How to migrate from Vite to Next.js
+nav_title: Vite
 description: Learn how to migrate your existing React application from Vite to Next.js.
-source: app/building-your-application/upgrading/from-vite
+source: app/guides/migrating/from-vite
 ---
 
 {/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
diff --git a/docs/02-pages/02-guides/migrating/index.mdx b/docs/02-pages/02-guides/migrating/index.mdx
@@ -0,0 +1,4 @@
+---
+title: Migrating
+description: Learn how to migrate from popular frameworks to Next.js
+---
diff --git a/docs/02-pages/02-guides/upgrading/version-13.mdx b/docs/02-pages/02-guides/upgrading/version-13.mdx
@@ -79,7 +79,7 @@ To upgrade your links to Next.js 13, you can use the [`new-link` codemod](/docs/
 
 ### `<Script>` Component
 
-The behavior of [`next/script`](/docs/pages/api-reference/components/script) has been updated to support both `pages` and `app`. If incrementally adopting `app`, read the [upgrade guide](/docs/pages/building-your-application/upgrading).
+The behavior of [`next/script`](/docs/pages/api-reference/components/script) has been updated to support both `pages` and `app`. If incrementally adopting `app`, read the [upgrade guide](/docs/pages/guides/upgrading).
 
 ### Font Optimization
 

diff --git a/docs/02-pages/03-building-your-application/01-routing/05-custom-app.mdx b/docs/02-pages/03-building-your-application/01-routing/05-custom-app.mdx
@@ -40,7 +40,7 @@ The `Component` prop is the active `page`, so whenever you navigate between rout
 
 Using [`getInitialProps`](/docs/pages/api-reference/functions/get-initial-props) in `App` will disable [Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization) for pages without [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props).
 
-**We do not recommend using this pattern.** Instead, consider [incrementally adopting](/docs/app/building-your-application/upgrading/app-router-migration) the App Router, which allows you to more easily fetch data for [pages and layouts](/docs/app/building-your-application/routing/layouts-and-templates).
+**We do not recommend using this pattern.** Instead, consider [incrementally adopting](/docs/app/guides/migrating/app-router-migration) the App Router, which allows you to more easily fetch data for [pages and layouts](/docs/app/building-your-application/routing/layouts-and-templates).
 
 ```tsx filename="pages/_app.tsx" switcher
 import App, { AppContext, AppInitialProps, AppProps } from 'next/app'

diff --git a/docs/02-pages/03-building-your-application/01-routing/06-custom-document.mdx b/docs/02-pages/03-building-your-application/01-routing/06-custom-document.mdx
@@ -54,7 +54,7 @@ export default function Document() {
 
 Customizing `renderPage` is advanced and only needed for libraries like CSS-in-JS to support server-side rendering. This is not needed for built-in `styled-jsx` support.
 
-**We do not recommend using this pattern.** Instead, consider [incrementally adopting](/docs/app/building-your-application/upgrading/app-router-migration) the App Router, which allows you to more easily fetch data for [pages and layouts](/docs/app/building-your-application/routing/layouts-and-templates).
+**We do not recommend using this pattern.** Instead, consider [incrementally adopting](/docs/app/guides/migrating/app-router-migration) the App Router, which allows you to more easily fetch data for [pages and layouts](/docs/app/building-your-application/routing/layouts-and-templates).
 
 ```tsx filename="pages/_document.tsx" switcher
 import Document, {
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,4 +7,4 @@ description: Enable the App Router to use layouts, streaming, and more.

		The App Router ([`app` directory](/docs/app/building-your-application/routing)) enables support for [layouts](/docs/app/building-your-application/routing/layouts-and-templates), [Server Components](/docs/app/building-your-application/rendering/server-components), [streaming](/docs/app/building-your-application/routing/loading-ui-and-streaming), and [colocated data fetching](/docs/app/building-your-application/data-fetching).

		Using the `app` directory will automatically enable [React Strict Mode](https://react.dev/reference/react/StrictMode). Learn how to [incrementally adopt `app`](/docs/app/building-your-application/upgrading/app-router-migration#migrating-from-pages-to-app).
		Using the `app` directory will automatically enable [React Strict Mode](https://react.dev/reference/react/StrictMode). Learn how to [incrementally adopt `app`](/docs/app/guides/migrating/app-router-migration#migrating-from-pages-to-app).