cdk-nextjs 0.6.2 → 0.7.0

package/docs/breaking-changes.md

@@ -1,5 +1,665 @@
 # Breaking Changes
 
+## 0.7.0 (unreleased)
+
+### Requests are served through the adapter runtime, not `next start`
+
+cdk-nextjs no longer sets `output: "standalone"`, and no deployment runs the
+`server.js` that standalone generates. Instead, `next build` reports every route
+it built through the [Deployment Adapter API](https://nextjs.org/docs/app/api-reference/adapters/runtime-integration),
+cdk-nextjs stages those outputs and their traced dependencies into
+`.next/cdk-nextjs-adapter/`, and its own server invokes the built entrypoints
+in-process.
+
+Nothing in the construct API changes for the common case: the four root
+constructs take the same props, and `adapterPath` in `next.config` — already
+required before this — keeps working. It is now optional, since cdk-nextjs sets
+`NEXT_ADAPTER_PATH` on the build it runs itself; an explicit `adapterPath` still
+wins, because Next.js reads the variable only as that option's default. You still
+need it when cdk-nextjs is not running your build, i.e. `skipBuild: true`. What
+changes:
+
+- **Next.js 16.3 or higher is required** (was 16.2). The build reads adapter
+  outputs 16.3 added (`routing.middlewareMatchers`, `assetsHashes`), and the
+  runtime bundles `@next/routing` 16.3.5. `next build` on an older version now
+  fails at once with a message naming the version.
+- **If you set `output: "standalone"` yourself, remove it.** Standalone and the
+  adapter are alternatives, not layers — `next build` says so, and a future
+  Next.js release may reject the combination outright.
+- **If you have a custom Dockerfile**, it can no longer `COPY .next/standalone`
+  or `CMD ["node", "server.js"]`. Copy `.next/cdk-nextjs-adapter/app` to the
+  image root and run `node cdk-nextjs-runtime/server.mjs`. Compare against
+  `src/nextjs-build/global-containers.Dockerfile`. cdk-nextjs now **rewrites**
+  any Dockerfile whose first line is `# ~~ Generated by cdk-nextjs ~~`, so
+  upgrades no longer leave a stale one behind (the previous copy is kept as
+  `<name>.bak`); delete that line to take ownership of the file. The build arg was renamed too:
+  `RELATIVE_PATH_TO_PACKAGE` is now `RELATIVE_PROJECT_DIR` (`"."` for an app at
+  the repo root), and only `NextjsRegionalContainers` passes it; the Global
+  Containers image no longer needs it. A Dockerfile still reading the old name gets it empty, and in a
+  monorepo copies `.next/static` and `public` to the image root instead of the
+  app's directory.
+- **Monorepo detection changed mechanism.** It used to find `server.js` with a
+  `.next` sibling inside `.next/standalone/`. It now uses the `repoRoot` and
+  project directory the adapter reports. No prop to change — this only matters if
+  you were relying on the old layout.
+- **`.env` and `.env.production` are staged and loaded explicitly.**
+  `writeStandaloneDirectory` used to copy them and `next start` loaded them; the
+  adapter hook has neither, so cdk-nextjs copies them into the package and the
+  runtime loads them at startup with Next.js's own `loadEnvConfig`. Same result:
+  a variable set on the function or task still wins over the files. If you were
+  depending on some _other_ env file reaching the server because standalone
+  happened to copy it, it did not — only those two were ever copied.
+- **The edge runtime fails the build.** That includes a `middleware.ts` with no
+  `export const config = { runtime: "nodejs" }`, since Next.js defaults
+  `middleware.ts` to edge, and any route with `export const runtime = "edge"`.
+  Rename middleware to `proxy.ts` (Node.js by default) or set
+  `runtime: "nodejs"`, and remove `runtime = "edge"` from routes.
+- **Pages API routes are not ended for you.** A route that returns without
+  calling `res.end()`, `res.json()` or `res.send()` now stalls until the
+  function or ALB timeout, as it does under `next start`. In exchange, a route
+  that finishes later — `stream.pipe(res)`, an `externalResolver` proxy, a
+  callback-style `res.json` — is no longer cut off with an empty 200.
+- **Request headers Next.js treats as internal are stripped** from viewer
+  requests, as `next start` does: `next-resume`, `x-matched-path`,
+  `x-nextjs-data`, `x-middleware-*`, `x-now-route-matches` and the rest of Next's
+  list. Nothing a browser sends is affected; a client that set one of them to
+  steer rendering no longer can.
+- **`next build` must run from the Next.js project directory.** A `buildCommand`
+  such as `next build apps/web` run from the repo root now fails the build with a
+  message saying so. Use `cd apps/web && next build`, or a package-manager filter
+  that runs in the package directory (`pnpm --filter <app> build`).
+
+### Functions are zip Lambdas, not container-image Lambdas
+
+Both Functions types (`NextjsGlobalFunctions`, `NextjsRegionalFunctions`) now
+package the staged tree as a zip asset. Docker is no longer needed to deploy
+them — only the Containers types still build images.
+
+- **`overrides.nextjsFunctions.dockerImageFunctionProps` →
+  `overrides.nextjsFunctions.functionProps`.** The keys that were specific to
+  container images (`assetImageCodeProps`, and anything under
+  `DockerImageFunctionProps` with no `FunctionProps` equivalent) are gone; the
+  rest — `memorySize`, `timeout`, `environment`, `vpc`, `logGroup` — move across
+  unchanged.
+- **The function is replaced on upgrade.** Its logical ID is unchanged, but
+  its package type goes from Image to Zip, which CloudFormation can only do by
+  creating a new function and deleting the old one. With a custom
+  `functionProps.functionName`, the first deploy fails ("cannot update a stack
+  when a custom-named resource requires replacing") and rolls back. For that
+  deploy, set a new name (e.g. `my-app-server-v2`) or remove it. To get the
+  original name back afterwards, deploy again with it: that is a second
+  replacement, which works now the name is free. On `NextjsGlobalFunctions` the
+  Function URL is replaced with it, and the distribution follows. Its log group
+  is replaced too, named after the new function; the old one is retained
+  (`UpdateReplacePolicy: Retain`), so server logs from before the upgrade stay in
+  `/aws/lambda/<old function name>`.
+- `NextjsFunctions.function` is a `lambda.Function`, not a
+  `DockerImageFunction`.
+- `OptionalDockerImageFunctionProps` is no longer exported.
+- **250 MB unzipped limit.** Zip Lambdas are capped where container images were
+  not. cdk-nextjs fails at synth with the group's measured size if a function
+  exceeds it; the fix is the new `functionGroups` prop (below).
+- **`functionProps.architecture` is honored.** The Functions types still
+  default to the architecture of the machine running synth, as in 0.6.x, so any
+  native dependency `next build` traced from it runs as built. Setting
+  `overrides.nextjsFunctions.functionProps.architecture` now deploys that
+  architecture, with `sharp` staged for it. It is one architecture per
+  deployment: a function group's own `overrides.functionProps.architecture`
+  that differs is a synth error. An x86 CI runner can deploy arm64 functions. Only
+  `sharp` is staged for the target. Any other native dependency in your app is
+  still traced from the build machine, so build on the architecture you deploy
+  if you have one.
+- **The post-deploy Lambda is always arm64.** It has no native dependencies,
+  so it no longer follows the synth machine. The first deploy after upgrading
+  from an x86 machine updates it in place.
+
+### The dedicated image optimization Lambda is gone
+
+`_next/image` is served by the same function as every other route, through
+cdk-nextjs's own S3-aware optimizer, after middleware. The separate Lambda that
+briefly existed behind an env var is removed along with it:
+
+- `CDK_NEXTJS_EXPERIMENTAL_DEDICATED_IMAGE_FUNCTION` — **removed.** It was never
+  a supported prop; unset it in CI and anywhere else it was exported. It is now
+  ignored, not honored.
+- `NextjsImageFunction` construct, `NextjsImageFunctionProps`,
+  `NextjsImageFunctionOverrides`,
+  `NextjsGlobalFunctions.nextjsImageFunction`,
+  `NextjsRegionalFunctions.nextjsImageFunction` — removed.
+- `NextjsDistributionProps.imageFunctionUrl`, `NextjsApiProps.imageFunction`,
+  `imageIntegrationProps` — removed.
+- `overrides.nextjsImageFunctionProps` — removed.
+- `overrides.nextjsImageFunction` on `NextjsGlobalFunctions` and
+  `NextjsRegionalFunctions`, and the protected
+  `NextjsBaseConstruct.createNextjsImageFunction()` a subclass could override —
+  removed. Setting the key is now a compile error; delete it, and size image
+  requests through `overrides.nextjsFunctions` as below.
+- `NextjsDistributionOverrides.imageFunctionUrlOriginWithOACProps` — removed;
+  there is no image function origin any more.
+- `NextjsBuild.imageOptimizationAssetPath` — removed.
+
+Independent memory and timeout sizing for image requests is the cost. Raise
+`overrides.nextjsFunctions.functionProps.memorySize` if image latency regresses.
+
+### `healthCheckPath` moved to the two Containers constructs
+
+It was required on all four root constructs, but only `NextjsGlobalContainers`
+and `NextjsRegionalContainers` ever read it — for the ALB target group and the
+ECS container health check. The Functions types took it and ignored it: Lambda
+has no long-lived process to probe, so there was nothing for it to do there.
+
+- `NextjsGlobalFunctions` / `NextjsRegionalFunctions`: the prop no longer exists.
+  **Remove it** — leaving it in place is now a type error rather than a no-op.
+  The `/api/health` route in your app is only needed if something else calls it.
+- `NextjsGlobalContainers` / `NextjsRegionalContainers`: unchanged, still
+  required, and still prefixed with your app's `basePath` (0.6.2) before it
+  reaches the target group and the container probe. Those two are now its only
+  consumers — the Lambda Web Adapter readiness check it also fed in 0.6.x is gone
+  along with LWA itself.
+- `NextjsComputeBaseProps.healthCheckPath` moved to `NextjsContainersProps`.
+  Deployed resources are identical either way; this only changes which props
+  compile.
+
+### `NextjsRegionalFunctions` puts the API Gateway stage back itself
+
+API Gateway strips the stage (`/prod`) from the path it passes to Lambda, so an
+app built with `basePath: "/prod"` — the setup `examples/regional-functions`
+documents — used to 404 every request unless middleware prepended the stage
+again. The example shipped that middleware in `examples/app-playground/proxy.ts`,
+driven by `PREPEND_APIGW_STAGE` and `API_GATEWAY_STAGE` on the function.
+
+The Lambda shell now does it: when the app's `basePath` starts with the prefix
+API Gateway stripped, Next.js is handed the request's unstripped path
+(`requestContext.path`). The stage is read off each request, so nothing is
+configured and a renamed stage just works. An app without a `basePath`, or behind
+a custom domain mapped at the root, sees exactly what it saw before.
+
+- **If you copied the stage-prepending middleware, remove it** along with the two
+  environment variables. The copy in the example skipped paths already starting
+  with the stage, so it is inert rather than harmful — but a variant without that
+  guard now rewrites `/prod/foo` to `/prod/prod/foo` and 404s.
+- **Redirects keep the stage.** A trailing-slash or repeated-slash redirect used
+  to answer with a `Location` outside the stage (`/isr/1` rather than
+  `/prod/isr/1`), which API Gateway then refused with a 403. They now match
+  `next start`.
+- **`/prod/` redirects to `/prod`**, as it does under `next start` for any app
+  with `basePath: "/prod"`. The middleware used to answer it directly with 200.
+  One extra hop on the stage root, and a page-relative URL resolved from the app's
+  root now resolves against `/prod` rather than `/prod/`.
+- **The `basePath` prop is now derived when unset**: the app's `basePath` minus
+  the prefix API Gateway strips (the stage, or a custom domain's base path
+  mapping from `restApiProps.domainName`). `basePath: "/prod"` still mounts at
+  the root, so the common setup is unchanged. An app whose `basePath` API Gateway
+  does not strip (`"/docs"` behind a root-mapped custom domain) now gets its
+  resources and its static assets' S3 keys under `docs`. Before, both stayed at
+  the root and every bundle 404'd. An explicit prop still wins. A domain
+  attached with `addDomainName()` is invisible at synth, so set the prop in that
+  case; `basePath: "/"` mounts at the root, for a domain whose base path mapping
+  strips the app's whole `basePath`. A `stageName` set through
+  `overrides.nextjsApi.restApiProps.deployOptions` is honored when deriving.
+
+### Lower-level constructs: new and renamed props
+
+The four root constructs fill these in; only code that uses `NextjsFunctions`,
+`NextjsContainers` or `NextjsBuild` directly has to change.
+
+- **`NextjsComputeBaseProps`** (the `NextjsFunctions` / `NextjsContainers`
+  props) now requires `staticAssetsBucket`, and takes an optional
+  `staticAssetsKeyPrefix`; take both from `NextjsStaticAssets` (`bucket`,
+  `keyPrefix`). `relativePathToPackage` is removed, and `healthCheckPath` moved
+  (above).
+- **`NextjsComputeBaseProps.buildDirectory` moved to `NextjsContainersProps`.**
+  `NextjsFunctions` never read it. Stop passing it when you construct
+  `NextjsFunctions` directly; `NextjsContainers` still requires it.
+- **`NextjsFunctionsProps`** now requires `deploymentRoots` and takes an optional
+  `architecture`; **`NextjsContainersProps`** now requires `relativeProjectDir`.
+  Take them from `NextjsBuild`'s fields of the same names.
+- **`NextjsBuild.relativePathToPackage` → `NextjsBuild.relativeProjectDir`**, now
+  read from the adapter manifest. New read-only fields: `architecture`,
+  `deploymentRoots`, `functionGroupBehaviors`, `nextConfigAssetPrefix`,
+  `nextConfigAssetPrefixPath`.
+- **`NextjsBuild.buildId` ends in `-<deploymentId>`** when the app sets
+  `deploymentId` (or `NEXT_DEPLOYMENT_ID`), so it no longer always equals
+  `.next/BUILD_ID`.
+- **`NextjsBuild.relativePathToEntrypoint` is `cdk-nextjs-runtime/server.mjs`**,
+  not `server.js` (or `<package>/server.js` in a monorepo). Update any task
+  definition or command you built from it.
+- **`NextjsBaseConstruct.createNextjsFunctions()`** (protected) takes no
+  parameter; it reads `overrides.nextjsFunctions` itself. A subclass that passed
+  overrides to it should set them there instead.
+
+### `nextjsFunctionsProps` is removed
+
+`overrides.nextjsGlobalFunctions.nextjsFunctionsProps` and
+`overrides.nextjsRegionalFunctions.nextjsFunctionsProps` are gone, along with
+the `NextjsFunctionsConstructOverrides` interface that declared them. Every
+`NextjsFunctionsProps` value is now either wired by the root construct from its
+siblings (the cache, the static assets, the build) or set elsewhere, and
+setting one there only desynced the stack: a different `staticAssetsKeyPrefix`,
+for example, made the functions read a prefix nothing uploaded to.
+
+- **Migration:** move `nextjsFunctionsProps.overrides` to
+  `overrides.nextjsFunctions`. Set `functionGroups` on the root construct's
+  props, and the architecture through
+  `overrides.nextjsFunctions.functionProps.architecture`. Drop any other key.
+
+### Fix: a VPC passed to the ECS cluster through `overrides` is kept
+
+On `NextjsGlobalContainers` and `NextjsRegionalContainers`, a VPC passed through
+`overrides.nextjsContainers.ecsClusterProps.vpc` was overwritten when the
+top-level `vpc` prop was unset, so the cluster created its own VPC. The override
+is now used. If you set it, the next deploy moves the tasks into that VPC and
+deletes the one the cluster created.
+
+### Fix: `NextjsGlobalFunctions` honors the `distribution` prop
+
+0.6.x silently ignored `distribution` on `NextjsGlobalFunctions` and always
+created its own (`NextjsGlobalContainers` already honored it). If you set it,
+the next deploy deletes the construct-created distribution, and with it its
+`dXXXX.cloudfront.net` domain, and adds the app's behaviors to yours instead.
+Without a `basePath` no catch-all behavior is added, so point your
+distribution's default behavior at the function, or set `basePath`.
+
+### Responses without `Cache-Control` are no longer cached by CloudFront
+
+The dynamic cache policy on `NextjsGlobalFunctions` and `NextjsGlobalContainers`
+now has a default TTL of 0 rather than CDK's default of one day. Before, any
+dynamic response that sent no `Cache-Control` - typically a route handler - was
+cached at the edge for 24 hours (per query string and cookie set). Next.js treats
+"no header" as "not cacheable", and so does every other host an app is likely to
+have been written against.
+
+What Next.js means to cache is unaffected: ISR, SSG and PPR shells send
+`s-maxage`, which the policy still honors up to its one-year `maxTtl`. If you
+relied on the old behavior, send `Cache-Control: s-maxage=<seconds>` from the
+route, or restore it with
+`overrides.nextjsDistribution.dynamicCachePolicyProps.defaultTtl`.
+
+An override of `dynamicCachePolicyProps.maxTtl` below a day was silently raised
+to a day before (CDK lifts `maxTtl` to `defaultTtl`), and is now honored as
+written. In particular `maxTtl: Duration.seconds(0)` now really turns the dynamic
+cache off, and the policy drops its cache key to match, because CloudFront
+rejects a policy that caches nothing but keys on headers, cookies or query
+strings. What reaches the origin does not change: the origin request policy
+forwards all of those regardless.
+
+### Behavior change: the dynamic cache key no longer includes `x-matched-path` or `x-next-cache-tags`
+
+The runtime strips `x-matched-path` from viewer requests, and viewers never send
+`x-next-cache-tags`, so both only took 2 of the policy's 10 cache-key header
+slots and let clients fragment the edge cache. The cache key changes, so expect
+one round of CloudFront cache misses on dynamic routes after upgrading. No
+action needed.
+
+### Behavior change: the deploy-time invalidation is scoped to `basePath`
+
+With a `basePath`, the CloudFront invalidation each deploy creates now covers
+only the app's URIs (`/base`, `/base?*`, `/base/*`) instead of `/*`, so
+deploying one app no longer empties the edge cache of other apps on a shared
+distribution. Without a `basePath` it is still `/*`.
+`overrides.nextjsPostDeploy.customResourceProperties.createInvalidationCommandInput`
+still replaces it.
+
+### Behavior change: `public/` follows `next start`
+
+The runtime now serves `public/` the way `next start` does. A `public/` file
+wins over an app route at the same path (`public/robots.txt` over
+`app/robots.ts`), and only GET and HEAD are answered; other methods get a 405.
+Rewrites onto a `public/` file (`rewrites()`, or a middleware rewrite to
+`/maintenance.html`) serve it on every type, as they did on 0.6.x:
+
+- **`NextjsRegionalContainers`** copies `public/` and `.next/static` into the
+  image, since nothing in front of it answers those paths, and lists `public/`
+  when the task starts, so files a `postbuild` step writes (`next-sitemap`'s
+  `sitemap.xml`, for one) are served.
+- **Every other type** doesn't carry `public/`. cdk-nextjs lists it at synth,
+  after the build command (so `postbuild` output is included), and the runtime
+  streams a rewritten file from the static assets bucket. A file's own URL is
+  still answered by S3 at the edge. A rewritten file keeps the `Cache-Control`
+  its S3 object carries, and `Range` requests are honored.
+
+On `NextjsGlobalFunctions` and `NextjsGlobalContainers`, a top-level `public/`
+entry whose name has no ASCII letter, digit or other character CloudFront can
+match (`public/фото/`) no longer gets a cache behavior, since that behavior
+would have captured every app route of the same length. The synth warns, and
+the entry's files are served by the server from S3 rather than by the edge.
+Rename it, or move it under an ASCII-named directory, to serve them directly.
+The same goes for a top-level name an API Gateway resource can't express on
+`NextjsRegionalFunctions` (`public/hello e2e.txt`), which used to 404.
+
+### New (non-breaking): `functionGroups`
+
+Splits one Next.js app across several Lambda functions, one per declared group of
+routes, so an app too large for Lambda's 250 MB unzipped limit can still deploy.
+Opt-in: omit it and you get one function, exactly as before. See
+[README](../README.md#splitting-a-large-app-across-functions).
+
+Splitting is checked when `next build` runs: every URL a grouped file serves
+must reach that file's group at the edge, or the build fails naming the URL and
+the pattern to add. That rejects, among others, a pattern that claims only some
+of the URLs one file serves (`/en` for an `app/[locale]/page.tsx` that also
+serves `/de`), a static rewrite whose source and destination land in different
+groups, and a group pattern that duplicates or is shadowed by a `public/`
+behavior. An optional catch-all's parent (`/blog` for `/blog/[[...slug]]`) is
+routed with `/blog/**` automatically, and listing `/blog` as well is now an
+error. Intercepting routes (`(..)photo`) are packaged with the group that owns
+the URL they intercept. Rewrites made by middleware are not checked.
+
+Two things only work within a group, because they run a route in-process in the
+function that received the request. A Pages Router `res.revalidate()` can only
+revalidate pages in its own group (the error names the owning group). And the
+image optimizer (`/_next/image`) always runs in the `default` group, so an
+`<Image>` whose local `src` is served by a route in another group
+(`/api/avatar/42` under `/api/**`) can't be fetched and fails instead of being
+optimized. `public/` and `_next/static` sources are read from S3 and are
+unaffected. Put image-serving routes in `default`, or use a static or remote
+source.
+
+Edge path matching is case-sensitive and Next.js's isn't, so `/API/reports/1`
+misses a `/api/reports/**` group and reaches the default function. That
+function answers a 308 to the route's own spelling (`/api/reports/1`, the
+dynamic values' case kept) instead of a 500, or a 404 if the URL isn't a case
+variant of the route.
+
+On `NextjsRegionalFunctions`, removing a group (or a top-level `public/` entry)
+used to leave its route in the live API Gateway stage: CloudFormation snapshots
+the stage before it deletes removed resources, so the old route kept pointing at
+the deleted function and answered 500. A small function now redeploys the stage
+when the stack update completes, so the gap is a minute or so after the update
+rather than until the next deploy. Turn it off with
+`overrides.nextjsRegionalFunctions.nextjsApiProps.redeployAfterUpdate: false`
+(`nextjsApiProps` is now the all-optional `OptionalNextjsApiProps`, so it takes
+just that flag).
+The redeploy is triggered by the stack's EventBridge status event, so an
+account bootstrapped with
+[`docs/cdk-nextjs-cfn-exec-policy.json`](./cdk-nextjs-cfn-exec-policy.json)
+needs `events:*` added to its CloudFormation execution policy, or the deploy
+fails creating the rule. The redeploy moves the stage off the deployment
+CloudFormation made, so drift detection reports the stage's `DeploymentId` as
+modified; that is expected.
+
+`OptionalNextjsApiProps` omits `overrides` and `functionGroups`, so
+`nextjsApiProps.overrides` no longer compiles. `functionGroups` belongs on the
+root construct's props, where the build checks routes against it, and
+`overrides.nextjsApi` is where `NextjsRegionalFunctions` reads the `RestApi`'s
+props from to derive `basePath`; one set under `nextjsApiProps` used to replace
+it, so the two could disagree about the stage.
+
+- **Migration:** move `nextjsApiProps.overrides` to `overrides.nextjsApi`.
+
+With groups and Pages Router data routes, the `_next/data` behaviors name the
+literal Next.js build ID, so they change on every deploy unless a
+`deploymentId` pins it.
+
+### Behavior change: the cache-behavior limit is 75 and configurable
+
+`NextjsDistribution` used to reject a build needing more than 25 cache behaviors
+(`public/` entries and, now, group patterns). The limit is CloudFront's default
+quota of 75, set with the new `maxCacheBehaviors` prop if your account's quota
+was raised. The check counts only the behaviors cdk-nextjs adds: if you pass
+in a distribution, or add behaviors through
+`overrides.nextjsDistribution.distributionProps`, lower `maxCacheBehaviors` by
+the behaviors those already have.
+
+### Behavior change: CloudFront's own viewer-request function can't be replaced on Global Functions
+
+`NextjsGlobalFunctions` puts a CloudFront Function on viewer-request for the
+dynamic and `_next/image*` behaviors. It overwrites `X-Forwarded-Host` with the
+viewer's `Host`, which the runtime trusts behind the Function URL, and redirects
+repeated slashes. `functionAssociations` in `overrides.dynamicBehaviorOptions`
+or `overrides.imageBehaviorOptions` used to replace it outright, which let a
+viewer's own `X-Forwarded-Host` reach the app (host injection into redirects and
+absolute URLs, cached for other viewers). Now:
+
+- associations on other event types (viewer-response, say) are added next to it;
+- an association on viewer-request throws at synth, since CloudFront allows one
+  function per event type per behavior. Move that logic to viewer-response or
+  into middleware.
+
+The runtime trusts `X-Forwarded-Host` only on a request Lambda reports as
+IAM-authenticated, so a Function URL overridden to `authType: NONE` builds its
+URLs from `Host`.
+
+The Containers types are unaffected: their origin sees the viewer's `Host`.
+
+### Behavior change: Global Containers builds absolute URLs with the viewer's protocol
+
+Without a certificate, CloudFront reaches the ALB over plain HTTP, so the ALB's
+`X-Forwarded-Proto` was `http`, and every absolute URL the app built from the
+request - `request.url`, `req.nextUrl.origin`, redirects, the origin a server
+action is forwarded to - came out as `http://` behind viewers on HTTPS.
+`NextjsGlobalContainers` now forwards CloudFront's own headers to the ALB (the
+managed `AllViewerAndCloudFrontHeaders-2022-06` origin request policy, which
+replaces `AllViewer`), and the container reads the viewer's protocol from
+`CloudFront-Forwarded-Proto`. The first deploy after upgrading updates the
+distribution, a CloudFront change of roughly ten minutes. An
+`overrides.nextjsDistribution.dynamicBehaviorOptions.originRequestPolicy` of
+your own still wins; if it does not forward `CloudFront-Forwarded-Proto`, the
+container falls back to `X-Forwarded-Proto` as before.
+
+### Behavior change: narrower CloudFront grants
+
+- **`NextjsGlobalContainers`** passes the distribution ID to the task as
+  `CDK_NEXTJS_DISTRIBUTION_ID`, and its `cloudfront:CreateInvalidation` grant
+  names that distribution instead of `distribution/*`. The
+  `cdk-nextjs-distribution-id-*` SSM parameter and the task's
+  `ssm:GetParameter` grant are gone.
+- **`NextjsGlobalFunctions`**: its `cloudfront:CreateInvalidation` grant also
+  names the distribution instead of `distribution/*`. It keeps the SSM
+  parameter, since the distribution depends on the function and the function
+  can't name it back; both statements moved from each function role's default
+  policy into one `InvalidationPolicy` (`AWS::IAM::Policy`) attached to every
+  group's role. CloudFront's `lambda:InvokeFunction` permission
+  on each function now has the distribution as its `SourceArn`, and moved from
+  `NextjsFunctions` to `NextjsDistribution`. Wiring the two by hand, the
+  distribution now adds it.
+
+### Behavior change: a missing object on the static S3 origin is a 404, not a 403
+
+The bucket policy now grants CloudFront's Origin Access Control principal
+`s3:ListBucket` on the static-assets bucket as well as `s3:GetObject`, so S3
+answers a missing `_next/static` or `public/` object with a 404 instead of a 403. Nothing is listable through the distribution: CloudFront only ever asks for
+one key. If you configured `errorResponses` (or monitoring) for 403 from the
+static behaviors, change them to 404.
+
+### Behavior change: a missing `_next/static` file is a plain-text 404
+
+A request for a `/_next/static/` file that doesn't exist - typically a client
+holding chunk hashes from the previous deploy - and a request for a missing
+image, script, font or style (by `Sec-Fetch-Dest`) now get a plain-text
+`Not Found` with `Cache-Control: no-store`, as `next start` answers them, instead
+of rendering your `not-found` page.
+
+### New: `'use cache: remote'` is shared across instances
+
+The adapter now also sets Next.js's
+[`cacheHandlers`](https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandlers):
+`remote` stores `'use cache: remote'` entries in the cache bucket (under
+`<buildId>/_use-cache/`, with an in-memory tier in front), so every Lambda
+instance or Fargate task serves the same entry. Before, Next.js fell back to its
+per-process in-memory handler, and `'use cache: remote'` was no more shared than
+`'use cache'`.
+
+`default` keeps plain `'use cache'` in memory, as before, but its tags now go
+through the revalidation table: a `revalidateTag`, `updateTag` or
+`revalidatePath` expires `'use cache'` entries on every instance within
+`CDK_NEXTJS_TAG_REFRESH_MS` (1 second by default), instead of only on
+the instance that ran it.
+
+A `cacheHandlers.default` or `cacheHandlers.remote` your `next.config` sets is
+left alone. See [README](../README.md#use-cache-and-use-cache-remote) for the
+cost and the settings.
+
+If you register the adapter yourself and copy its files rather than installing
+the package (as the examples' `sync-cdk-nextjs` script does), copy
+`lib/adapter/use-cache-default-handler.mjs` and
+`lib/adapter/use-cache-remote-handler.mjs` too: the adapter resolves them through
+the package's `cdk-nextjs/cache-handlers/default` and `/remote` exports.
+
+### Behavior change: the revalidation table gains a TTL and a log
+
+Instances no longer re-read every tag marker they keep once a second, for
+`'use cache'`/`'use cache: remote'` or for ISR and the data cache. With up to
+1000 kept tags that was ten `BatchGetItem`s a second per instance, all on one
+DynamoDB partition, so a handful of busy instances could throttle it (and each
+cost about 500 RCU a second).
+
+Instead, each `revalidateTag`/`updateTag` also writes a row to a revalidation
+log (`pk = <buildId>#log`, `sk = <epoch-ms>#<tag>`), and each instance sends one
+`Query` per `CDK_NEXTJS_TAG_REFRESH_MS` for the rows it hasn't seen. ISR, the
+data cache and `'use cache'` share one copy of the markers per instance, so one
+query serves them all. `0` queries the log on every check. The marker rows stay the source of truth: an instance still reads a tag's
+marker the first time it needs it, and re-reads each one it keeps every 7.5
+to 10 minutes, at most 100 a second. After a gap the log may not cover, it forgets
+them and reads each again when it's next needed.
+
+- An instance now keeps up to 10,000 tags' markers, up from 1,000 for
+  `'use cache'`. Every path is a tag of its own (`_N_T_/<path>`), so an app with
+  1,000 tagged pages needs 2,000, and at 1,000 it kept evicting and re-reading
+  them.
+
+- The table `NextjsCache` creates now has TTL on the `ttl` attribute, which the
+  log rows set 15 minutes out. Enabling it is an in-place update.
+  `revalidationTableProps` in `overrides` still wins.
+- If you pass your own `revalidationTable`, enable TTL on `ttl` yourself, or
+  the log rows accumulate.
+- `revalidateTag` costs one more write per tag (the log row's `PutItem`),
+  which the existing table grant already allows.
+- For ISR and the data cache, a marker read that fails is retried on the next
+  refresh (up to `CDK_NEXTJS_TAG_REFRESH_MS` later) rather than on the very
+  next check. The entry is treated as valid in between, as before.
+
+### Sharing a `cacheBucket` or `revalidationTable` between deployments is not supported
+
+Earlier docs said several deployments (branches, stages, apps) could safely
+share one `cacheBucket` and one `revalidationTable` because entries are keyed
+by `buildId`. They can't, and couldn't in earlier versions either: every
+deploy's post-deploy step deletes every cache object under a `<buildId>/`
+prefix other than its own, and the revalidation entries of the build it last
+recorded in the table's `METADATA` row, which with a shared table is whichever
+deployment deployed last. So deploying one deployment wiped the others' caches.
+The docs now say what the code does: bring-your-own `cacheBucket` and
+`revalidationTable` are still supported, but each must be dedicated to one
+deployment.
+
+`staticAssetsBucket` can still be shared between deployments with different
+`basePath`s (different S3 key prefixes), since pruning is scoped to
+`<basePath>/_next/`. Two deployments under the same prefix, such as subdomain
+previews all served at the root, overwrite each other's `public/` files and
+prune each other's `_next/` assets once they are past the prune TTL (30 days by
+default), so give those their own buckets too.
+
+- **Migration:** if deployments share a cache bucket or revalidation table, give
+  each its own. Either remove the `cacheBucket`/`revalidationTable` props and let
+  cdk-nextjs create them in each stack (removed with the stack), or create a
+  dedicated bucket (and a table with `pk`/`sk` String keys and TTL on `ttl`) per
+  deployment and point that deployment's props at it. Nothing needs copying: the
+  cache is re-seeded from the build on the next deploy. Delete the old shared
+  bucket and table once nothing points at them.
+  [examples/bring-your-own](../examples/bring-your-own) now shares only the VPC,
+  ECS cluster, and ALB between branches.
+- **Upgrading bring-your-own:** deploy every branch stack first, then
+  `SharedInfra`. The new `SharedInfra` deletes the shared cache bucket, static
+  assets bucket, revalidation table and their SSM parameters, which a branch
+  stack still on the old version serves from and reads at deploy; deployed
+  first, each branch has moved onto its own buckets and table before they go.
+
+### Performance compared with 0.6.2
+
+Measured with the [load tests](../examples/load-tests) against
+[`examples/bench-app`](../examples/bench-app), both versions deployed side by
+side from one EC2 load generator per stack in us-east-1: 2048 MB Lambda
+functions, and 1 vCPU / 2 GB Fargate tasks autoscaling from 2 to 10. Latency is
+p50 / p99 in ms; "faster" is 0.6.2 over 0.7.0.
+
+| Construct                  | Compute p50 | Compute p99 | Cold start p50 | Compared at      |
+| -------------------------- | ----------- | ----------- | -------------- | ---------------- |
+| `NextjsGlobalFunctions`    | 1.7× faster | 1.5× faster | 1.3× faster    | 1000 req/s/route |
+| `NextjsGlobalContainers`   | 1.1× faster | 1.1× faster | –              | 10 req/s/route   |
+| `NextjsRegionalContainers` | 7.0× faster | 3.9× faster | –              | 10 req/s/route   |
+| `NextjsRegionalFunctions`  | 1.9× faster | 1.5× faster | 1.6× faster    | 1000 req/s/route |
+
+Compute is the geometric mean over the routes that reach compute on every
+construct (`ssr`, `stream`, `rsc`, `api`), at the highest rate both versions
+served with under 1% errors. `stream` counts by time to first byte, since its
+total includes a fixed 200 ms delay in the page.
+
+The Containers constructs are compared at 10 req/s per route because 50 was
+past capacity for 0.6.2 on `NextjsGlobalContainers` (5% errors) and for both
+versions on `NextjsRegionalContainers`. A step lasts 3 minutes, less than the
+time a new task takes to start serving, so each run measures the two tasks it
+started with. On `NextjsGlobalContainers`, 0.7.0 is also 1.1× faster at 50
+req/s per route.
+
+**`NextjsGlobalFunctions`**: RSC payloads and route handlers are the big
+change, since they no longer pass through the Lambda Web Adapter and the
+standalone server. At 10 req/s per route both versions' p50s are within 5% on
+every compute route. From 50 req/s up, 0.6.2 adds a flat ~40 ms to `rsc` and
+`api`, most of the difference. At 1000 req/s per route:
+
+| Route           | 0.6.2      | 0.7.0      | Faster      |
+| --------------- | ---------- | ---------- | ----------- |
+| `rsc`           | 69 / 94    | 25 / 52    | 2.8× / 1.8× |
+| `api`           | 67 / 89    | 23 / 47    | 2.9× / 1.9× |
+| `ssr`           | 31 / 109   | 29 / 73    | 1.1× / 1.5× |
+| Cold start TTFB | 1844 (p50) | 1390 (p50) | 1.3×        |
+
+Both sustain at least 6,560 req/s of `ssr`, the load generator's limit.
+
+**`NextjsGlobalContainers`**: latency is unchanged, but 0.6.2 served sporadic
+502s under load (5% of `ssr` at 50 req/s per route). Node's default keep-alive
+timeout (5 s) is shorter than the ALB's idle timeout (60 s), so the ALB reused
+connections the server had closed, and CloudFront cached each 502 for its
+10 s error caching TTL. 0.7.0's server outlives the ALB's timeout. `ssr`
+capacity rose from 129 to 194 req/s on two to ten tasks.
+
+**`NextjsRegionalContainers`**: with no CDN, every request is the container's,
+and each is several times cheaper. At 10 req/s per route:
+
+| Route    | 0.6.2     | 0.7.0    | Faster      |
+| -------- | --------- | -------- | ----------- |
+| `static` | 197 / 442 | 41 / 163 | 4.8× / 2.7× |
+| `ssr`    | 137 / 602 | 22 / 172 | 6.3× / 3.5× |
+| `rsc`    | 65 / 275  | 9.4 / 64 | 6.9× / 4.3× |
+| `api`    | 62 / 242  | 6.9 / 55 | 8.9× / 4.4× |
+
+`ssr` capacity is the same, 675 req/s; `isr` capacity rose from 3,200 to at
+least 6,075 req/s. At 50 req/s on every route at once
+(400 req/s including assets and image optimization), neither version's two
+tasks keep up long enough for autoscaling.
+
+**`NextjsRegionalFunctions`**: responses stream through API Gateway, where 0.6.2
+buffered them, and prerendered pages no longer go through the standalone
+server. Rendering itself changed little: `ssr`, `rsc` and `api` p50s are 1.1×
+faster at every rate. At 50 req/s per route:
+
+| Route           | 0.6.2      | 0.7.0      | Faster        |
+| --------------- | ---------- | ---------- | ------------- |
+| `stream` (TTFB) | 231 / 280  | 25 / 84    | 9.2× / 3.3×   |
+| `static`        | 128 / 231  | 57 / 140   | 2.3× / 1.6×   |
+| `isr`           | 128 / 229  | 56 / 124   | 2.3× / 1.8×   |
+| `image`         | 81 / 173   | 125 / 221  | 0.7× (slower) |
+| Cold start TTFB | 2182 (p50) | 1380 (p50) | 1.6×          |
+
+`ssr` and `isr` capacity are at least 6,560 req/s on both.
+
+The Regional constructs' cache hits now check their tags' revalidation markers
+in DynamoDB, in-memory hits included, which is what lets `revalidateTag` reach
+every instance. Each instance holds a marker it read for a second
+(`CDK_NEXTJS_TAG_REFRESH_MS`), since read on every request they capped a
+route's cache hits at about 1,900 req/s: every marker of a deployment shares one
+partition key. The `isr` latencies above predate that TTL; the capacities
+include it.
+
+One thing is slower: **image optimization on `NextjsRegionalFunctions`**, 1.5×,
+now that it runs in the server function instead of a dedicated one (see
+[The dedicated image optimization Lambda is gone](#the-dedicated-image-optimization-lambda-is-gone)).
+
+0.6.2 also needed two things of the app that 0.7.0 does not: middleware on
+`NextjsRegionalFunctions` to re-add the API Gateway stage to every path, and a
+`Cache-Control` header on every dynamic response, without which CloudFront
+cached it for a day.
+
 ## 0.6.0
 
 ### `basePath` is reconciled with your Next.js app's own `basePath`
@@ -55,9 +715,12 @@ at synth, and derived from the app where there's only one value that can work.
   based at `"/base"` — drop the prefix: the prop is now the path as your app
   routes it, and a prefixed value becomes `/base/base/api/health`, which 404s.
   Left as the default `"/api/health"`, nothing changes for you.
-- Static asset pruning is now scoped to the app's S3 key prefix, so apps or
-  branches sharing one bucket under different `basePath`s no longer delete each
-  other's assets once they age past `msTtl`. One-time cleanup: **if you are
+- Static asset pruning is now scoped to `_next/` under the app's S3 key prefix
+  (`<basePath>/_next/`, or `_next/` at the bucket root), so apps or branches
+  sharing one bucket under different `basePath`s — including one at the root —
+  no longer delete each other's assets once they age past `msTtl`. A file
+  removed from `public/` is no longer pruned; delete it by hand if the storage
+  matters. One-time cleanup: **if you are
   adding a `basePath` to an existing deployment**, objects already uploaded under
   the old prefix (the bucket root, usually) are outside the new listing and will
   never be pruned. Delete them yourself once after the first deploy.
@@ -104,7 +767,7 @@ if you want one:
 `NextjsRegionalFunctions.nextjsImageFunction` are `undefined` unless the
 dedicated image Lambda is enabled, which no supported prop does yet. A future
 release routes `_next/image` through the adapter runtime after middleware; see
-`docs/plans/adapter-runtime-release.md`.
+`docs/adapter-runtime.md`.
 
 ## 0.5.0