[backport] docs: september improvements and fixes (#83997)

Collects a bunch of docs improvements and fixes.

---------

Co-authored-by: Lee Robinson <[email protected]>
Co-authored-by: Felix Shih <[email protected]>
Co-authored-by: Benjamin Woodruff <[email protected]>
Co-authored-by: David <[email protected]>
Co-authored-by: Aymeric PINEAU <[email protected]>
Co-authored-by: Luca Krebs <[email protected]>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: Rich Haines <[email protected]>
Co-authored-by: Mohammad Nedaeifard <[email protected]>
Co-authored-by: pontasan <[email protected]>
Co-authored-by: Steven <[email protected]>
Co-authored-by: Honda Yuto <[email protected]>
Co-authored-by: Jiachi Liu <[email protected]>
Co-authored-by: ryu <[email protected]>
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
Co-authored-by: Lorenzo Palmes <[email protected]>
Co-authored-by: JJ Kasper <[email protected]>

Author: 18 people

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/.