From c67febd180fef23bd3930d9a4f33f6eb8bfb99d8 Mon Sep 17 00:00:00 2001 From: Joseph Date: Tue, 26 Aug 2025 12:37:49 +0200 Subject: [PATCH 1/9] Docs/getting started improv (#82741) Part of: https://linear.app/vercel/issue/DOC-4809/layout-pages-and-linking-and-navigating-improvements Iterating a bunch of improvements to getting-started --- .../01-getting-started/01-installation.mdx | 40 ++++++++++++- .../02-project-structure.mdx | 57 ++++++++++++------- 2 files changed, 76 insertions(+), 21 deletions(-) diff --git a/docs/01-app/01-getting-started/01-installation.mdx b/docs/01-app/01-getting-started/01-installation.mdx index 64592fd133a14..2dc40c68dbc8a 100644 --- a/docs/01-app/01-getting-started/01-installation.mdx +++ b/docs/01-app/01-getting-started/01-installation.mdx @@ -5,6 +5,44 @@ description: Learn how to create a new Next.js application with the `create-next {/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} + + +Create a new Next.js app and run it locally. + +## Quick start + +1. Create a new Next.js app named `my-app` +2. `cd my-app` and start the dev server. +3. Visit `http://localhost:3000`. + +```bash package="pnpm" +pnpm create next-app@latest my-app --yes +cd my-app +pnpm dev +``` + +```bash package="npm" +npx create-next-app@latest my-app --yes +cd my-app +npm run dev +``` + +```bash package="yarn" +yarn create next-app@latest my-app --yes +cd my-app +yarn dev +``` + +```bash package="bun" +bun create next-app@latest my-app --yes +cd my-app +bun dev +``` + +- `--yes` skips prompts using saved preferences or defaults. The default setup enables TypeScript, Tailwind, App Router, and Turbopack, with import alias `@/*`. + + + ## System requirements Before you begin, make sure your system meets the following requirements: @@ -12,7 +50,7 @@ Before you begin, make sure your system meets the following requirements: - [Node.js 18.18](https://nodejs.org/) or later. - macOS, Windows (including WSL), or Linux. -## Automatic installation +## Create with the CLI The quickest way to create a new Next.js app is using [`create-next-app`](/docs/app/api-reference/cli/create-next-app), which sets up everything automatically for you. To create a project, run: 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 dbf7cc07d47f5..8e117955a7295 100644 --- a/docs/01-app/01-getting-started/02-project-structure.mdx +++ b/docs/01-app/01-getting-started/02-project-structure.mdx @@ -52,6 +52,8 @@ Top-level files are used to configure your application, manage dependencies, run ### Routing Files +Add `page` to expose a route, `layout` for shared UI such as header, nav, or footer, `loading` for skeletons, `error` for error boundaries and `route` for APIs. + | | | | | ----------------------------------------------------------------------------- | ------------------- | ---------------------------- | | [`layout`](/docs/app/api-reference/file-conventions/layout) | `.js` `.jsx` `.tsx` | Layout | @@ -66,35 +68,50 @@ Top-level files are used to configure your application, manage dependencies, run ### Nested routes -| | | -| --------------- | -------------------- | -| `folder` | Route segment | -| `folder/folder` | Nested route segment | +Folders define URL segments. Nesting folders nests segments. Layouts at any level wrap their child segments. A route becomes public when a `page` or `route` file exists. + +| Path | URL pattern | Notes | +| --------------------------- | --------------- | ----------------------------- | +| `app/layout.tsx` | — | Root layout wraps all routes | +| `app/blog/layout.tsx` | — | Wraps `/blog` and descendants | +| `app/page.tsx` | `/` | Public route | +| `app/blog/page.tsx` | `/blog` | Public route | +| `app/blog/authors/page.tsx` | `/blog/authors` | Public route | ### Dynamic routes -| | | -| ------------------------------------------------------------------------------------------------------ | -------------------------------- | -| [`[folder]`](/docs/app/api-reference/file-conventions/dynamic-routes#convention) | Dynamic route segment | -| [`[...folder]`](/docs/app/api-reference/file-conventions/dynamic-routes#catch-all-segments) | Catch-all route segment | -| [`[[...folder]]`](/docs/app/api-reference/file-conventions/dynamic-routes#optional-catch-all-segments) | Optional catch-all route segment | +Parameterize segments with square brackets. Use `[segment]` for a single param, `[...segment]` for catch‑all, and `[[...segment]]` for optional catch‑all. Access values via the [`params`](/docs/app/api-reference/file-conventions/page#params-optional) prop. + +| Path | URL pattern | +| ------------------------------- | -------------------------------------------------------------------- | +| `app/blog/[slug]/page.tsx` | `/blog/my-first-post` | +| `app/shop/[...slug]/page.tsx` | `/shop/clothing/shoes`, `/shop/clothing/shirts` | +| `app/docs/[[...slug]]/page.tsx` | `/docs`, `/docs/layouts-and-pages`, `/docs/api-reference/use-router` | ### Route Groups and private folders -| | | -| ------------------------------------------------------------------------------ | ------------------------------------------------ | -| [`(folder)`](/docs/app/api-reference/file-conventions/route-groups#convention) | Group routes without affecting routing | -| [`_folder`](#private-folders) | Opt folder and all child segments out of routing | +Organize code without changing URLs with route groups [`(group)`](/docs/app/api-reference/file-conventions/route-groups#convention), and colocate non-routable files with private folders [`_folder`](#private-folders). + +| Path | URL pattern | Notes | +| ------------------------------- | ----------- | ----------------------------------------- | +| `app/(marketing)/page.tsx` | `/` | Group omitted from URL | +| `app/(shop)/cart/page.tsx` | `/cart` | Share layouts within `(shop)` | +| `app/blog/_components/Post.tsx` | — | Not routable; safe place for UI utilities | +| `app/blog/_lib/data.ts` | — | Not routable; safe place for utils | ### Parallel and Intercepted Routes -| | | -| ------------------------------------------------------------------------------------------- | -------------------------- | -| [`@folder`](/docs/app/api-reference/file-conventions/parallel-routes#slots) | Named slot | -| [`(.)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept same level | -| [`(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept one level above | -| [`(..)(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept two levels above | -| [`(...)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept from root | +These features fit specific UI patterns, such as slot-based layouts or modal routing. + +Use `@slot` for named slots rendered by a parent layout. Use intercept patterns to render another route inside the current layout without changing the URL, for example, to show a details view as a modal over a list. + +| Pattern (docs) | Meaning | Typical use case | +| ------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------ | +| [`@folder`](/docs/app/api-reference/file-conventions/parallel-routes#slots) | Named slot | Sidebar + main content | +| [`(.)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept same level | Preview sibling route in a modal | +| [`(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept parent | Open parent child as overlay | +| [`(..)(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept two levels | Deeply nested overlay | +| [`(...)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept from root | Show arbitrary route in current view | ### Metadata file conventions From 8c41a6d7724dc5bbc3ad17b504280733b70c6ff8 Mon Sep 17 00:00:00 2001 From: Joseph Date: Tue, 23 Sep 2025 14:48:36 +0200 Subject: [PATCH 2/9] docs: onRequestError request header type (#83988) Aligning with the actual type https://github.com/vercel/next.js/blob/canary/packages/next/src/server/instrumentation/types.ts#L18 --- .../03-api-reference/03-file-conventions/instrumentation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/01-app/03-api-reference/03-file-conventions/instrumentation.mdx b/docs/01-app/03-api-reference/03-file-conventions/instrumentation.mdx index 88522f1767d0f..f98bf6aef2ca1 100644 --- a/docs/01-app/03-api-reference/03-file-conventions/instrumentation.mdx +++ b/docs/01-app/03-api-reference/03-file-conventions/instrumentation.mdx @@ -88,7 +88,7 @@ export function onRequestError( request: { path: string // resource path, e.g. /blog?name=foo method: string // request method. e.g. GET, POST, etc - headers: { [key: string]: string } + headers: { [key: string]: string | string[] } }, context: { routerKind: 'Pages Router' | 'App Router' // the router type From e36b2de7b609a774569f87c5087e02f394527563 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Martin?= Date: Mon, 22 Sep 2025 13:29:45 +0200 Subject: [PATCH 3/9] Fix TypeScript type error in example code (#84041) Without the `| null`, the following error appears during compilation: ``` TS2322: Type RefObject is not assignable to type RefObject Type HTMLDivElement | null is not assignable to type HTMLDivElement Type null is not assignable to type HTMLDivElement ``` Co-authored-by: Joseph --- docs/01-app/03-api-reference/03-file-conventions/error.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/01-app/03-api-reference/03-file-conventions/error.mdx b/docs/01-app/03-api-reference/03-file-conventions/error.mdx index fba5b9382caee..0a86e3ffe1eee 100644 --- a/docs/01-app/03-api-reference/03-file-conventions/error.mdx +++ b/docs/01-app/03-api-reference/03-file-conventions/error.mdx @@ -219,7 +219,7 @@ export class GracefullyDegradingErrorBoundary extends Component< ErrorBoundaryProps, ErrorBoundaryState > { - private contentRef: React.RefObject + private contentRef: React.RefObject constructor(props: ErrorBoundaryProps) { super(props) From 5b69afeea78d67e716dc586fa2a47d21e9e7084e Mon Sep 17 00:00:00 2001 From: liketiger <50165633+liketiger@users.noreply.github.com> Date: Tue, 23 Sep 2025 19:31:19 +0900 Subject: [PATCH 4/9] docs: improve dynamic routes example in project structure page (#84086) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Documentation Update This PR improves the dynamic routes example in the `project-structure.mdx` page. ### Changes - Updated catch-all segments example: - Before: `/shop/clothing/shoes` - After: `/shop/clothing` - Adjusted follow-up examples for consistency: - `/shop/a`, `/shop/a/b` → `/shop/clothing`, `/shop/clothing/shirts` ### Why - Provides a clearer and more intuitive demonstration of how catch-all segments work. - Keeps the example consistent with other dynamic routes documentation. Co-authored-by: Joseph --- docs/01-app/01-getting-started/02-project-structure.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 8e117955a7295..e4c18f191c016 100644 --- a/docs/01-app/01-getting-started/02-project-structure.mdx +++ b/docs/01-app/01-getting-started/02-project-structure.mdx @@ -85,7 +85,7 @@ Parameterize segments with square brackets. Use `[segment]` for a single param, | Path | URL pattern | | ------------------------------- | -------------------------------------------------------------------- | | `app/blog/[slug]/page.tsx` | `/blog/my-first-post` | -| `app/shop/[...slug]/page.tsx` | `/shop/clothing/shoes`, `/shop/clothing/shirts` | +| `app/shop/[...slug]/page.tsx` | `/shop/clothing`, `/shop/clothing/shirts` | | `app/docs/[[...slug]]/page.tsx` | `/docs`, `/docs/layouts-and-pages`, `/docs/api-reference/use-router` | ### Route Groups and private folders From 0c846de243dd0fb873e72effd20bcba615da914d Mon Sep 17 00:00:00 2001 From: Joseph Date: Mon, 22 Sep 2025 10:46:33 +0200 Subject: [PATCH 5/9] docs: We have dropped the CORS example linked (#84065) We have dropped the example linked in this page. I'll re-evaluate later if the section is still enough for a dev to understand how to set CORS related headers. --- docs/01-app/03-api-reference/03-file-conventions/route.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/01-app/03-api-reference/03-file-conventions/route.mdx b/docs/01-app/03-api-reference/03-file-conventions/route.mdx index 9ebac33682af6..82f010d64bce1 100644 --- a/docs/01-app/03-api-reference/03-file-conventions/route.mdx +++ b/docs/01-app/03-api-reference/03-file-conventions/route.mdx @@ -546,7 +546,6 @@ export async function GET(request) { > **Good to know**: > > - To add CORS headers to multiple Route Handlers, you can use [Middleware](/docs/app/api-reference/file-conventions/middleware#cors) or the [`next.config.js` file](/docs/app/api-reference/config/next-config-js/headers#cors). -> - Alternatively, see our [CORS example](https://github.com/vercel/examples/blob/main/edge-functions/cors/lib/cors.ts) package. ### Webhooks From 961a0f57bf12c999ba90f7de44310d026be3fc7a Mon Sep 17 00:00:00 2001 From: Milancen123 <122306536+Milancen123@users.noreply.github.com> Date: Mon, 22 Sep 2025 11:24:57 +0200 Subject: [PATCH 6/9] docs: add pageExtensions note to Middleware and clarify default filename (#84045) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added a Note to the Middleware docs explaining that when `pageExtensions` are customized (e.g. `.page.ts`), the Middleware file should be named `middleware.page.ts` or `middleware.page.js`. - Updated wording so `middleware.ts/js` is described as the default filename, not a strict requirement. --------- Co-authored-by: Joseph --- docs/01-app/03-api-reference/03-file-conventions/middleware.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/01-app/03-api-reference/03-file-conventions/middleware.mdx b/docs/01-app/03-api-reference/03-file-conventions/middleware.mdx index 8c0838e3b577a..85b49c768085e 100644 --- a/docs/01-app/03-api-reference/03-file-conventions/middleware.mdx +++ b/docs/01-app/03-api-reference/03-file-conventions/middleware.mdx @@ -20,6 +20,8 @@ Middleware executes before routes are rendered. It's particularly useful for imp Create a `middleware.ts` (or `.js`) file in the project root, or inside `src` if applicable, so that it is located at the same level as `pages` or `app`. +If you’ve customized [`pageExtensions`](/docs/app/api-reference/config/next-config-js/pageExtensions), for example to `.page.ts` or `.page.js`, name your file `middleware.page.ts` or `middleware.page.js` accordingly. + ```tsx filename="middleware.ts" switcher import { NextResponse, NextRequest } from 'next/server' From 895f0f5b6a2a11e2107568e0547623a5fd1fc0b1 Mon Sep 17 00:00:00 2001 From: Joseph Date: Thu, 25 Sep 2025 15:50:45 +0200 Subject: [PATCH 7/9] docs: nav_title for long unbroken words (#84233) Let's use a different title for these, otherwise we have a very long composite word. --- .../05-config/01-next-config-js/browserDebugInfoInTerminal.mdx | 3 ++- .../05-config/01-next-config-js/turbopackPersistentCaching.mdx | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/01-app/03-api-reference/05-config/01-next-config-js/browserDebugInfoInTerminal.mdx b/docs/01-app/03-api-reference/05-config/01-next-config-js/browserDebugInfoInTerminal.mdx index 4a0e853f601fb..bcdfbea45e8cf 100644 --- a/docs/01-app/03-api-reference/05-config/01-next-config-js/browserDebugInfoInTerminal.mdx +++ b/docs/01-app/03-api-reference/05-config/01-next-config-js/browserDebugInfoInTerminal.mdx @@ -1,5 +1,6 @@ --- -title: browserDebugInfoInTerminal +title: Debug Browser Info in Terminal +nav_title: browserDebugInfoInTerminal description: Forward browser console logs and errors to your terminal during development. version: experimental --- diff --git a/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackPersistentCaching.mdx b/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackPersistentCaching.mdx index c0bd7c437ef66..bcec852d9b3f5 100644 --- a/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackPersistentCaching.mdx +++ b/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackPersistentCaching.mdx @@ -1,5 +1,6 @@ --- -title: turbopackPersistentCaching +title: Turbopack Persistent Caching +nav_title: turbopackPersistentCaching description: Learn how to enable Persistent Caching for Turbopack builds version: canary --- From 3ca72cd1244e80689e18bc34b8184bd6c48cd724 Mon Sep 17 00:00:00 2001 From: Joseph Chamochumbi Date: Mon, 29 Sep 2025 18:09:27 +0200 Subject: [PATCH 8/9] Revert "docs: nav_title for long unbroken words (#84233)" This reverts commit 895f0f5b6a2a11e2107568e0547623a5fd1fc0b1. --- .../05-config/01-next-config-js/browserDebugInfoInTerminal.mdx | 3 +-- .../05-config/01-next-config-js/turbopackPersistentCaching.mdx | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/01-app/03-api-reference/05-config/01-next-config-js/browserDebugInfoInTerminal.mdx b/docs/01-app/03-api-reference/05-config/01-next-config-js/browserDebugInfoInTerminal.mdx index bcdfbea45e8cf..4a0e853f601fb 100644 --- a/docs/01-app/03-api-reference/05-config/01-next-config-js/browserDebugInfoInTerminal.mdx +++ b/docs/01-app/03-api-reference/05-config/01-next-config-js/browserDebugInfoInTerminal.mdx @@ -1,6 +1,5 @@ --- -title: Debug Browser Info in Terminal -nav_title: browserDebugInfoInTerminal +title: browserDebugInfoInTerminal description: Forward browser console logs and errors to your terminal during development. version: experimental --- diff --git a/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackPersistentCaching.mdx b/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackPersistentCaching.mdx index bcec852d9b3f5..c0bd7c437ef66 100644 --- a/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackPersistentCaching.mdx +++ b/docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackPersistentCaching.mdx @@ -1,6 +1,5 @@ --- -title: Turbopack Persistent Caching -nav_title: turbopackPersistentCaching +title: turbopackPersistentCaching description: Learn how to enable Persistent Caching for Turbopack builds version: canary --- From 0d47599a07ff45cad6449ae48c4640b940539851 Mon Sep 17 00:00:00 2001 From: geraldochristiano <68152918+geraldochristiano@users.noreply.github.com> Date: Thu, 4 Sep 2025 01:25:35 +0200 Subject: [PATCH 9/9] Fixed broken link in backend-for-frontend.mdx (#83310) Broken link to API Routes in Pages Router Co-authored-by: JJ Kasper --- docs/01-app/02-guides/backend-for-frontend.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/01-app/02-guides/backend-for-frontend.mdx b/docs/01-app/02-guides/backend-for-frontend.mdx index 8757dcf15c9f5..557a84e43aedd 100644 --- a/docs/01-app/02-guides/backend-for-frontend.mdx +++ b/docs/01-app/02-guides/backend-for-frontend.mdx @@ -28,7 +28,7 @@ To implement this pattern, use: - [Route Handlers](/docs/app/api-reference/file-conventions/route) - [`middleware`](/docs/app/api-reference/file-conventions/middleware) -- In Pages Router, [API Routes](/pages/building-your-application/routing/api-routes) +- In Pages Router, [API Routes](/docs/pages/building-your-application/routing/api-routes) ## Public Endpoints