[backport] docs: september improvements and fixes

docs/01-app/01-getting-started/01-installation.mdx

@@ -63,7 +63,7 @@ Then, add the following scripts to your `package.json` file:
 ```json filename="package.json"
 {
   "scripts": {
-    "dev": "next dev",
+    "dev": "next dev --turbopack",
     "build": "next build",
     "start": "next start",
     "lint": "eslint"
@@ -73,11 +73,13 @@ Then, add the following scripts to your `package.json` file:
 
 These scripts refer to the different stages of developing an application:
 
-- `next dev`: Starts the development server.
+- `next dev --turbopack`: Starts the development server using Turbopack.
 - `next build`: Builds the application for production.
 - `next start`: Starts the production server.
 - `eslint`: Runs ESLint.
 
+Turbopack is stable for `dev`. For production builds, Turbopack is in beta. To try it, run `next build --turbopack`. See the [Turbopack docs](/docs/app/api-reference/turbopack) for status and caveats.
+
 <AppOnly>
 
 ### Create the `app` directory

docs/01-app/01-getting-started/08-updating-data.mdx

@@ -393,7 +393,11 @@ Calling `redirect` [throws](/docs/app/api-reference/functions/redirect#behavior)
 
 ### Cookies
 
-You can `get`, `set`, and `delete` cookies inside a Server Action using the [`cookies`](/docs/app/api-reference/functions/cookies) API:
+You can `get`, `set`, and `delete` cookies inside a Server Action using the [`cookies`](/docs/app/api-reference/functions/cookies) API.
+
+When you [set or delete](/docs/app/api-reference/functions/cookies#understanding-cookie-behavior-in-server-actions) a cookie in a Server Action, Next.js re-renders the current page and its layouts on the server so the **UI reflects the new cookie value**.
+
+> **Good to know**: The server update applies to the current React tree, re-rendering, mounting, or unmounting components, as needed. Client state is preserved for re-rendered components, and effects re-run if their dependencies changed.
 
 ```ts filename="app/actions.ts" switcher
 'use server'

docs/01-app/01-getting-started/14-metadata-and-og-images.mdx

@@ -51,7 +51,7 @@ export const metadata: Metadata = {
   description: '...',
 }
 
-export default function Page() {}
+export default function Layout() {}
 ```
 
 ```jsx filename="app/blog/layout.tsx" switcher
@@ -60,7 +60,7 @@ export const metadata = {
   description: '...',
 }
 
-export default function Page() {}
+export default function Layout() {}
 ```
 
 You can view a full list of available options, in the [`generateMetadata` documentation](/docs/app/api-reference/functions/generate-metadata#metadata-fields).

docs/01-app/01-getting-started/15-route-handlers-and-middleware.mdx

@@ -109,7 +109,7 @@ export default function Page() {
   return <h1>Hello, Next.js!</h1>
 }
 
-// ❌ Conflict
+// Conflict
 // `app/route.ts`
 export async function POST(request: Request) {}
 ```
@@ -119,7 +119,7 @@ export default function Page() {
   return <h1>Hello, Next.js!</h1>
 }
 
-// ❌ Conflict
+// Conflict
 // `app/route.js`
 export async function POST(request) {}
 ```
@@ -164,7 +164,7 @@ Using fetch with `options.cache`, `options.next.revalidate`, or `options.next.ta
 
 ### Convention
 
-Use the file `middleware.ts` (or `.js`) in the root of your project to define Middleware. For example, at the same level as `pages` or `app`, or inside `src` if applicable.
+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`.
 
 > **Note**: While only one `middleware.ts` file is supported per project, you can still organize your middleware logic into modules. Break out middleware functionalities into separate `.ts` or `.js` files and import them into your main `middleware.ts` file. This allows for cleaner management of route-specific middleware, aggregated in the `middleware.ts` for centralized control. By enforcing a single middleware file, it simplifies configuration, prevents potential conflicts, and optimizes performance by avoiding multiple middleware layers.
 

docs/01-app/02-guides/backend-for-frontend.mdx

@@ -647,6 +647,15 @@ export function middleware(request) {
 
 ## Security
 
+### Working with headers
+
+Be deliberate about where headers go, and avoid directly passing incoming request headers to the outgoing response.
+
+- **Upstream request headers**: In Middleware, `NextResponse.next({ request: { headers } })` modifies the headers your server receives and does not expose them to the client.
+- **Response headers**: `new Response(..., { headers })`, `NextResponse.json(..., { headers })`, `NextResponse.next({ headers })`, or `response.headers.set(...)` send headers back to the client. If sensitive values were appended to these headers, they will be visible to clients.
+
+Learn more in [NextResponse headers in Middleware](/docs/app/api-reference/functions/next-response#next).
+
 ### Rate limiting
 
 You can implement rate limiting in your Next.js backend. In addition to code-based checks, enable any rate limiting features provided by your host.

docs/01-app/02-guides/content-security-policy.mdx

@@ -548,7 +548,7 @@ export function middleware(request: NextRequest) {
   const cspHeader = `
     default-src 'self';
     script-src 'self' 'nonce-${nonce}' 'strict-dynamic' ${isDev ? "'unsafe-eval'" : ''};
