docs: platform portability and infrastructure documentation

docs/01-app/01-getting-started/17-deploying.mdx

@@ -87,4 +87,4 @@ Refer to each provider's documentation for information on supported Next.js feat
 - [Netlify](https://docs.netlify.com/frameworks/next-js/overview/#next-js-support-on-netlify)
 - [Vercel](https://vercel.com/docs/frameworks/nextjs)
 
-> **Note:** We are working on a [Deployment Adapters API](https://github.com/vercel/next.js/discussions/77740) for all platforms to adopt. After completion, we will add documentation on how to write your own adapters.
+The [Deployment Adapter API](/docs/app/api-reference/config/next-config-js/adapterPath) lets platforms customize how Next.js applications are built and deployed. For details on which Next.js features require specific platform capabilities, see [Deploying to Platforms](/docs/app/guides/deploying-to-platforms).

docs/01-app/02-guides/cdn-caching.mdx

@@ -0,0 +1,114 @@
+---
+title: Using a CDN with Next.js
+nav_title: CDN Caching
+description: Learn how CDN caching works with Next.js, including what works today, cache variability, and the direction toward pathname-based cache keying.
+related:
+  description: Related guides and references.
+  links:
+    - app/guides/deploying-to-platforms
+    - app/guides/self-hosting
+    - app/guides/streaming
+    - app/api-reference/config/next-config-js/assetPrefix
+---
+
+Next.js sets standard `Cache-Control` headers that CDNs can use to cache responses at the edge. This page covers what works today, where CDN caching is challenging, and the direction toward eliminating custom-header dependencies.
+
+## What Works Today
+
+### Cache-Control headers
+
+Next.js sets `Cache-Control` headers based on the rendering strategy of each route:
+
+- **Static pages** (no revalidation): `s-maxage=31536000` (one year)
+- **ISR pages** (time-based revalidation): `s-maxage={revalidate}, stale-while-revalidate={expire - revalidate}`. The default `expire` is one year, so `stale-while-revalidate` is included in the response header by default. You can customize this with [`cacheLife`](/docs/app/api-reference/functions/cacheLife).
+- **Dynamic pages** (no caching): `private, no-cache, no-store, max-age=0, must-revalidate`
+
+CDNs that respect `s-maxage` and `stale-while-revalidate` can cache static and ISR pages at the edge. However, CDN-level caching alone does not support on-demand revalidation ([`revalidateTag()`](/docs/app/api-reference/functions/revalidateTag) / [`revalidatePath()`](/docs/app/api-reference/functions/revalidatePath)): those calls invalidate the Next.js server cache, but the CDN will continue serving its cached copy until the `s-maxage` TTL expires. To propagate on-demand revalidation to the CDN, trigger CDN purges alongside your revalidation call. A common pattern is: call `revalidateTag()`/`revalidatePath()` to invalidate the Next.js server cache, then call your CDN purge API for the affected keys (including both HTML and RSC variants).
+
+### Static assets
+
+Static assets (JavaScript, CSS, images, fonts) served from `/_next/static/` include content hashes in their filenames and have a 1 year `max-age` and `immutable` directive: `public,max-age=31536000,immutable`
+
+You can use [`assetPrefix`](/docs/app/api-reference/config/next-config-js/assetPrefix) to serve static assets from a different domain or CDN origin.
+
+### Static prefetches (PPR-enabled routes)
+
+When a route has Partial Prerendering enabled and the `next-router-prefetch` header is set (indicating a static prefetch), the response is deterministic: it returns the same prerendered content regardless of the client's router state. The `next-router-state-tree` header is not parsed for these requests, so it does not affect the response.
+
+For PPR-enabled routes, a CDN can cache static prefetch responses if it:
+
+1. Includes the `_rsc` search parameter in the cache key (to distinguish prefetch variants from HTML responses).
+2. Respects the `Cache-Control` headers Next.js sets on the response.
+
+> **Good to know:** For routes without PPR, the `next-router-state-tree` header is read during prefetch requests to determine which segments to include, which increases cache `vary` as it passes the current router state. When Cache Components is enabled, segment-level prefetches already use pathname-based routes (for example, `/page.segments/_tree.segment.rsc`), and CDNs can cache these with standard pathname-based cache keys.
+
+## Where CDN Caching Is Challenging
+
+App Router responses can vary based on several custom request headers. Next.js sets a `Vary` header on responses to signal this to CDNs:
+
+- `rsc` — whether the request should return a React Server Components (RSC) payload instead of HTML
+- `next-router-state-tree` — the client's current router state, used for targeted segment updates during dynamic navigations
+- `next-router-prefetch` — whether this is a prefetch request
+- `next-router-segment-prefetch` — the specific segment being prefetched
+- `next-url` — added only for routes that use [interception routes](/docs/app/api-reference/file-conventions/intercepting-routes), carries the URL being intercepted
+
+Many CDNs don't support `Vary` without additional configuration. Next.js addresses this with the `_rsc` search parameter: a hash of the relevant request header values that acts as a cache-key, ensuring different response variants get different cache keys. This ensures correct responses even on CDNs that ignore `Vary`.
+
+## Handling Headers at the CDN
+
+### What you can safely ignore
+
+These headers can be omitted in specific cases without causing protocol errors. The server still returns a parseable response, but it may be larger or less targeted to the specific navigation:
+
+**`next-router-state-tree`**: when omitted on non-prefetch RSC requests, the server returns a full payload instead of a targeted segment update.
+
+**`next-router-segment-prefetch`**: when omitted on prefetch requests, the server falls back to a broader prefetch payload instead of a segment-specific one.
+
+**`next-url`**: used for [interception routes](/docs/app/api-reference/file-conventions/intercepting-routes) to vary the response based on the referring page. If omitted, interception routes are not supported as the server doesn't know what original path to match against. The response returned is for regular navigation when `next-url` is omitted: the user sees the target page instead of the intercepted target page.
+
+### What you must preserve
+
+**The `rsc` header** must be forwarded from the client to the server. This header tells the server to return an RSC payload instead of HTML. If a CDN strips it, the server returns HTML when the client-side router expects RSC data, which breaks client-side navigation, causing browser navigations instead. The `Vary` header and `_rsc` parameter exist specifically to prevent CDNs from serving a cached HTML response to an RSC request (or vice versa).
+
+**When `next-router-prefetch` is present, preserve both the prefetch header and the `_rsc` search parameter.** For prefetch flows, `_rsc` is a required cache-busting discriminator and should be treated as mandatory.
+
+**The `_rsc` search parameter** must be included in the cache key. It distinguishes response variants (HTML vs. RSC, different prefetch types). Ensure your CDN does not strip query parameters from cache keys, as some CDNs do this by default. When the `experimental.validateRSCRequestHeaders` option is enabled and a RSC request arrives without the correct `_rsc` value, the server responds with a **307 redirect** to the URL with the correct hash. CDNs should follow this redirect. Platforms that compute the hash upstream can rewrite requests to include the correct `_rsc` before forwarding to avoid an extra round trip.
+
+> **Good to know:** Today, `next-url` is included in the `_rsc` hash even during static prefetches. This means you cannot safely ignore it under the current scheme without potentially getting cache misses. The pathname-based direction described below resolves this gap.
+
+## Direction: Pathname-Based Cache Keying
+
+The Next.js team is working on moving all cache-affecting inputs into the URL pathname, eliminating the need for `Vary` on custom headers and removing the `_rsc` search parameter. This resolves the CDN caching challenges described above.
+
+### How it works
+
+The approach extends the routing scheme that [`output: 'export'`](/docs/app/guides/static-exports) and segment prefetches already use today. File extensions in the pathname identify the response type:
+
+- **Full page RSC**: `/my/page.rsc` returns the RSC payload for the entire page
+- **Segment RSC**: `/my/page.segments/path/to/segment.segment.rsc` returns the RSC payload for a specific segment
+
+Under this model:
+
+- **The pathname determines the cache key.** Anything in the pathname affects which response variant is returned.
+- **Search parameters can be safely dropped** without affecting returned responses.
+- **Standard HTTP cache headers** (`Cache-Control`, `max-age`, etc.) are respected as usual.
+- **No `Vary` support needed** from the CDN.
+
+A CDN would cache Next.js responses by using the pathname as the cache key, ignoring search parameters, and respecting standard `Cache-Control` headers. No need to understand `Vary`, inspect custom headers, or program edge logic.
+
+### What changes for interception routes
+
+Under the current scheme, `next-url` contributes to the `_rsc` hash, so dropping it causes cache misses. Under the pathname-based scheme, interception variability would be encoded in a search parameter (not the pathname):
+
+- If a CDN preserves search params, interception works correctly.
+- If a CDN drops search params, interception is not supported. It would gracefully degrade to the non-intercepted page, client-side navigations won't break.
+
+This makes interception route support an opt-in CDN capability rather than a requirement.
+
+### Current status
+
+This direction extends patterns that are already operational in the codebase (segment prefetch paths, `output: 'export'` mode). It is in active design.
+
+## CDN Feature Compatibility
+
+For a full table showing the infrastructure primitives available on every major CDN (edge compute, key-value storage, blob storage, PPR resuming), see [Deploying to Platforms](/docs/app/guides/deploying-to-platforms#cdn-infrastructure-compatibility).

docs/01-app/02-guides/deploying-to-platforms.mdx

@@ -0,0 +1,78 @@
+---
+title: Deploying Next.js to different platforms
+nav_title: Deploying to Platforms
+description: Understand which Next.js features require specific platform capabilities and how to choose the right deployment target.
+related:
+  description: Related guides and references.
+  links:
+    - app/guides/rendering-philosophy
+    - app/guides/self-hosting
+    - app/getting-started/deploying
+    - app/api-reference/config/next-config-js/adapterPath
+---
+
+Next.js [treats static and dynamic content as a spectrum](/docs/app/guides/rendering-philosophy) at the component level. Different features in this model require different platform capabilities. This page helps you understand what your platform needs to support and how to configure your deployment.
+
+## Minimum Requirements
+
+To run Next.js, your platform needs **a Node.js server**. That's it.
+
+A single `next start` process handles every Next.js feature correctly: Server Components, ISR, PPR, Cache Components, Server Actions, Proxy, and `after()`. Streaming support is needed for features like PPR and Server Components to deliver content progressively (without it, responses are buffered and sent as a whole, which still works but loses the streaming performance benefit). Additional infrastructure (CDN caching, edge compute, shared cache) primarily improves performance and multi-instance consistency. In multi-instance deployments, shared cache and tag coordination reduce stale divergence between instances. The only additional dependency is the `sharp` package, which is required for [Image Optimization](/docs/app/api-reference/components/image).
+
+## Functional Fidelity vs. Performance Fidelity
+
+When evaluating platform support for Next.js, it helps to distinguish between two levels:
+
+**Functional fidelity** means every Next.js feature works correctly. The [adapter test suite](/docs/app/api-reference/config/next-config-js/adapterPath#testing-adapters) is the contract: if a platform's adapter passes the tests, it supports Next.js. This is binary: it passes or it doesn't.
+
+**Performance fidelity** means features achieve their optimal performance characteristics. Examples include PPR's static shell served at CDN latency rather than origin latency, or ISR serving stale content instantly with sub-second revalidation propagation. Performance fidelity is a spectrum that every platform will achieve differently based on their architecture.
+
+A platform that achieves functional fidelity is a fully supported deployment target for Next.js. Performance fidelity is how platforms differentiate, and it improves incrementally over time.
+
+Use the feature matrix below through this lens: "Streaming Required" and "Shared Cache Recommended" describe what is needed for functional fidelity. "Edge Stitching" is a performance fidelity optimization.
+
+## Feature Support Matrix
+
+Different features require different infrastructure capabilities. The "Edge Stitching" column is a **performance optimization**, not a correctness requirement. All features work correctly from a single origin server.
+
+| Feature                        | Streaming | Shared Cache | Edge Stitching | Notes                                                                                            |
+| ------------------------------ | --------- | ------------ | -------------- | ------------------------------------------------------------------------------------------------ |
+| Server Components              | Required  | No           | No             | Basic streaming support                                                                          |
+| ISR (time-based)               | No        | Recommended  | No             | Works per-instance without shared cache                                                          |
+| ISR (on-demand)                | No        | Recommended  | No             | [Tag propagation](/docs/app/guides/how-revalidation-works) needs shared cache for multi-instance |
+| Partial Prerendering           | Required  | Recommended  | Optional       | [See PPR Platform Guide](/docs/app/guides/ppr-platform-guide)                                    |
+| Cache Components (`use cache`) | Required  | Recommended  | No             | Shared cache enables cross-instance consistency                                                  |
+| Proxy / Middleware             | No        | No           | No             | Runs at edge or origin                                                                           |
+| Server Actions                 | Required  | No           | No             | POST requests with streaming response                                                            |
+| `after()`                      | No        | No           | No             | Requires [graceful shutdown](/docs/app/guides/self-hosting#after) support                        |
+
+**Streaming Required** means the platform must support chunked transfer encoding or HTTP/2 streaming and must not buffer the response before sending it to the client.
+
+**Shared Cache Recommended** means multiple server instances benefit from shared cache backends to coordinate. For ISR and server response caching, use [`cacheHandler`](/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath). For `'use cache'` entries, use [`cacheHandlers`](/docs/app/api-reference/config/next-config-js/cacheHandlers). Without shared cache, each instance maintains its own cache independently — features still work correctly on each instance, but revalidation events don't propagate across instances.
+
+## CDN Infrastructure Compatibility
+
+The following table maps infrastructure primitives for each major CDN. These are available building blocks, not finished integrations:
+
+| CDN               | Edge Compute | Key-Value / Tags | Blob Storage   | PPR Resuming |
+| ----------------- | ------------ | ---------------- | -------------- | ------------ |
+| Cloudflare        | Workers      | KV               | R2             | Yes (worker) |
+| Akamai            | EdgeWorkers  | EdgeKV           | Object Storage | Yes (worker) |
+| Amazon CloudFront | Lambda@Edge  | KeyValueStore    | S3             | Yes (Lambda) |
+| Fastly            | Compute      | KV Store         | Object Storage | Yes (WASM)   |
+| Azure             | Functions    | Managed Redis    | Blob Storage   | Yes (server) |
+| Google Cloud      | Cloud Run    | Various KV       | Cloud Storage  | Yes (server) |
+
+These are available building blocks, not finished integrations. Most community adapters today deploy Next.js as a Docker container or Node.js server without leveraging CDN-specific primitives like edge KV or PPR resuming. See the [Deploying](/docs/app/getting-started/deploying#adapters) page for the current list of adapters. For CDN-specific caching considerations (including known limitations with `Vary` on custom headers), see [CDN Caching](/docs/app/guides/cdn-caching).
+
+## Adapters
+
+Next.js provides a [Deployment Adapter API](/docs/app/api-reference/config/next-config-js/adapterPath) that lets platforms customize how Next.js applications are built and deployed for their infrastructure. Adapters run at build time and produce platform-specific output from the standard Next.js build.
+
+The adapter API plus Next.js caching interfaces form the complete platform integration surface. The adapter handles build-time output, while `cacheHandler` and `cacheHandlers` cover different runtime caching paths. `cacheHandler` (singular) covers server cache paths like ISR, route handlers, patched `fetch`/`unstable_cache`, and image optimization. `cacheHandlers` (plural) configures `'use cache'` directive backends.
+
+For a list of available platform adapters, see the [Deploying](/docs/app/getting-started/deploying#adapters) page.
+
+## A Note on Infrastructure Requirements
+
+Next.js's [rendering model](/docs/app/guides/rendering-philosophy) places the static/dynamic boundary at the component level rather than the route level. Finer-grained boundaries provide more flexibility for developers at the cost of broader requirements for hosting platforms. This is a deliberate trade-off: the infrastructure requirements on this page exist because of what the rendering model delivers.