Backport/docs fixes 16.1.5 (#88916)

Back porting docs updates into 16-1 (canary now contains changes that
shouldn't show in 16.1)

---------

Co-authored-by: Eng Zer Jun <engzerjun@gmail.com>
Co-authored-by: Rich Haines <hello@richardhaines.dev>
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Co-authored-by: Luke Sandberg <lukesandberg@users.noreply.github.com>
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
Co-authored-by: Jiachi Liu <inbox@huozhi.im>
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>

Author: 9 people

docs/01-app/01-getting-started/04-linking-and-navigating.mdx

@@ -328,7 +328,7 @@ function HoverPrefetchLink({ href, children }) {
 
 React mitigates this with Selective Hydration and you can further improve this by:
 
-- Using the [`@next/bundle-analyzer`](/docs/app/guides/package-bundling#analyzing-javascript-bundles) plugin to identify and reduce bundle size by removing large dependencies.
+- Using the [`@next/bundle-analyzer`](/docs/app/guides/package-bundling#nextbundle-analyzer-for-webpack) plugin to identify and reduce bundle size by removing large dependencies.
 - Moving logic from the client to the server where possible. See the [Server and Client Components](/docs/app/getting-started/server-and-client-components) docs for guidance.
 
 ## Examples

docs/01-app/01-getting-started/05-server-and-client-components.mdx

@@ -32,7 +32,7 @@ Use **Server Components** when you need:
 
 For example, the `<Page>` component is a Server Component that fetches data about a post, and passes it as props to the `<LikeButton>` which handles client-side interactivity.
 
-```tsx filename="app/[id]/page.tsx" highlight={1,12} switcher
+```tsx filename="app/[id]/page.tsx" highlight={1,17} switcher
 import LikeButton from '@/app/ui/like-button'
 import { getPost } from '@/lib/data'
 
@@ -241,7 +241,7 @@ export default function Search() {
 
 You can pass data from Server Components to Client Components using props.
 
-```tsx filename="app/[id]/page.tsx" highlight={1,7} switcher
+```tsx filename="app/[id]/page.tsx" highlight={1,12} switcher
 import LikeButton from '@/app/ui/like-button'
 import { getPost } from '@/lib/data'
 

docs/01-app/01-getting-started/06-cache-components.mdx

@@ -86,7 +86,7 @@ export default async function Page() {
 }
 ```
 
-> **Good to know**: You can verify that a route was fully prerendered by checking the build output summary. Alternatively see what content was added to the static shell of any page by viewing the page source in your browser.
+> **Good to know**: You can verify that a route was fully prerendered by checking the build output summary. Alternatively, see what content was added to the static shell of any page by viewing the page source in your browser.
 
 ## Defer rendering to request time
 
@@ -102,12 +102,11 @@ External systems provide content asynchronously, which often takes an unpredicta
 
 In general, when you need the latest data from the source on each request (like real-time feeds or personalized content), defer rendering by providing fallback UI with a Suspense boundary.
 
-For example the `DynamicContent` component below uses multiple operations that are not automatically prerendered.
+For example, the `DynamicContent` component below uses multiple operations that are not automatically prerendered.
 
 ```tsx filename="page.tsx"
 import { Suspense } from 'react'
 import fs from 'node:fs/promises'
-import { setTimeout } from 'node:timers/promises'
 
 async function DynamicContent() {
   // Network request
@@ -120,7 +119,7 @@ async function DynamicContent() {
   const file = await fs.readFile('..', 'utf-8')
 
   // Simulating external system delay
-  await setTimeout(100) // from 'node:timers/promises'
+  await new Promise((resolve) => setTimeout(resolve, 100))
 
   return <div>Not in the static shell</div>
 }
@@ -174,7 +173,7 @@ async function RuntimeData({ searchParams }) {
 }
 ```
 
-To use the `RuntimeData` component in, wrap it in a `<Suspense>` boundary:
+To use the `RuntimeData` component, wrap it in a `<Suspense>` boundary:
 
 ```tsx filename="page.tsx"
 export default async function Page(props) {
@@ -504,6 +503,12 @@ During prerendering the header (static) and the blog posts fetched from the API
 
 When a user visits the page, they instantly see this prerendered shell with the header and blog posts. Only the personalized preferences need to stream in at request time since they depend on the user's cookies. This ensures fast initial page loads while still providing personalized content.
 
+## Metadata and Viewport
+
+`generateMetadata` and `generateViewport` are part of rendering your page or layout. During prerendering, their access to runtime data or uncached dynamic data is tracked separately from the rest of the page.
+
+If a page or layout is prerenderable but only metadata or viewport accesses uncached dynamic data or runtime data, Next.js requires an explicit choice: cache the data if possible, or signal that deferred rendering is intentional. See [Metadata with Cache Components](/docs/app/api-reference/functions/generate-metadata#with-cache-components) and [Viewport with Cache Components](/docs/app/api-reference/functions/generate-viewport#with-cache-components) for how to handle this.
+
 ## Enabling Cache Components
 
 You can enable Cache Components (which includes PPR) by adding the [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) option to your Next config file:
@@ -569,7 +574,7 @@ export default function Page() {
 
 ### `dynamic = "force-static"`
 
-Start by removing it. When unhandled dynamic or runtime data access is detected during development and built time, Next.js raises an error. Otherwise, the [prerendering](#automatically-prerendered-content) step automatically extracts the static HTML shell.
+Start by removing it. When unhandled dynamic or runtime data access is detected during development and build time, Next.js raises an error. Otherwise, the [prerendering](#automatically-prerendered-content) step automatically extracts the static HTML shell.
 
 For dynamic data access, add [`use cache`](#using-use-cache) as close to the data access as possible with a long [`cacheLife`](/docs/app/api-reference/functions/cacheLife) like `'max'` to maintain cached behavior. If needed, add it at the top of the page or layout.
 

docs/01-app/01-getting-started/13-fonts.mdx

@@ -12,6 +12,8 @@ The [`next/font`](/docs/app/api-reference/components/font) module automatically
 
 It includes **built-in self-hosting** for any font file. This means you can optimally load web fonts with no layout shift.
 
+<AppOnly>
+
 To start using `next/font`, import it from [`next/font/local`](#local-fonts) or [`next/font/google`](#google-fonts), call it as a function with the appropriate options, and set the `className` of the element you want to apply the font to. For example:
 
 ```tsx filename="app/layout.tsx" highlight={1,3-5,9} switcher
@@ -48,12 +50,99 @@ export default function Layout({ children }) {
 
 Fonts are scoped to the component they're used in. To apply a font to your entire application, add it to the [Root Layout](/docs/app/api-reference/file-conventions/layout#root-layout).
 
+</AppOnly>
+
+<PagesOnly>
+
+To start using `next/font`, import it from [`next/font/local`](#local-fonts) or [`next/font/google`](#google-fonts), call it as a function with the appropriate options, and set the `className` of the element you want to apply the font to. For example, you can apply fonts globally in your [Custom App](/docs/pages/building-your-application/routing/custom-app) (`pages/_app`):
+
+```tsx filename="pages/_app.tsx" highlight={1,4-6,10} switcher
+import { Geist } from 'next/font/google'
+import type { AppProps } from 'next/app'
+
+const geist = Geist({
+  subsets: ['latin'],
+})
+
+export default function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <main className={geist.className}>
+      <Component {...pageProps} />
+    </main>
+  )
+}
+```
+
+```jsx filename="pages/_app.js" highlight={1,3-5,9} switcher
+import { Geist } from 'next/font/google'
+
+const geist = Geist({
+  subsets: ['latin'],
+})
+
+export default function MyApp({ Component, pageProps }) {
+  return (
+    <main className={geist.className}>
+      <Component {...pageProps} />
+    </main>
+  )
+}
+```
+
+If you want to apply the font to the `<html>` element, you can use a [Custom Document](/docs/pages/building-your-application/routing/custom-document) (`pages/_document`):
+
+```tsx filename="pages/_document.tsx" highlight={2,4-6,10} switcher
+import { Html, Head, Main, NextScript } from 'next/document'
+import { Geist } from 'next/font/google'
+
+const geist = Geist({
+  subsets: ['latin'],
+})
+
+export default function Document() {
+  return (
+    <Html lang="en" className={geist.className}>
+      <Head />
+      <body>
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  )
+}
+```
+
+```jsx filename="pages/_document.js" highlight={2,4-6,10} switcher
+import { Html, Head, Main, NextScript } from 'next/document'
+import { Geist } from 'next/font/google'
+
+const geist = Geist({
+  subsets: ['latin'],
+})
+
+export default function Document() {
+  return (
+    <Html lang="en" className={geist.className}>
+      <Head />
+      <body>
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  )
+}
+```
+
+</PagesOnly>
+
 ## Google fonts
 
 You can automatically self-host any Google Font. Fonts are included stored as static assets and served from the same domain as your deployment, meaning no requests are sent to Google by the browser when the user visits your site.
 
 To start using a Google Font, import your chosen font from `next/font/google`:
 
+<AppOnly>
+
 ```tsx filename="app/layout.tsx" switcher
 import { Geist } from 'next/font/google'
 
@@ -90,8 +179,49 @@ export default function RootLayout({ children }) {
 }
 ```
 
+</AppOnly>
+
+<PagesOnly>
+
+```tsx filename="pages/_app.tsx" switcher
+import { Geist } from 'next/font/google'
+import type { AppProps } from 'next/app'
+
+const geist = Geist({
+  subsets: ['latin'],
+})
+
+export default function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <main className={geist.className}>
+      <Component {...pageProps} />
+    </main>
+  )
+}
+```
+
+```jsx filename="pages/_app.js" switcher
+import { Geist } from 'next/font/google'
+
+const geist = Geist({
+  subsets: ['latin'],
+})
+
+export default function MyApp({ Component, pageProps }) {
+  return (
+    <main className={geist.className}>
+      <Component {...pageProps} />
+    </main>
+  )
+}
+```
+
+</PagesOnly>
+
 We recommend using [variable fonts](https://fonts.google.com/variablefonts) for the best performance and flexibility. But if you can't use a variable font, you will need to specify a weight:
 
+<AppOnly>
+
 ```tsx filename="app/layout.tsx" highlight={4} switcher
 import { Roboto } from 'next/font/google'
 
@@ -130,8 +260,51 @@ export default function RootLayout({ children }) {
 }
 ```
 
+</AppOnly>
+
+<PagesOnly>
+
+```tsx filename="pages/_app.tsx" highlight={5} switcher
+import { Roboto } from 'next/font/google'
+import type { AppProps } from 'next/app'
+
+const roboto = Roboto({
+  weight: '400',
+  subsets: ['latin'],
+})
+
+export default function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <main className={roboto.className}>
+      <Component {...pageProps} />
+    </main>
+  )
+}
+```
+
+```jsx filename="pages/_app.js" highlight={4} switcher
+import { Roboto } from 'next/font/google'
+
+const roboto = Roboto({
+  weight: '400',
+  subsets: ['latin'],
+})
+
+export default function MyApp({ Component, pageProps }) {
+  return (
+    <main className={roboto.className}>
+      <Component {...pageProps} />
+    </main>
+  )
+}
+```
+
+</PagesOnly>
+
 ## Local fonts
 
+<AppOnly>
+
 To use a local font, import your font from `next/font/local` and specify the [`src`](/docs/app/api-reference/components/font#src) of your local font file. Fonts can be stored in the [`public`](/docs/app/api-reference/file-conventions/public-folder) folder or co-located inside the `app` folder. For example:
 
 ```tsx filename="app/layout.tsx" switcher
@@ -170,6 +343,47 @@ export default function RootLayout({ children }) {
 }
 ```
 
+</AppOnly>
+
+<PagesOnly>
+
+To use a local font, import your font from `next/font/local` and specify the [`src`](/docs/pages/api-reference/components/font#src) of your local font file. Fonts can be stored in the [`public`](/docs/pages/api-reference/file-conventions/public-folder) folder or inside the `pages` folder. For example:
+
+```tsx filename="pages/_app.tsx" switcher
+import localFont from 'next/font/local'
+import type { AppProps } from 'next/app'
+
+const myFont = localFont({
+  src: './my-font.woff2',
+})
+
+export default function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <main className={myFont.className}>
+      <Component {...pageProps} />
+    </main>
+  )
+}
+```
+
+```jsx filename="pages/_app.js" switcher
+import localFont from 'next/font/local'
+
+const myFont = localFont({
+  src: './my-font.woff2',
+})
+
+export default function MyApp({ Component, pageProps }) {
+  return (
+    <main className={myFont.className}>
+      <Component {...pageProps} />
+    </main>
+  )
+}
+```
+
+</PagesOnly>
+
 If you want to use multiple files for a single font family, `src` can be an array:
 
 ```js

docs/01-app/01-getting-started/16-proxy.mdx

@@ -52,7 +52,6 @@ export function proxy(request: NextRequest) {
 // Alternatively, you can use a default export:
 // export default function proxy(request: NextRequest) { ... }
 
-// See "Matching Paths" below to learn more
 export const config = {
   matcher: '/about/:path*',
 }
@@ -69,10 +68,11 @@ export function proxy(request) {
 // Alternatively, you can use a default export:
 // export default function proxy(request) { ... }
 
-// See "Matching Paths" below to learn more
 export const config = {
   matcher: '/about/:path*',
 }
 ```
 
+The `matcher` config allows you to filter Proxy to run on specific paths. See the [Matcher](/docs/app/api-reference/file-conventions/proxy#matcher) documentation for more details on path matching.
+
 Read more about [using `proxy`](/docs/app/guides/backend-for-frontend#proxy), or refer to the `proxy` [API reference](/docs/app/api-reference/file-conventions/proxy).

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

@@ -415,9 +415,11 @@ Consider nonces when:
 For applications that do not require nonces, you can set the CSP header directly in your [`next.config.js`](/docs/app/api-reference/config/next-config-js) file:
 
 ```js filename="next.config.js"
+const isDev = process.env.NODE_ENV === 'development'
+
 const cspHeader = `
     default-src 'self';
-    script-src 'self' 'unsafe-eval' 'unsafe-inline';
+    script-src 'self' 'unsafe-inline'${isDev ? " 'unsafe-eval'" : ''};
     style-src 'self' 'unsafe-inline';
     img-src 'self' blob: data:;
     font-src 'self';