-    style-src 'self' 'nonce-${nonce}' ${isDev ? "'unsafe-inline'" : ''};
+    style-src 'self' ${isDev ? "'unsafe-inline'" : `'nonce-${nonce}'`};
     img-src 'self' blob: data:;
     font-src 'self';
     object-src 'none';
@@ -570,7 +570,7 @@ export function middleware(request) {
   const cspHeader = `
     default-src 'self';
     script-src 'self' 'nonce-${nonce}' 'strict-dynamic' ${isDev ? "'unsafe-eval'" : ''};
-    style-src 'self' 'nonce-${nonce}' ${isDev ? "'unsafe-inline'" : ''};
+    style-src 'self' ${isDev ? "'unsafe-inline'" : `'nonce-${nonce}'`};
     img-src 'self' blob: data:;
     font-src 'self';
     object-src 'none';

docs/01-app/02-guides/data-security.mdx

@@ -251,6 +251,10 @@ yarn add server-only
 pnpm add server-only
 ```
 
+```bash package="bun"
+bun add server-only
+```
+
 ```ts filename="lib/data.ts"
 import 'server-only'
 

docs/01-app/02-guides/incremental-static-regeneration.mdx

@@ -97,7 +97,7 @@ Here's how this example works:
 3. After 60 seconds has passed, the next request will still return the cached (now stale) page
 4. The cache is invalidated and a new version of the page begins generating in the background
 5. Once generated successfully, the next request will return the updated page and cache it for subsequent requests
-6. If `/blog/26` is requested, and it exists, the page will be generated on-demand. This behavior can be changed by using a different [dynamicParams](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams) value. However, if the post does not exist, then 404 is returned.
+6. If `/blog/26` is requested, and it exists, the page will be generated on-demand. This behavior can be changed by using a different [dynamicParams](/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams) value. However, if the post does not exist, then 404 is returned.
 
 </AppOnly>
 
@@ -196,7 +196,7 @@ Here's how this example works:
 3. After 60 seconds has passed, the next request will still return the cached (now stale) page
 4. The cache is invalidated and a new version of the page begins generating in the background
 5. Once generated successfully, the next request will return the updated page and cache it for subsequent requests
-6. If `/blog/26` is requested, and it exists, the page will be generated on-demand. This behavior can be changed by using a different [fallback](https://nextjs.org/docs/pages/api-reference/functions/get-static-paths#fallback-false) value. However, if the post does not exist, then 404 is returned.
+6. If `/blog/26` is requested, and it exists, the page will be generated on-demand. This behavior can be changed by using a different [fallback](/docs/pages/api-reference/functions/get-static-paths#fallback-false) value. However, if the post does not exist, then 404 is returned.
 
 </PagesOnly>
 

docs/01-app/02-guides/internationalization.mdx

@@ -215,3 +215,4 @@ export default async function RootLayout({ children, params }) {
 - [`paraglide-next`](https://inlang.com/m/osslbuzt/paraglide-next-i18n)
 - [`lingui`](https://lingui.dev)
 - [`tolgee`](https://tolgee.io/apps-integrations/next)
+- [`next-intlayer`](https://intlayer.org/doc/environment/nextjs)

docs/01-app/02-guides/local-development.mdx

@@ -181,16 +181,16 @@ It provides detailed information about the time taken for each module to compile
 1. Navigate around your application or make edits to files to reproduce the problem.
 1. Stop the Next.js development server.
 1. A file called `trace-turbopack` will be available in the `.next` folder.
-1. You can interpret the file using `next internal trace [path-to-file]`:
+1. You can interpret the file using `npx next internal trace [path-to-file]`:
 
    ```bash
-   next internal trace .next/trace-turbopack
+   npx next internal trace .next/trace-turbopack
    ```
 
    On versions where `trace` is not available, the command was named `turbo-trace-server`:
 
    ```bash
-   next internal turbo-trace-server .next/trace-turbopack
+   npx next internal turbo-trace-server .next/trace-turbopack
    ```
 
 1. Once the trace server is running you can view the trace at https://trace.nextjs.org/.

docs/01-app/02-guides/package-bundling.mdx

@@ -70,7 +70,7 @@ const nextConfig = {
 module.exports = nextConfig
 ```
 
-Next.js also optimizes some libraries automatically, thus they do not need to be included in the optimizePackageImports list. See the [full list](https://nextjs.org/docs/app/api-reference/config/next-config-js/optimizePackageImports).
+Next.js also optimizes some libraries automatically, thus they do not need to be included in the optimizePackageImports list. See the [full list](/docs/app/api-reference/config/next-config-js/optimizePackageImports).
 
 <PagesOnly>
 

docs/01-app/02-guides/videos.mdx

@@ -96,7 +96,7 @@ To embed videos from external platforms, you can use Next.js to fetch the video
 
 **1. Create a Server Component for video embedding**
 
-The first step is to create a [Server Component](https://nextjs.org/docs/app/getting-started/server-and-client-components) that generates the appropriate iframe for embedding the video. This component will fetch the source URL for the video and render the iframe.
+The first step is to create a [Server Component](/docs/app/getting-started/server-and-client-components) that generates the appropriate iframe for embedding the video. This component will fetch the source URL for the video and render the iframe.
 
 ```jsx filename="app/ui/video-component.jsx"
 export default async function VideoComponent() {
@@ -108,7 +108,7 @@ export default async function VideoComponent() {
 
 **2. Stream the video component using React Suspense**
 
-After creating the Server Component to embed the video, the next step is to [stream](https://nextjs.org/docs/app/api-reference/file-conventions/loading) the component using [React Suspense](https://react.dev/reference/react/Suspense).
+After creating the Server Component to embed the video, the next step is to [stream](/docs/app/api-reference/file-conventions/loading) the component using [React Suspense](https://react.dev/reference/react/Suspense).
 
 ```jsx filename="app/page.jsx"
 import { Suspense } from 'react'

docs/01-app/03-api-reference/02-components/image.mdx

@@ -82,6 +82,9 @@ export default function Page() {
 }
 ```
 
+> **Good to know**: For security reasons, the Image Optimization API using the default [loader](#loader) will _not_ forward headers when fetching the `src` image.
+> If the `src` image requires authentication, consider using the [unoptimized](#unoptimized) property to disable Image Optimization.
+
 #### `alt`
 
 The `alt` property is used to describe the image for screen readers and search engines. It is also the fallback text if images have been disabled or an error occurs while loading the image.
@@ -527,7 +530,7 @@ module.exports = {
 }
 ```
 
-If using a version prior to 15.3.0, you can configure `remotePatterns` using the object:
+You can also configure `remotePatterns` using the object:
 
 ```js filename="next.config.js"
 module.exports = {
@@ -863,7 +866,7 @@ The `getImageProps` function can be used to get the props that would be passed t
 ```jsx
 import { getImageProps } from 'next/image'
 
-const props = getImageProps({
+const { props } = getImageProps({
   src: 'https://example.com/image.jpg',
   alt: 'A scenic mountain view',
   width: 1200,

docs/01-app/03-api-reference/02-components/link.mdx

@@ -58,6 +58,7 @@ The following props can be passed to the `<Link>` component:
 | Prop                                | Example                  | Type              | Required |
 | ----------------------------------- | ------------------------ | ----------------- | -------- |
 | [`href`](#href-required)            | `href="/dashboard"`      | String or Object  | Yes      |
+| [`as`](#as)                         | `as="/post/abc"`         | String or Object  | -        |
 | [`replace`](#replace)               | `replace={false}`        | Boolean           | -        |
 | [`scroll`](#scroll)                 | `scroll={false}`         | Boolean           | -        |
 | [`prefetch`](#prefetch)             | `prefetch={false}`       | Boolean           | -        |
@@ -452,6 +453,12 @@ export default function Home() {
 }
 ```
 
+### `as`
+
+Optional decorator for the path that will be shown in the browser URL bar. Before Next.js 9.5.3 this was used for dynamic routes, check our [previous docs](https://github.com/vercel/next.js/blob/v9.5.2/docs/api-reference/next/link.md#dynamic-routes) to see how it worked.
+
+When this path differs from the one provided in `href` the previous `href`/`as` behavior is used as shown in the [previous docs](https://github.com/vercel/next.js/blob/v9.5.2/docs/api-reference/next/link.md#dynamic-routes).
+
 </PagesOnly>
 
 ### `onNavigate`

docs/01-app/03-api-reference/03-file-conventions/01-metadata/manifest.mdx

@@ -69,4 +69,4 @@ export default function manifest() {
 
 ### Manifest Object
 
-The manifest object contains an extensive list of options that may be updated due to new web standards. For information on all the current options, refer to the `MetadataRoute.Manifest` type in your code editor if using [TypeScript](https://nextjs.org/docs/app/api-reference/config/typescript#ide-plugin) or see the [MDN](https://developer.mozilla.org/docs/Web/Manifest) docs.
+The manifest object contains an extensive list of options that may be updated due to new web standards. For information on all the current options, refer to the `MetadataRoute.Manifest` type in your code editor if using [TypeScript](/docs/app/api-reference/config/typescript#ide-plugin) or see the [MDN](https://developer.mozilla.org/docs/Web/Manifest) docs.

docs/01-app/03-api-reference/03-file-conventions/dynamic-routes.mdx

@@ -113,13 +113,33 @@ The difference between **catch-all** and **optional catch-all** segments is that
 
 When using TypeScript, you can add types for `params` depending on your configured route segment — use [`PageProps<'/route'>`](/docs/app/api-reference/file-conventions/page#page-props-helper), [`LayoutProps<'/route'>`](/docs/app/api-reference/file-conventions/layout#layout-props-helper), or [`RouteContext<'/route'>`](/docs/app/api-reference/file-conventions/route#route-context-helper) to type `params` in `page`, `layout`, and `route` respectively.
 
+Route `params` values are typed as `string`, `string[]`, or `undefined` (for optional catch-all segments), because their values aren't known until runtime. Users can enter any URL into the address bar, and these broad types help ensure that your application code handles all these possible cases.
+
 | Route                               | `params` Type Definition                 |
 | ----------------------------------- | ---------------------------------------- |
 | `app/blog/[slug]/page.js`           | `{ slug: string }`                       |
 | `app/shop/[...slug]/page.js`        | `{ slug: string[] }`                     |
 | `app/shop/[[...slug]]/page.js`      | `{ slug?: string[] }`                    |
 | `app/[categoryId]/[itemId]/page.js` | `{ categoryId: string, itemId: string }` |
 
+If you're working on a route where `params` can only have a fixed number of valid values, such as a `[locale]` param with a known set of language codes, you can use runtime validation to handle any invalid params a user may enter, and let the rest of your application work with the narrower type from your known set.
+
+```tsx filename="/app/[locale]/page.tsx"
+import { notFound } from 'next/navigation'
+import type { Locale } from '@i18n/types'
+import { isValidLocale } from '@i18n/utils'
+
+function assertValidLocale(value: string): asserts value is Locale {
+  if (!isValidLocale(value)) notFound()
+}
+
+export default async function Page(props: PageProps<'/[locale]'>) {
+  const { locale } = await props.params // locale is typed as string
+  assertValidLocale(locale)
+  // locale is now typed as Locale
+}
+```
+
 ## Behavior
 
 - Since the `params` prop is a promise. You must use `async`/`await` or React's use function to access the values.

docs/01-app/03-api-reference/03-file-conventions/layout.mdx

@@ -61,7 +61,7 @@ A promise that resolves to an object containing the [dynamic route parameters](/
 
 ```tsx filename="app/dashboard/[team]/layout.tsx" switcher
 export default async function Layout({
-  children
+  children,
   params,
 }: {
   children: React.ReactNode
@@ -234,7 +234,7 @@ export default function Layout({ children }) {
 
 Layouts do not re-render on navigation, so they do not access pathname which would otherwise become stale.
 
-To access the current pathname, you can read it inside a Client Component using the [`usePathname`](https://nextjs.org/docs/app/api-reference/functions/use-pathname) hook. Since Client Components re-render during navigation, they have access to the latest pathname.
+To access the current pathname, you can read it inside a Client Component using the [`usePathname`](/docs/app/api-reference/functions/use-pathname) hook. Since Client Components re-render during navigation, they have access to the latest pathname.
 
 ```tsx filename="app/ui/breadcrumbs.tsx" switcher
 'use client'
@@ -312,7 +312,7 @@ export default function Layout({ children }) {
 
 Layouts cannot pass data to their `children`. However, you can fetch the same data in a route more than once, and use React [`cache`](https://react.dev/reference/react/cache) to dedupe the requests without affecting performance.
 
-Alternatively, when using [`fetch`](https://nextjs.org/docs/app/api-reference/functions/fetch)in Next.js, requests are automatically deduped.
+Alternatively, when using [`fetch`](/docs/app/api-reference/functions/fetch)in Next.js, requests are automatically deduped.
 
 ```tsx filename="app/lib/data.ts" switcher
 export async function getUser(id: string) {