cdk-nextjs 0.7.12 → 0.7.13

package/.jsii

@@ -9032,7 +9032,7 @@
   },
   "name": "cdk-nextjs",
   "readme": {
-    "markdown": "![Version](https://img.shields.io/github/v/release/cdklabs/cdk-nextjs)\n[![npm version](https://img.shields.io/npm/v/cdk-nextjs.svg?style=flat-square)](https://www.npmjs.org/package/cdk-nextjs)\n![License](https://img.shields.io/github/license/cdklabs/cdk-nextjs)\n\n# CDK Next.js Construct Library\n\n<!--BEGIN STABILITY BANNER-->\n\n---\n\n![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)\n\n> The APIs of higher level constructs in this module are experimental and under active development.\n> They are subject to non-backward compatible changes or removal in any future version. These are\n> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be\n> announced in the release notes. This means that while you may use them, you may need to update\n> your source code when upgrading to a newer version of this package.\n\n---\n\n<!--END STABILITY BANNER-->\n\nDeploy [Next.js](https://nextjs.org/) apps on [AWS](https://aws.amazon.com/) with the [AWS CDK](https://aws.amazon.com/cdk/).\n\n## Features\n\n- Supports all features of Next.js App and Pages Router for [Node.js Runtime](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes#nodejs-runtime).\n- Choose your AWS architecture for Next.js with the supported constructs: `NextjsGlobalFunctions`, `NextjsGlobalContainers`, `NextjsRegionalContainers`, `NextjsRegionalFunctions`.\n- Global Content Delivery Network (CDN) built with [Amazon CloudFront](https://aws.amazon.com/cloudfront/) to deliver content with low latency and high transfer speeds.\n- Serverless functions powered by [AWS Lambda](https://aws.amazon.com/lambda/) or serverless containers powered by [AWS Fargate](https://aws.amazon.com/fargate/).\n- Static assets (JS, CSS, public folder) are stored and served from [Amazon Simple Storage Service (S3)](https://aws.amazon.com/s3/) for all constructs (except `NextjsRegionalContainers`) to decrease latency and reduce compute costs by serving directly from S3.\n- [Optimized images](https://nextjs.org/docs/pages/building-your-application/optimizing/images), [data cache](https://nextjs.org/docs/app/building-your-application/caching#data-cache), [full route cache](https://nextjs.org/docs/app/building-your-application/caching#full-route-cache) and [`'use cache: remote'`](https://nextjs.org/docs/app/api-reference/directives/use-cache-remote) are shared across compute with [Amazon Simple Storage Service (S3)](https://aws.amazon.com/s3/) with supporting metadata in [Amazon DynamoDB](https://aws.amazon.com/dynamodb), and `revalidateTag`/`revalidatePath` reach plain [`'use cache'`](https://nextjs.org/docs/app/api-reference/directives/use-cache) on every instance. See [`'use cache'` and `'use cache: remote'`](#use-cache-and-use-cache-remote).\n- Customize every construct via `overrides`.\n- AWS security and operational best practices are utilized, guided by [cdk-nag](https://github.com/cdklabs/cdk-nag).\n- First class support for [monorepos](https://monorepo.tools/).\n- [Bring Your Own Resources](#bring-your-own-resources) — import existing AWS resources (CloudFront distributions, ECS clusters, ALBs, S3 buckets, DynamoDB tables).\n- [AWS GovCloud (US)](https://aws.amazon.com/govcloud-us) compatible with `NextjsRegionalFunctions` and `NextjsRegionalContainers`.\n\n## Prerequisites\n\n- Next.js app running v16.3 or higher (`next build` fails on older versions). If you don't have one yet - follow [these steps](https://nextjs.org/docs/getting-started) to create one.\n- [AWS Cloud Development Kit](https://docs.aws.amazon.com/cdk/v2/guide/home.html) app either in the same package or separate package. cdk-nextjs supports monorepos.\n- A Docker compatible container engine, but **only** for `NextjsGlobalContainers` and `NextjsRegionalContainers` - we recommend [Rancher Desktop](https://rancherdesktop.io/) with dockerd (moby). The two Functions types deploy zip Lambdas and need no container engine.\n- [Node.js](https://nodejs.org/en) v24 (or LTS)\n\n## Getting Started\n\n1. Install `cdk-nextjs` in the package(s) containing your CDK and Next.js app with `npm i cdk-nextjs`\n2. Deploy your Next.js app to AWS: `cdk deploy`. Make sure you have [AWS credentials](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-configure.html) configured.\n3. Visit URL printed in terminal (CloudFormation Output) to view your Next.js app!\n\nNo `next.config` change is needed: cdk-nextjs runs `next build` itself, and sets [`NEXT_ADAPTER_PATH`](https://nextjs.org/docs/app/api-reference/config/next-config-js/adapterPath) on that build so Next.js loads cdk-nextjs's [Deployment Adapter](https://nextjs.org/docs/app/guides/deployment-adapters).\n\n### Registering the adapter yourself\n\nSet `adapterPath` in `next.config` in three cases. An explicit `adapterPath` always wins over `NEXT_ADAPTER_PATH`, so this is also how you pin a specific adapter.\n\n- **cdk-nextjs isn't running your build** — `skipBuild: true`, or you build in CI and hand the output to CDK.\n- **cdk-nextjs isn't a dependency of the Next.js app**, only of the CDK app. cdk-nextjs resolves the adapter from your app's directory, so it can't find it in that layout.\n- **cdk-nextjs is linked from outside your project root** — a `link:`/`file:` dependency on a checkout elsewhere on disk, as this repo's own examples use. The symlink resolves out of the project, and the adapter derives its cache handler path from its own location, so Next.js gets a `cacheHandler` outside `turbopack.root` and Turbopack rejects it. Setting `adapterPath` fixes this because the build resolves it, after whatever put the adapter in place.\n\n```ts\nimport { NextConfig } from \"next\";\n\nconst nextConfig: NextConfig = {\n  // ...\n  adapterPath: require.resolve(\"cdk-nextjs/adapter\"),\n};\n\nexport default nextConfig;\n```\n\n`require.resolve` works in an ESM `next.config.ts` too, because Next.js transpiles the config to CJS before evaluating it.\n\n### cdk-nextjs Created Dockerfile\n\nFor the Containers types, cdk-nextjs generates a Dockerfile in your Next.js app's directory. It cannot clean the file up after the image is built, so either commit it or gitignore it.\n\nEvery generated Dockerfile starts with the line `# ~~ Generated by cdk-nextjs ~~`, and cdk-nextjs **overwrites** any file carrying it — that way an upgrade that changes how the image is built does not leave a stale Dockerfile behind. To customize it, delete that first line; cdk-nextjs then leaves the file alone. If you edited a generated file without deleting the header, cdk-nextjs saves your version beside it as `<name>.Dockerfile.bak` before replacing it; gitignore that too.\n\n## Basic Example CDK App\n\n```ts\nimport { App, Stack, StackProps } from \"aws-cdk-lib\";\nimport { Construct } from \"constructs\";\nimport { NextjsGlobalFunctions } from \"cdk-nextjs\";\nimport { join } from \"node:path\";\n\nclass WebStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n    new NextjsGlobalFunctions(this, \"Nextjs\", {\n      buildDirectory: join(import.meta.dirname),\n    });\n  }\n}\n\nconst app = new App();\n\nnew WebStack(app, \"web-stack\");\n```\n\nSee [examples/](./examples/) for more usage examples.\n\n## Configuration\n\nThe variables below are read at runtime by the cache handler inside your deployed\nLambda functions or containers. Set them on the compute through `overrides`:\n\n```ts\n// NextjsGlobalFunctions / NextjsRegionalFunctions\noverrides: {\n  nextjsFunctions: {\n    functionProps: { environment: { CDK_NEXTJS_MEMORY_CACHE_TTL_MS: \"0\" } },\n  },\n},\n\n// NextjsGlobalContainers / NextjsRegionalContainers\noverrides: {\n  nextjsContainers: {\n    taskImageOptions: { environment: { CDK_NEXTJS_MEMORY_CACHE_TTL_MS: \"0\" } },\n  },\n},\n```\n\nValues you pass are merged over the ones the construct sets, so the same mechanism\noverrides the [infrastructure variables](#infrastructure-configuration) too.\n\n### Cache Configuration\n\n#### `CDK_NEXTJS_MEMORY_CACHE_TTL_MS`\n\nTime to live in milliseconds for in-memory cache entries. After this duration, entries expire and are removed from the cache.\n\n**Note**: Every memory hit is checked against the tag revalidation markers, so an entry revalidated on another instance is not served from memory. A tag's marker is read from DynamoDB only on its first use and a rolling re-read every few minutes; in between, revalidations arrive through the revalidation log (one `Query` per [`CDK_NEXTJS_TAG_REFRESH_MS`](#cdk_nextjs_tag_refresh_ms)). Memory still saves the S3 read and body parse. Set this to `0` to disable the memory cache entirely (all requests will fall through to S3 + DynamoDB).\n\n**Default**: `3600000` (1 hour)\n\n**Examples**:\n\n- Short TTL (5 minutes): `300000` - for frequently changing data\n- Medium TTL (1 hour): `3600000` - balanced between freshness and performance\n- Long TTL (24 hours): `86400000` - for mostly static content\n\n**Trade-offs**:\n\n- Lower values: More cache misses, fresher data, higher S3/DynamoDB costs\n- Higher values: Fewer cache misses, better performance, but longer stale data windows\n\n#### `CDK_NEXTJS_MEMORY_CACHE_MAX_ENTRIES`\n\nMaximum number of cache entries to store in memory. When this limit is reached, the least recently used (LRU) entry is evicted.\n\n**Default**: `1000`\n\n**Examples**:\n\n- Small cache: `100` - minimal memory footprint for simple apps\n- Medium cache: `1000` - good balance for typical applications\n- Large cache: `10000` - for high-traffic apps with many unique pages\n\n**Trade-offs**:\n\n- Lower values: Less memory usage, more cache evictions\n- Higher values: More memory usage, fewer cache evictions, better hit rates\n\n**Memory considerations**: Each entry stores the full cache value (HTML, JSON, etc.). A typical page cache might be 10-100KB, so 1000 entries ≈ 10-100MB of memory. Consider your compute environment's memory limits (Lambda: 128MB-10GB, Fargate: 512MB-30GB) and size accordingly.\n\n### `'use cache'` and `'use cache: remote'`\n\nThe adapter registers two [`cacheHandlers`](https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandlers)\nnext to the `cacheHandler` it already sets, unless your `next.config` names a\nhandler of its own for either:\n\n| Directive             | `cacheHandlers` name | Stored                           | Tags                    |\n| --------------------- | -------------------- | -------------------------------- | ----------------------- |\n| `'use cache'`         | `default`            | each instance's memory           | DynamoDB, all instances |\n| `'use cache: remote'` | `remote`             | S3 cache bucket, memory in front | DynamoDB, all instances |\n\n- **`'use cache: remote'`** is shared: an entry any instance generates is the one\n  every instance serves, until it expires or a tag is revalidated. Use it for\n  results you don't want each Lambda instance or task to compute on its own. It\n  costs an S3 `GetObject` the first time an instance reads an entry, and a\n  `PutObject` per generated entry. Objects live under\n  `<buildId>/_use-cache/` in the cache bucket and are pruned with the build.\n- **`'use cache'`** stays per instance, as Next.js intends — but `revalidateTag`,\n  `updateTag` and `revalidatePath` now expire it on every instance, not only the\n  one that ran them. Next.js's built-in handler keeps tags in process memory, so\n  before this every other instance kept serving the revalidated value, even into\n  pages re-rendered because of that revalidation.\n\nBoth read the same per-tag marker rows in the revalidation table that ISR and\nthe data cache use. A tag an instance has not seen yet — an entry read from S3,\na page's implicit `revalidatePath` tags — is read from its marker before it is\ntrusted, once per instance.\n\nAfter that, an instance doesn't re-read the tags it tracks to learn what\nchanged. Each `revalidateTag`/`updateTag` also writes a row to a revalidation\nlog in the same table (`pk = <buildId>#log`, expiring after 15 minutes through\nthe table's `ttl` attribute). At most once per\n[`CDK_NEXTJS_TAG_REFRESH_MS`](#cdk_nextjs_tag_refresh_ms),\neach instance sends one DynamoDB `Query` for the rows written since its last\none and applies those for tags it tracks. So a revalidation on another instance\nis honored within that window (1 second by default), and on the instance that ran\nit immediately. An idle instance's query costs 0.5 RCU a second, where\nre-reading up to 1000 tracked tags cost about 500. Each tag's marker is still\nre-read every 7.5 to 10 minutes, a few each second rather than all at once (about 8\nRCU a second at the most an instance tracks, 10,000 tags). After a gap the log\nmay no longer cover (a Lambda frozen between invocations, a run of failed\nqueries), an instance forgets its tracked markers and reads each again as it's\nneeded. ISR and the data cache share the same copy of the markers, so one\n`revalidateTag` writes each tag's rows once and one `Query` serves them all.\n\nIf you pass your own `revalidationTable`, enabling TTL on its `ttl` attribute is\nrecommended. Without it the log rows (about 100 bytes per revalidated tag) are\nkept until a deploy replaces their build, whose post-deploy step deletes them.\n\nTwo instances that generate the same `'use cache: remote'` entry at the same\nmoment both store it; each serves its own copy until that copy's `revalidate`\ntime, after which S3's is used.\n\n#### `CDK_NEXTJS_TAG_REFRESH_MS`\n\nHow often, at most, in milliseconds, an instance asks the revalidation log what\nother instances revalidated, for `'use cache'`, ISR and the data cache alike. A\n`revalidateTag` elsewhere goes unseen for up to about the window plus a second\n(2 s by default), since `'use cache'` doesn't wait for the answer - and for\nlonger while a query is slow or failing, or for a page render that started\ninside the window, which reads what the instance knew when it began. It's one DynamoDB `Query`,\nhowever many tags the instance tracks, shared by every request on the instance\nduring the window. `0` asks before every cache check, and waits for the answer\n(`'use cache'` only while the instance holds an entry the answer could expire).\nOtherwise `'use cache'` reads don't wait for it, and it applies from the\ninstance's next request. The exception is an instance that hasn't caught up for\nover a second past the window (it sat idle or was frozen): it waits for the\nanswer, before rendering the page for a page request. `'use cache: remote'`\nalways waits.\n\n**Default**: `1000`\n\n#### `CDK_NEXTJS_USE_CACHE_MEMORY_BYTES`\n\nSize bound, in bytes, of each handler's in-memory store: all of `'use cache'`,\nand the memory tier in front of S3 for `'use cache: remote'`. Least recently used\nentries are evicted first.\n\n**Default**: `52428800` (50 MB, Next.js's own default)\n\n### Infrastructure Configuration\n\nThe construct sets these itself and they typically don't need to be modified:\n\n#### `CDK_NEXTJS_BUILD_ID`\n\nUnique identifier for the Next.js build. Used for cache isolation between deployments.\n\n#### `CDK_NEXTJS_CACHE_BUCKET_NAME`\n\nS3 bucket name for storing cached data (optimized images, data cache, full route cache, `'use cache: remote'`).\n\n#### `CDK_NEXTJS_REVALIDATION_TABLE_NAME`\n\nDynamoDB table name for tracking cache revalidations and tag-to-cache-key mappings.\n\n#### `DEBUG`\n\nNot set by default. Set it to `cdk-nextjs:*` to enable debug logs. This is especially useful to see cache handler activity.\n\n### `next.config.js` options cdk-nextjs reads\n\nBoth are read out of your build, so you set them in one place — your app — and the\ninfrastructure follows.\n\n#### `basePath`\n\nBecomes the S3 key prefix for static assets and the prefix on every CloudFront\ncache behavior. See [Resource Isolation](#resource-isolation); the `basePath`\nprop only exists to be explicit about it.\n\n#### `assetPrefix`\n\n- **A path** (`assetPrefix: \"/cdn\"`) — Next.js emits bundle URLs as\n  `/cdn/_next/static/...`, on top of `basePath` rather than under it, while the\n  objects stay in S3 under `<basePath>/_next/static/...`. `NextjsGlobalFunctions`\n  and `NextjsGlobalContainers` add a cache behavior for\n  `<assetPrefix>/_next/static*` pointing at the assets bucket, with a CloudFront\n  Function that rewrites the prefix back to the S3 keys. It costs one of the 25\n  cache behaviors cdk-nextjs budgets for you. **Not supported on\n  `NextjsRegionalFunctions` or `NextjsRegionalContainers`** — nothing there maps\n  the prefix back, so bundles would 404; synth warns if your app sets one.\n- **An absolute URL** (`assetPrefix: \"https://cdn.example.com\"`) — names an origin\n  cdk-nextjs doesn't serve, so nothing is added, on any construct. Point that host\n  at the assets bucket yourself, including the `basePath` prefix the objects are\n  stored under.\n- **An absolute URL with a path** (`assetPrefix: \"https://cdn.example.com/cdn\"`) —\n  its path is treated exactly like the path case above, because `next build`\n  compiles a `/cdn/_next/:path+` rewrite of its own: `next start` serves bundles\n  under that path too, so the Global constructs answer there as well. Useful when\n  that host is a second domain on the same distribution.\n\n## Splitting a Large App Across Functions\n\nOnly for `NextjsGlobalFunctions` and `NextjsRegionalFunctions`, and only if you\nneed it. AWS Lambda caps a function's unzipped code at 250 MB. If your app\nexceeds it, cdk-nextjs fails at synth with the measured size and points you here:\n\n```\nFunction group \"default\" is 274 MB unzipped, over Lambda's 250 MB limit. Use the\n`functionGroups` prop to package routes into separate functions. Note that\nsplitting only removes route-local code — anything reachable from a shared layout\nor the `next` runtime is in every group.\n```\n\n`functionGroups` declares which routes get their own Lambda. Everything you do\nnot name stays on the `default` function:\n\n```ts\nnew NextjsGlobalFunctions(this, \"Nextjs\", {\n  buildDirectory: join(import.meta.dirname, \"..\", \"web\"),\n  functionGroups: [\n    { name: \"reports\", routes: [\"/dashboard/reports/**\"] },\n    { name: \"admin\", routes: [\"/admin\", \"/admin/**\", \"/settings\"] },\n  ],\n});\n```\n\nEach group becomes one Lambda function containing only the routes it owns (plus\nthe framework closure every function needs), and one CloudFront behavior — or API\nGateway resource, for `NextjsRegionalFunctions` — per pattern.\n\n**Route patterns** are either an exact path (`/settings`) or a subtree\n(`/admin/**`). A subtree owns what is _under_ it, not the path itself:\n`/admin/**` does not claim `/admin`. To own a page and everything under it, list\nboth, as the example above does: `[\"/admin\", \"/admin/**\"]`. Where two groups\ncould both match, the longest pattern wins, so `/api/**` and `/api/reports/**`\ncan coexist in different groups. Dynamic segments (`/blog/[slug]`), route group\nsegments (`/(marketing)/about`), `/`, and `/**` are rejected at synth —\nCloudFront matches literal path prefixes and cannot express them. `/index` is\naccepted for an App Router `app/index/page.tsx`, but not for a Pages Router home\npage, which is the same file as `/`.\n\n**What is routed for you.** Patterns decide which _files_ a group packages; the\nedge then has to send every URL those files serve to that group. cdk-nextjs\nderives these without extra patterns:\n\n- A Pages Router page's data URL, `/_next/data/<buildId>/<page>.json`. The\n  behavior carries the literal build ID, so it changes on every deploy; a\n  client still on the previous build falls through to the `default` function,\n  which answers 404, and the Next.js client reloads the page.\n- The `trailingSlash` form of an exact pattern (`/pricing/`). CloudFront gets a\n  behavior for it; on `NextjsRegionalFunctions` none is needed, because API\n  Gateway already routes `/pricing/` to the `/pricing` resource.\n- The parent of an optional catch-all. `/shop/**` moving\n  `app/shop/[[...slug]]/page.tsx` also routes `/shop`, which the same file\n  serves. Do not add `/shop` yourself: it matches no route and is rejected.\n- An [interception route](https://nextjs.org/docs/app/api-reference/file-conventions/intercepting-routes)\n  is packaged with the group that owns the URL it intercepts, not by its own\n  path: `app/feed/(..)photo/[id]` follows `/photo/[id]`, because a soft\n  navigation requests `/photo/1` and Next.js rewrites it in whichever function\n  receives it.\n\n**What synth rejects.** After assigning routes, cdk-nextjs replays the\nCloudFront behaviors over every URL each file serves and fails when one would\nreach a function without its file, naming the file, the URL and the pattern to\nadd. That covers:\n\n- A file behind several templates that a pattern only partly covers — root\n  params (`app/[locale]/page.tsx` prerendered as `/en` and `/de`) grouped with\n  `/en` alone. A dynamic first segment can never be routed, so such a file stays\n  in `default`.\n- An intercepted URL space split between groups (`/photo/[id]` in one,\n  `/photo/1` in another), since the intercepting file cannot be in both.\n- A `next.config` rewrite whose source reaches one group and whose destination\n  file is in another: rewrites run inside the function that received the\n  request. Only rewrites with a literal destination are checked.\n- A group pattern that duplicates a top-level `public/` entry's behavior\n  (`public/docs/` and `/docs/**`), or sits under one (`/docs/guide/**`), which\n  would send the group's routes to S3.\n\nNot checked, because it is only known at request time: **a middleware\n`NextResponse.rewrite()`** to a route in another group reaches the function that\nreceived the original URL, which lacks the route's file. It answers 404 (or a\n308 to the canonical URL when only the case differs) and logs a warning naming\nthe group that owns the route. Keep a middleware rewrite's source and\ndestination in the same group. The same goes\nfor a `next.config` rewrite whose destination is built from its parameters\n(`/b/:slug` → `/blog/:slug`), and for a dynamic segment of a `default` route\nthat overlaps a group's literal path (`/[section]/intro` against `/docs/**`).\nLikewise **a Pages Router `res.revalidate()`** renders the page in the function\nthat called it, so it can only revalidate pages in its own group; the error\nnames the group that owns the page. Use `revalidatePath()` or `revalidateTag()`\nacross groups. And **an `<Image>` whose `src` is a route in another group**\n(`/api/avatar/42` under an `/api/**` group) can't be optimized: `/_next/image`\nruns in the `default` function, which fetches a local source that isn't a\n`public/` or `_next/static` file by running its route in-process, and it doesn't\ncarry that route, so the image request fails. Keep image-serving routes in\n`default`, or point `src` at a `public/` file or a remote URL.\n\n**What splitting does and does not save.** Every function ships the same `next`\nruntime closure, so splitting only moves route-_local_ code and its dependencies.\nA group whose routes import a large library is worth extracting; splitting an app\nin half does not halve either function.\n\nNotes:\n\n- Group names must be valid CDK construct ids (letters, digits, `-`). `default`\n  is reserved.\n- A pattern that matches no route in the build is a synth error, not a silent\n  no-op — it is almost always a typo.\n- Cannot be combined with `i18n`: locale-prefixed routes would need one\n  CloudFront behavior per locale per pattern.\n- Group patterns (and the routes derived from them above) count against the\n  same CloudFront behavior budget as your `public/` entries (see\n  [Limitations](#limitations)).\n- Per-group `overrides` let you size each function independently:\n  `{ name: \"reports\", routes: [...], overrides: { functionProps: { memorySize: 2048 } } }`.\n\n## Architecture\n\nHow requests are served inside the compute — the adapter runtime, and where it deliberately differs from `next start` — is in [docs/adapter-runtime.md](./docs/adapter-runtime.md).\n\n### `NextjsGlobalFunctions`\n\nArchitecture includes [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) Functions to respond to dynamic requests and [CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html) Distribution to globally serve requests and distribute static assets. Use this construct when you have unpredictable traffic, can afford occasional latency (i.e. cold starts - [typically 1% of production traffic](https://aws.amazon.com/blogs/compute/operating-lambda-performance-optimization-part-1/)), and/or want the most granular pricing model. ([code](./src/root-constructs/nextjs-global-functions.ts))\n\n```mermaid\narchitecture-beta\n    group aws(cloud)[AWS Cloud]\n    group cache[Cache Layer] in aws\n\n    service user(internet)[User]\n    service cloudfront(server)[CloudFront Distribution] in aws\n    service s3static(disk)[S3 Static Assets] in aws\n    service lambda(server)[Lambda Function] in aws\n    service dynamodb(database)[DynamoDB Table] in cache\n    service s3cache(disk)[S3 Cache Bucket] in cache\n\n    user:R --> L:cloudfront\n    cloudfront:R --> L:s3static\n    cloudfront:R --> L:lambda\n    lambda:R --> L:dynamodb\n    lambda:R --> L:s3cache\n```\n\n### `NextjsGlobalContainers`\n\nArchitecture includes [ECS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) containers to respond to dynamic requests and [CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html) Distribution to globally serve requests and distribute static assets. Use this option when you have predictable traffic, need the lowest latency, and/or can afford a less granular pricing model. ([code](./src/root-constructs/nextjs-global-containers.ts))\n\n```mermaid\narchitecture-beta\n    group aws(cloud)[AWS Cloud]\n    group vpc[VPC] in aws\n    group cache[Cache Layer] in aws\n\n    service user(internet)[User]\n    service cloudfront(server)[CloudFront Distribution] in aws\n    service s3static(disk)[S3 Static Assets] in aws\n    service alb(server)[Application Load Balancer] in vpc\n    service fargate(server)[ECS Fargate Containers] in vpc\n    service dynamodb(database)[DynamoDB Table] in cache\n    service s3cache(disk)[S3 Cache Bucket] in cache\n\n    user:R --> L:cloudfront\n    cloudfront:R --> L:s3static\n    cloudfront:R --> L:alb\n    alb:R --> L:fargate\n    fargate:R --> L:dynamodb\n    fargate:R --> L:s3cache\n```\n\n### `NextjsRegionalContainers`\n\nArchitecture includes [ECS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) containers to respond to dynamic requests and [Application Load Balancer](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/) to regionally serve requests. Use this options when you cannot use Amazon CloudFront (i.e. [AWS GovCloud](https://aws.amazon.com/govcloud-us/?whats-new.sort-by=item.additionalFields.postDateTime&whats-new.sort-order=desc)). ([code](./src/root-constructs/nextjs-regional-containers.ts#L41))\n\n```mermaid\narchitecture-beta\n    group aws(cloud)[AWS Cloud]\n    group vpc[VPC] in aws\n    group cache[Cache Layer] in aws\n\n    service user(internet)[User]\n    service alb(server)[Application Load Balancer] in vpc\n    service fargate(server)[ECS Fargate Containers] in vpc\n    service dynamodb(database)[DynamoDB Table] in cache\n    service s3cache(disk)[S3 Cache Bucket] in cache\n\n    user:R --> L:alb\n    alb:R --> L:fargate\n    fargate:R --> L:dynamodb\n    fargate:R --> L:s3cache\n```\n\n### `NextjsRegionalFunctions`\n\nArchitecture includes [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) Functions to respond to dynamic requests and [API Gateway REST API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html) to regionally serve requests and distribute static assets. Use this options when you cannot use Amazon CloudFront (i.e. [AWS GovCloud](https://aws.amazon.com/govcloud-us/?whats-new.sort-by=item.additionalFields.postDateTime&whats-new.sort-order=desc)). ([code](./src/root-constructs/nextjs-regional-functions.ts))\n\n```mermaid\narchitecture-beta\n    group aws(cloud)[AWS Cloud]\n    group cache[Cache Layer] in aws\n\n    service user(internet)[User]\n    service apigateway(server)[API Gateway REST API] in aws\n    service s3static(disk)[S3 Static Assets] in aws\n    service lambda(server)[Lambda Function] in aws\n    service dynamodb(database)[DynamoDB Table] in cache\n    service s3cache(disk)[S3 Cache Bucket] in cache\n\n    user:R --> L:apigateway\n    apigateway:R --> L:s3static\n    apigateway:R --> L:lambda\n    lambda:R --> L:dynamodb\n    lambda:R --> L:s3cache\n```\n\n## Why\n\nThe simplest path to deploy Next.js is on [Vercel](https://vercel.com/) - the Platform-as-a-Service company behind Next.js. However, deploying to Vercel can be expensive and some developers want all of their workloads running _directly_ on AWS. Developers can deploy Next.js on AWS through [AWS Amplify Hosting](https://docs.aws.amazon.com/amplify/latest/userguide/ssr-Amplifysupport.html), but Amplify does not support all Next.js features and manages AWS resources for you so they cannot be customized. If Amplify meets your requirements we recommend you use it, but if you want to use all Next.js features or want more visibility into the AWS resources then this construct is for you.\n\n## Design Principles\n\n- Integrate through Next.js's official interfaces. Build on the [Deployment Adapter](https://nextjs.org/docs/app/guides/deployment-adapters) API and [`@next/routing`](https://www.npmjs.com/package/@next/routing) rather than Next.js internals, so new Next.js versions rarely break this construct. Where no public interface exists yet, the dependency is listed in [Next.js private APIs](docs/nextjs-private-apis.md).\n- Security first.\n- One architecture does not fit all.\n- Enable customization everywhere.\n\n## Bring Your Own Resources\n\ncdk-nextjs supports importing existing AWS resources instead of creating new ones. This is especially useful for per-branch (MR/PR) environments where you deploy shared infrastructure (VPC, ECS cluster, ALB) once and spin up lightweight branch stacks that reuse it.\n\n### Supported Resources\n\n| Resource                    | Prop                 | Available On                                         |\n| --------------------------- | -------------------- | ---------------------------------------------------- |\n| S3 Cache Bucket             | `cacheBucket`        | All constructs                                       |\n| DynamoDB Revalidation Table | `revalidationTable`  | All constructs                                       |\n| S3 Static Assets Bucket     | `staticAssetsBucket` | All constructs                                       |\n| CloudFront Distribution     | `distribution`       | `NextjsGlobalFunctions`, `NextjsGlobalContainers`    |\n| ECS Cluster                 | `ecsCluster`         | `NextjsGlobalContainers`, `NextjsRegionalContainers` |\n| ALB                         | `alb`                | `NextjsGlobalContainers`, `NextjsRegionalContainers` |\n\n### Resource Isolation\n\n- **Cache bucket and DynamoDB table** must be dedicated to one deployment. Sharing either between deployments (branches, stages, apps) is not supported: each deploy's post-deploy step prunes every cache object and revalidation entry that isn't from its own current build, so deploying one branch wipes the others' caches. Buckets and tables are cheap, so give each deployment its own, or leave `cacheBucket`/`revalidationTable` unset and let cdk-nextjs create them (they are removed with the stack).\n- **Static assets bucket** can be shared, but only between deployments with different `basePath`s, which become their S3 key prefixes. Pruning only looks at `<basePath>/_next/`, so it never touches another prefix. Two deployments under the same prefix (for example two subdomain previews both 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. `NextjsGlobalFunctions` and `NextjsGlobalContainers` read the `basePath` out of your Next.js build and use it as the S3 key prefix, since CloudFront serves assets from S3 by request path and the two can't differ. Set the `basePath` prop only if you want to be explicit about it; a value that disagrees with your app's fails at synth. Each deployment also adds an ownership tag per static asset upload (1 to 3, by whether the build has `public/` files and service workers) to a bucket created in your CDK app; an imported bucket gets none. S3 allows 50 tags per bucket, so such a bucket holds at least 16 deployments.\n\n### Shared ALB and `removeAutoCreatedListener()`\n\n`ApplicationLoadBalancedFargateService` always creates a listener on port 80 — there is no opt-out. When you import an ALB that already has a listener on that port, the duplicate causes a deployment failure. Since CDK doesn't expose a way to prevent this, `removeAutoCreatedListener()` surgically removes the generated CloudFormation resources: the `CfnListener`, its security group ingress rule, rebuilds the ECS service `DependsOn` without the deleted listener, and removes auto-created `CfnOutput` resources:\n\n```ts\nconst nextjs = new NextjsRegionalContainers(this, \"Nextjs\", {\n  // ...\n  alb: sharedAlb,\n  ecsCluster: sharedCluster,\n});\nnextjs.nextjsContainers.removeAutoCreatedListener();\n```\n\n### Examples\n\nSee [examples/bring-your-own/](./examples/bring-your-own/) for a complete deployable example with a shared VPC, ECS cluster, and ALB, per-branch host-header routing, and a cache bucket, revalidation table, and static assets bucket per branch.\n\n## Preview Environments (Per-Branch Deployments)\n\ncdk-nextjs can deploy ephemeral preview environments per merge request (MR) or pull request (PR). The recommended approach uses subdomain-based routing (`pr-123.app.example.com`) so each preview environment runs the same Next.js build as production — no `basePath` configuration or separate builds required.\n\nSee [examples/bring-your-own/](./examples/bring-your-own/) for a fully deployable example using `NextjsRegionalContainers` with a shared VPC, ALB, and ECS Cluster (connected via SSM Parameter Store), and S3 buckets and a DynamoDB table owned by each branch stack.\n\nEach preview environment needs its own cache bucket and revalidation table (see [Resource Isolation](#resource-isolation)). Since every preview serves the same build at the root, give each its own static assets bucket too. Leaving `cacheBucket`, `revalidationTable`, and `staticAssetsBucket` unset does this: cdk-nextjs creates them in the branch stack and deletes them when it's torn down.\n\n### Prerequisites\n\n- Wildcard DNS record: `*.app.example.com` → your routing layer (ALB, CloudFront, API Gateway)\n- Wildcard ACM certificate: `*.app.example.com`\n\n### Per-Architecture Recommendations\n\n#### `NextjsGlobalContainers` and `NextjsRegionalContainers` (ALB-based)\n\nSubdomain routing via ALB host-based listener rules. This is the fastest and simplest approach. For `NextjsGlobalContainers`, CloudFront forwards the `Host` header to the ALB origin, so the ALB handles all branch routing — no CloudFront changes needed per branch.\n\nSee [examples/bring-your-own/](./examples/bring-your-own/) for the full implementation.\n\n#### `NextjsRegionalFunctions` (API Gateway)\n\nSubdomain routing via API Gateway custom domain mappings.\n\n1. Per branch, deploy a cdk-nextjs stack that creates its own API Gateway, Lambda function, S3 buckets, and DynamoDB table\n2. Create an API Gateway custom domain (`pr-123.app.example.com`) mapped to the branch's API stage\n3. Tear down the branch stack on MR close\n\n#### `NextjsGlobalFunctions` (Lambda + CloudFront)\n\nRequires a separate cdk-nextjs stack per branch, each with its own CloudFront distribution. CloudFront cannot route to different Lambda Function URL origins based on the `Host` header — origin selection is determined by cache behavior path patterns, not request headers.\n\n1. Per branch, deploy a full cdk-nextjs stack that creates its own CloudFront distribution, Lambda function, S3 buckets, and DynamoDB table\n2. Point `pr-123.app.example.com` DNS to the branch's CloudFront distribution\n3. Tear down the branch stack on MR close\n\nNote: CloudFront distributions take several minutes to create/update, so this architecture has the slowest preview environment spin-up time.\n\n## Limitations\n\n- If using `NextjsGlobalFunctions` or `NextjsGlobalContainers` (which use CloudFront), each top level file/directory in `public/` takes a CloudFront cache behavior, and a distribution's default quota is 75 behaviors (cdk-nextjs uses 3 to 6 itself). We recommend you put all of your public assets into one top level directory (i.e. public/static) so you don't reach this limit. If you raise the quota for your account, set `maxCacheBehaviors` on the distribution props (`overrides.nextjsGlobalFunctions.nextjsDistributionProps`, or the Containers equivalent) to match. The synth check only counts the behaviors cdk-nextjs adds, so if you pass your own `distribution` (or add behaviors through `overrides.nextjsDistribution.distributionProps`), lower `maxCacheBehaviors` by the behaviors it already has. See [CloudFront Quotas](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html) for more information.\n- If using `NextjsGlobalFunctions` or `NextjsGlobalContainers`, on-demand revalidation ([revalidatePath](https://nextjs.org/docs/app/api-reference/functions/revalidatePath), [revalidateTag](https://nextjs.org/docs/app/api-reference/functions/revalidateTag)) creates the CloudFront invalidations for you (so does the Pages Router's `res.revalidate()`, for the page's HTML and `_next/data` copies), but [invalidations](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html) are eventually consistent: until one completes (usually seconds, occasionally minutes), some edge locations can still serve the previous copy.\n  - **Burst limit.** CloudFront allows 15 wildcard invalidation paths in progress per distribution, and each page cdk-nextjs invalidates is one wildcard path (`/blog*`). Next.js sends every `revalidatePath`/`revalidateTag` from one request as a single call, one invalidation per cache-life profile, however many pages it covers. A Pages Router `res.revalidate()` sends one invalidation per call, and a page regenerated after a stale-while-revalidate `revalidateTag(tag, profile)` sends one more when it lands. When the quota is full, cdk-nextjs retries the request as a single `/*` (a colder edge, never a stale page). If that is also rejected, it logs `Failed to create CloudFront invalidation` and the page stays stale at the edge until its `s-maxage` expires.\n  - **For bulk updates** (a CMS webhook touching many pages), call `revalidateTag` with a tag the pages share, or `revalidatePath` for each page within one request, rather than looping `res.revalidate()`. If you need to know when invalidations are dropped, add a CloudWatch Logs metric filter on that log line.\n- If using `NextjsGlobalFunctions`, a client-supplied `Authorization` header does not reach your app: CloudFront signs each request to the Lambda Function URL with SigV4, which uses that header. Send credentials under a different name (e.g. `x-authorization`) and read that header in your app. cdk-nextjs does not rename it for you — it no longer uses [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter), so `AWS_LWA_AUTHORIZATION_SOURCE` no longer applies.\n- If using `NextjsGlobalFunctions`, a `POST` or `PUT` with a request body must carry an `x-amz-content-sha256` header holding the hex SHA-256 of that body. This is [AWS behavior](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-lambda.html), not a cdk-nextjs choice: CloudFront signs the origin request to the Lambda Function URL with SigV4 but does not hash the body, and Lambda rejects an unsigned payload with `403 InvalidSignatureException`. Requests from your own pages are handled for you — cdk-nextjs injects a `fetch`/`XMLHttpRequest` wrapper into the client bundle that adds the header, so server actions, route handlers, `fetch` and `XMLHttpRequest` from the browser work untouched, whatever the body type. The exception is a native `<form method=\"post\">` submitted before the page hydrates (a server action form without JavaScript, or clicked before the bundle loads): the browser sends it, not the wrapper, so it has no header and gets the 403. **Anything that is not that browser bundle has to add the header itself**: `curl`, a mobile app, a webhook provider, another service calling your API routes. Server-to-server callers can compute it with the AWS SDK's `Sha256`, or with `crypto.createHash(\"sha256\").update(body).digest(\"hex\")`. The other three deployment types are unaffected.\n- If using `NextjsGlobalFunctions`, a `HEAD` request is answered with `content-length: 0`, whatever length your handler declares. This is Lambda Function URL behavior: the same runtime's declared length reaches the client through API Gateway (`NextjsRegionalFunctions`) and from an ALB, with or without CloudFront in front (the two Containers types).\n- Group patterns declared via [`functionGroups`](#splitting-a-large-app-across-functions) also count against the CloudFront behavior limit above.\n- If using `NextjsRegionalFunctions` without a custom domain, API Gateway REST APIs require a [stage name](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-stages.html) (default: `/prod`) to be specified. This causes links to pages and static assets to break because they're not prefixed with the stage name. You can work around this issue by specifying [basePath](https://nextjs.org/docs/app/api-reference/config/next-config-js/basePath) in next.config.js as your stage name — leave the construct's `basePath` prop unset when you do, since API Gateway strips the stage before matching resources. API Gateway strips the stage from the path it passes to Lambda; cdk-nextjs puts it back for an app whose `basePath` starts with it, reading the stage off each request, so no middleware is needed and a renamed stage needs no configuration. Mapping a custom domain at the root avoids all of this — see [examples/regional-functions/README.md](./examples/regional-functions/README.md#with-a-custom-domain-no-stage-workarounds).\n\n## Additional Security Recommendations\n\nThis construct by default implements all AWS security best practices that a CDK construct library reasonably can considering cost and complexity. Below are additional security practices we recommend you implement within your CDK app. Please see them below:\n\n- [VPC Flow Logs](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html). See [examples/](./examples) for sample implementation.\n- [Scan ECR Images For Vulnerabilities](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-scanning.html).\n- For `NextjsGlobalFunctions` and `NextjsGlobalContainers`, [CloudFront Access Logs](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/AccessLogs.html). See [examples/](./examples) for sample implementation.\n- For `NextjsGlobalContainers` and `NextjsRegionalContainers`, use [ALB HTTPS Listener](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-https-listener.html)\n- If using `NextjsGlobalContainers` and `NextjsRegionalContainers`, enable `ReadonlyRootFilesystem`. This will remove ability to use Static On-Demand feature of Next.js so it's not enabled by default, but is recommended for security.\n\n## Estimated Costs\n\n### Assumptions\n\nThe following basic assumptions were used for a typical medium Next.js app. See [docs/usage.xlsx](./docs/usage.xlsx) for detailed assumptions and usage per construct type that you can plug into AWS Pricing Calculator.\n\n| Metric                                                       | Value |\n| ------------------------------------------------------------ | ----- |\n| Monthly Active Users                                         | 1K    |\n| Pages Visited Per Month Per User                             | 100   |\n| Avg Request Size                                             | 50KB  |\n| Static Requests Per Page (js, css, etc)                      | 15    |\n| Static Requests Cache Hit %                                  | 50%   |\n| Static Assets Size                                           | 10GB  |\n| Dynamic Requests Per Page (document, optimized images, etc.) | 5     |\n| Dynamic Cache Read %                                         | 50%   |\n| Dynamic Cache Write %                                        | 5%    |\n| Dynamic Cache Data Size                                      | 10GB  |\n| Average Dynamic Cache Request Size                           | 100KB |\n| Dynamic Revalidate Tag %                                     | 1%    |\n\nMore Details:\n\n- Assume ARM architecture for compute\n- AWS Region: us-east-1\n- Excludes charges related to: CloudWatch Logs, NAT Gateway data processing\n\n### NextjsGlobalFunctions\n\n[AWS Pricing Calculator](https://calculator.aws/#/estimate?id=23611f6fea87ef05d5fe87c33135ddde43b17a98)\n\n| Service    | Monthly Usage                                  | Estimated Monthly Cost (USD) |\n| ---------- | ---------------------------------------------- | ---------------------------- |\n| Lambda     | 500K requests, 2 GB memory, 150ms avg duration | $0.00 (Always Free Tier)     |\n| CloudFront | 2M requests, 100 GB transfer to internet       | $0.00 (Always Free Tier)     |\n| S3         | 20 GB storage, 1M GET, 250K PUT requests       | $2.11                        |\n| DynamoDB   | 10 GB storage, 5K Reads, 5K Writes             | $2.50                        |\n| Total      |                                                | $8.09                        |\n\n### NextjsGlobalContainers\n\n[AWS Pricing Calculator](https://calculator.aws/#/estimate?id=02f0073e612d1eee2a7ccace2c636adc5f0acab7)\n\n| Service     | Monthly Usage                            | Estimated Monthly Cost (USD) |\n| ----------- | ---------------------------------------- | ---------------------------- |\n| ECS Fargate | 1 task (1 vCPU, 2 GB)                    | $28.44                       |\n| ALB         | 1 LB, 1.04GB/hr, 5.79 conn/sec           | $22.50                       |\n| CloudFront  | 2M requests, 100 GB transfer to internet | $0.00 (Always Free Tier)     |\n| S3          | 20 GB storage, 1M GET, 250K PUT requests | $2.11                        |\n| DynamoDB    | 10 GB storage, 5K Reads, 5K Writes       | $2.50                        |\n| VPC         | NAT Gateway, 2 AZs                       | $65.70                       |\n| Total       |                                          | $121.25                      |\n\n### NextjsRegionalContainers\n\n[AWS Pricing Calculator](https://calculator.aws/#/estimate?id=e214abe60eb4e24fc5866d07ef4355393261af3c)\n\n| Service     | Monthly Usage                              | Estimated Monthly Cost (USD) |\n| ----------- | ------------------------------------------ | ---------------------------- |\n| ECS Fargate | 1 task (2 vCPU, 4 GB), always on           | $28.44                       |\n| ALB         | 1 LB, 4.17 GB/hr, 23.15 conn/sec           | $40.78                       |\n| S3          | 10 GB storage, 250K GET, 250K PUT requests | $1.58                        |\n| DynamoDB    | 10 GB storage, 5K Reads, 5K Writes         | $2.50                        |\n| VPC         | NAT Gateway, 2 AZs                         | $65.70                       |\n| Total       |                                            | $139.00                      |\n\n### NextjsRegionalFunctions\n\n[AWS Pricing Calculator](https://calculator.aws/#/estimate?id=60da38c7993c1baeee2fee4bd19ba6441608bb15)\n\n| Service     | Monthly Usage                                  | Estimated Monthly Cost (USD) |\n| ----------- | ---------------------------------------------- | ---------------------------- |\n| Lambda      | 500K requests, 2 GB memory, 150ms avg duration | $0.00 (Always Free Tier)     |\n| API Gateway | 2M requests                                    | $7.00                        |\n| S3          | 10 GB storage, 250K GET, 250K PUT requests     | $1.58                        |\n| DynamoDB    | 10 GB storage, 5K Reads, 5K Writes             | $2.50                        |\n| Total       |                                                | $11.08                       |\n\n## Performance\n\nMeasured with [k6](https://grafana.com/docs/k6/latest/) from EC2 in us-east-1, the region of the stacks under test (one load generator per stack), against a small benchmark app ([`examples/bench-app`](./examples/bench-app)) that makes no calls outside its own stack. Functions run the default 2048 MB Lambda functions. Containers run the default 1 vCPU / 2 GB Fargate tasks, with CPU autoscaling from 2 to 10 tasks added (the default is one task and no autoscaling). Methodology, caveats, and how to reproduce the numbers: [`examples/load-tests`](./examples/load-tests).\n\nWhat each route measures:\n\n- `static-asset`, `static`, `image`: CloudFront's cache on the Global constructs, and the construct itself on the Regional ones.\n- `isr`: the cache until the page is stale (10 s), then a background revalidation through the S3 + DynamoDB cache.\n- `ssr`, `stream`, `rsc`, `api`: the construct's compute on every request, on every construct.\n\n<!-- tables generated by `pnpm report` in examples/load-tests -->\n\n| Construct                  | `ssr` at 10 req/s | `ssr` at 50 req/s                         | `ssr` capacity | `isr` capacity | Cold start p50 |\n| -------------------------- | ----------------- | ----------------------------------------- | -------------- | -------------- | -------------- |\n| `NextjsGlobalFunctions`    | 36 / 103          | 33 / 84                                   | ≥ 6560 req/s   | ≥ 6560 req/s   | 1390 ms        |\n| `NextjsGlobalContainers`   | 19 / 44           | 18 / 219                                  | 194 req/s      | ≥ 6400 req/s   | –              |\n| `NextjsRegionalContainers` | 22 / 172          | 1972 / 39536 ⚠️ 0.54% errors, 76% dropped | 675 req/s      | ≥ 6075 req/s   | –              |\n| `NextjsRegionalFunctions`  | 32 / 114          | 30 / 103                                  | ≥ 6560 req/s   | ≥ 6560 req/s   | 1380 ms        |\n\n_Latency is p50 / p99 in ms, with every route loaded at that rate at once. Capacity is the highest rate sustained with p99 under 1000 ms and under 1% errors._\n\nWhat this means for choosing one:\n\n- **Functions constructs scale with no sizing.** Both held at least 6,560 req/s of SSR, the load generator's limit, at the same latency as at 10 req/s. The cost is a cold start of about 1.4 s on a new execution environment.\n- **Containers constructs are fastest per request but need sizing.** Two 1 vCPU tasks served SSR at 19–22 ms p50 against Lambda's ~30 ms, but tasks take minutes to add. Past capacity they don't degrade gradually: tasks too busy to answer the ALB health check are replaced, which leaves fewer tasks for the same load. Leave headroom.\n- **CloudFront carries the Global constructs' cached traffic.** Prerendered pages, ISR hits, images and assets were answered at the edge in 2–3 ms at every rate. On the Regional constructs every request reaches the construct: `NextjsRegionalContainers` serves assets and image optimization from the same tasks, so 50 req/s on every route at once (400 req/s) is already more than two tasks handle.\n- **Cached pages scale on every construct.** ISR hits held at least 6,000 req/s on all four: at the edge on the Global constructs, and through the S3 + DynamoDB cache on the Regional ones, where each instance holds a tag's revalidation marker for a second (`CDK_NEXTJS_TAG_REFRESH_MS`, see the [Caching Guide](./docs/caching-guide.md)).\n\n<details>\n<summary><code>NextjsGlobalFunctions</code></summary>\n\nLatency per route, p50 / p99 in ms, with every route at the same rate at once:\n\n| Route         | 10 req/s  | 50 req/s  | 250 req/s | 1000 req/s | CDN hits |\n| ------------- | --------- | --------- | --------- | ---------- | -------- |\n| static-asset  | 2.1 / 4.8 | 2.1 / 4.7 | 2.0 / 4.9 | 2.1 / 11   | 100%     |\n| static        | 3.3 / 7.5 | 3.2 / 6.8 | 3.1 / 7.3 | 3.2 / 13   | 100%     |\n| isr           | 3.3 / 7.4 | 3.3 / 7.7 | 3.2 / 7.2 | 3.2 / 12   | 100%     |\n| ssr           | 36 / 103  | 33 / 84   | 31 / 86   | 29 / 73    | 0%       |\n| stream        | 233 / 268 | 230 / 261 | 228 / 259 | 226 / 252  | 0%       |\n| stream (TTFB) | 32 / 89   | 29 / 66   | 27 / 65   | 25 / 57    |          |\n| rsc           | 32 / 67   | 28 / 61   | 27 / 60   | 25 / 52    | 0%       |\n| api           | 29 / 79   | 26 / 55   | 24 / 61   | 23 / 47    | 0%       |\n| image         | 3.2 / 6.3 | 3.1 / 6.8 | 3.1 / 7.0 | 3.1 / 12   | 100%     |\n\nCapacity: `isr` ≥ 6560 req/s, `ssr` ≥ 6560 req/s.\n\nCold start, time to first byte of `/ssr` on a new execution environment: p50 1390 ms, p90 1451 ms (warm: 84 ms).\n\nBrowser, p75 in ms, under 50 req/s per route:\n\n| Route  | LCP | TTFB | Client-side navigation |\n| ------ | --- | ---- | ---------------------- |\n| static | 76  | 13   | 15                     |\n| ssr    | 80  | 39   | 53                     |\n| isr    | 52  | 8.7  | 12                     |\n| stream | 64  | 34   | 38                     |\n| image  | 52  | 6.7  | 10                     |\n\n</details>\n\n<details>\n<summary><code>NextjsGlobalContainers</code></summary>\n\nLatency per route, p50 / p99 in ms, with every route at the same rate at once:\n\n| Route         | 10 req/s  | 50 req/s  | CDN hits |\n| ------------- | --------- | --------- | -------- |\n| static-asset  | 1.4 / 3.9 | 1.5 / 3.7 | 100%     |\n| static        | 1.9 / 4.8 | 1.8 / 3.7 | 100%     |\n| isr           | 2.0 / 4.4 | 1.7 / 4.0 | 100%     |\n| ssr           | 19 / 44   | 18 / 219  | 0%       |\n| stream        | 217 / 242 | 217 / 359 | 0%       |\n| stream (TTFB) | 17 / 45   | 16 / 207  |          |\n| rsc           | 12 / 26   | 12 / 86   | 0%       |\n| api           | 11 / 23   | 10 / 81   | 0%       |\n| image         | 2.0 / 4.7 | 1.7 / 4.1 | 100%     |\n\nCapacity: `isr` ≥ 6400 req/s, `ssr` 194 req/s.\n\nBrowser, p75 in ms, under 50 req/s per route:\n\n| Route  | LCP | TTFB | Client-side navigation |\n| ------ | --- | ---- | ---------------------- |\n| static | 88  | 12   | 17                     |\n| ssr    | 80  | 26   | 39                     |\n| isr    | 56  | 6.1  | 13                     |\n| stream | 64  | 20   | 25                     |\n| image  | 52  | 5.4  | 11                     |\n\n</details>\n\n<details>\n<summary><code>NextjsRegionalContainers</code></summary>\n\nLatency per route, p50 / p99 in ms, with every route at the same rate at once:\n\n| Route         | 10 req/s  | 50 req/s                                  | CDN hits |\n| ------------- | --------- | ----------------------------------------- | -------- |\n| static-asset  | 18 / 159  | 1698 / 28824 ⚠️ 0.40% errors, 72% dropped | no CDN   |\n| static        | 41 / 163  | 916 / 28298 ⚠️ 0.46% errors, 66% dropped  | no CDN   |\n| isr           | 40 / 169  | 697 / 27146 ⚠️ 0.36% errors, 57% dropped  | no CDN   |\n| ssr           | 22 / 172  | 1972 / 39536 ⚠️ 0.54% errors, 76% dropped | no CDN   |\n| stream        | 221 / 354 | 1909 / 27423 ⚠️ 0.44% errors, 72% dropped | no CDN   |\n| stream (TTFB) | 19 / 166  | 1881 / 27162                              |          |\n| rsc           | 9.4 / 64  | 433 / 26066 ⚠️ 0.25% errors, 39% dropped  | no CDN   |\n| api           | 6.9 / 55  | 429 / 26041 ⚠️ 0.25% errors, 38% dropped  | no CDN   |\n| image         | 140 / 440 | 1599 / 27489 ⚠️ 0.22% errors, 69% dropped | no CDN   |\n\nCapacity: `isr` ≥ 6075 req/s, `ssr` 675 req/s.\n\nBrowser, p75 in ms, under 10 req/s per route. `static` is each visit's first page: on a plain-HTTP origin, Chrome tries HTTPS first and falls back after about 3 s (HTTPS-Upgrades), which real visitors pay too. Put a certificate on the ALB to avoid it.\n\n| Route  | LCP  | TTFB | Client-side navigation |\n| ------ | ---- | ---- | ---------------------- |\n| static | 3100 | 3047 | 16                     |\n| ssr    | 68   | 14   | 27                     |\n| isr    | 88   | 43   | 13                     |\n| stream | 48   | 11   | 13                     |\n| image  | 212  | 38   | 9.6                    |\n\n</details>\n\n<details>\n<summary><code>NextjsRegionalFunctions</code></summary>\n\nLatency per route, p50 / p99 in ms, with every route at the same rate at once:\n\n| Route         | 10 req/s  | 50 req/s  | 250 req/s | 1000 req/s | CDN hits |\n| ------------- | --------- | --------- | --------- | ---------- | -------- |\n| static-asset  | 34 / 76   | 32 / 72   | 30 / 72   | 30 / 68    | no CDN   |\n| static        | 58 / 138  | 57 / 140  | 57 / 147  | 57 / 127   | no CDN   |\n| isr           | 58 / 149  | 56 / 124  | 56 / 145  | 55 / 125   | no CDN   |\n| ssr           | 32 / 114  | 30 / 103  | 29 / 115  | 29 / 98    | no CDN   |\n| stream        | 229 / 293 | 227 / 288 | 227 / 299 | 226 / 282  | no CDN   |\n| stream (TTFB) | 27 / 85   | 25 / 84   | 25 / 97   | 24 / 76    |          |\n| rsc           | 27 / 76   | 26 / 73   | 25 / 83   | 25 / 70    | no CDN   |\n| api           | 24 / 84   | 22 / 70   | 22 / 97   | 22 / 67    | no CDN   |\n| image         | 127 / 210 | 125 / 221 | 125 / 236 | 123 / 211  | no CDN   |\n\nCapacity: `isr` ≥ 6560 req/s, `ssr` ≥ 6560 req/s.\n\nCold start, time to first byte of `/ssr` on a new execution environment: p50 1380 ms, p90 1442 ms (warm: 71 ms).\n\nBrowser, p75 in ms, under 50 req/s per route:\n\n| Route  | LCP | TTFB | Client-side navigation |\n| ------ | --- | ---- | ---------------------- |\n| static | 128 | 70   | 17                     |\n| ssr    | 88  | 35   | 50                     |\n| isr    | 108 | 62   | 13                     |\n| stream | 64  | 31   | 36                     |\n| image  | 220 | 60   | 9.6                    |\n\n</details>\n\n## Guides\n\n- [Caching Guide](./docs/caching-guide.md)\n- [Pruning Guide](./docs/pruning-guide.md)\n- [Native Dependencies Guide](./docs/native-dependencies-guide.md)\n- [Next Build Output Guide](./docs/next-build-output-guide.ts)\n- [Development Guide](./docs/development-guide.ts)\n\n## Contributing\n\nSteps to build locally:\n\n1. `git clone https://github.com/cdklabs/cdk-nextjs.git`\n2. `cd cdk-nextjs`\n3. `pnpm i && pnpm compile && pnpm build`\n\nThis project uses Projen, so make sure to not edit [Projen](https://projen.io/) created files and only edit .projenrc.ts.\n\n## FAQ\n\nQ: How does this compare to [cdk-nextjs-standalone](https://github.com/jetbridge/cdk-nextjs) or [OpenNext](https://opennext.js.org)?<br/>\nA: cdk-nextjs builds on Next.js's official [Deployment Adapter](https://nextjs.org/docs/app/guides/deployment-adapters) API and runs requests through [`@next/routing`](https://www.npmjs.com/package/@next/routing), the routing library Next.js publishes for platform adapters. Next.js tells cdk-nextjs what it built, and routing follows the same rules as `next start`. Nothing re-implements Next.js's router or patches its server. The few Next.js internals cdk-nextjs does load (the image optimizer and static file server) are loaded as they are, not modified. This keeps upgrades cheap and breaking changes rare. cdk-nextjs is tested against Next.js's own end-to-end test suite; [harness-coverage.md](docs/harness-coverage.md) lists the cases that differ and why.\n\nQ: Why does cdk-nextjs depend upon Next.js v16.3 or higher?\nA: cdk-nextjs builds through the public [Adapter API](https://nextjs.org/docs/app/api-reference/config/next-config-js/adapterPath), and 16.3 is the first version whose build output carries everything it reads (middleware matchers and per-file asset hashes). 16.2 also added the [Image Optimization Caching](https://nextjs.org/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath#image-optimization-caching) it relies on. The runtime bundles `@next/routing` at the version it was tested against (see `package.json`), and newer Next.js 16 releases are expected to work.\n\nQ: How does cdk-nextjs support caching in Next.js?<br/>\nA: See [Caching Guide](./docs/caching-guide.md)\n\nQ: How customizable is the `cdk-nextjs` package for different use cases?<br/>\nA: The `cdk-nextjs` package offers deep customization through _prop-based_ overrides. These can be accessed in the construct props, allowing you to override settings like VPC configurations, CloudFront distribution, and ECS/Fargate setup. For example, you can modify `nextjsBuildProps` to customize the build process or use `nextjsDistributionProps` to adjust how CloudFront handles caching and routing. This level of control makes it easy to adapt the infrastructure to your application’s specific performance, networking, or deployment needs.\n\nQ: How can I use a custom domain with `cdk-nextjs`?<br/>\nA: See [low-cost example](./examples/low-cost/app.ts).\n\nQ: What is difference between `NextjsGlobalFunctionsProps.overrides.nextjsDistribution` and `NextjsGlobalFunctionsProps.overrides.nextjsGlobalFunctions.nextjsDistributionProps`<br/>\nA: `NextjsGlobalFunctionsProps.overrides.nextjsDistribution` allows you to customize any construct's props _within_ `NextjsDistribution` and is likely what you want whereas `NextjsGlobalFunctionsProps.overrides.nextjsGlobalFunctions.nextjsDistributionProps` allows you to customize the props passed into the construct: `NextjsDistribution`. This principle also applies to other similarly named overrides.\n\nQ: How can I `cdk bootstrap --cloudformation-execution-policies ...` my AWS Account with limited permissions for cdk-nextjs to deploy?<br />\nA: See [docs/cdk-nextjs-cfn-exec-policy.json](./docs/cdk-nextjs-cfn-exec-policy.json). Note, this IAM Policy is scoped to all cdk-nextjs constructs so you can remove services if you know the construct you're using doesn't use that service.\n\n## Acknowledgements\n\nThis construct was built on the shoulders of giants. Thank you to the contributors of [cdk-nextjs-standalone](https://github.com/jetbridge/cdk-nextjs) and [OpenNext](https://opennext.js.org).\n\n## 🥂 Thanks Contributors\n\nThank you for helping other developers deploy Next.js apps on AWS\n\n<a href=\"https://github.com/cdklabs/cdk-nextjs/graphs/contributors\">\n  <img src=\"https://contrib.rocks/image?repo=cdklabs/cdk-nextjs\" />\n</a>\n"
+    "markdown": "![Version](https://img.shields.io/github/v/release/cdklabs/cdk-nextjs)\n[![npm version](https://img.shields.io/npm/v/cdk-nextjs.svg?style=flat-square)](https://www.npmjs.org/package/cdk-nextjs)\n![License](https://img.shields.io/github/license/cdklabs/cdk-nextjs)\n\n# CDK Next.js Construct Library\n\n<!--BEGIN STABILITY BANNER-->\n\n---\n\n![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)\n\n> The APIs of higher level constructs in this module are experimental and under active development.\n> They are subject to non-backward compatible changes or removal in any future version. These are\n> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be\n> announced in the release notes. This means that while you may use them, you may need to update\n> your source code when upgrading to a newer version of this package.\n\n---\n\n<!--END STABILITY BANNER-->\n\nDeploy [Next.js](https://nextjs.org/) apps on [AWS](https://aws.amazon.com/) with the [AWS CDK](https://aws.amazon.com/cdk/).\n\n## Features\n\n- Supports all features of Next.js App and Pages Router for [Node.js Runtime](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes#nodejs-runtime).\n- Choose your AWS architecture for Next.js with the supported constructs: `NextjsGlobalFunctions`, `NextjsGlobalContainers`, `NextjsRegionalContainers`, `NextjsRegionalFunctions`.\n- Global Content Delivery Network (CDN) built with [Amazon CloudFront](https://aws.amazon.com/cloudfront/) to deliver content with low latency and high transfer speeds.\n- Serverless functions powered by [AWS Lambda](https://aws.amazon.com/lambda/) or serverless containers powered by [AWS Fargate](https://aws.amazon.com/fargate/).\n- Static assets (JS, CSS, public folder) are stored and served from [Amazon Simple Storage Service (S3)](https://aws.amazon.com/s3/) for all constructs (except `NextjsRegionalContainers`) to decrease latency and reduce compute costs by serving directly from S3.\n- [Optimized images](https://nextjs.org/docs/pages/building-your-application/optimizing/images), [data cache](https://nextjs.org/docs/app/building-your-application/caching#data-cache), [full route cache](https://nextjs.org/docs/app/building-your-application/caching#full-route-cache) and [`'use cache: remote'`](https://nextjs.org/docs/app/api-reference/directives/use-cache-remote) are shared across compute with [Amazon Simple Storage Service (S3)](https://aws.amazon.com/s3/) with supporting metadata in [Amazon DynamoDB](https://aws.amazon.com/dynamodb), and `revalidateTag`/`revalidatePath` reach plain [`'use cache'`](https://nextjs.org/docs/app/api-reference/directives/use-cache) on every instance. See [`'use cache'` and `'use cache: remote'`](#use-cache-and-use-cache-remote).\n- Customize every construct via `overrides`.\n- AWS security and operational best practices are utilized, guided by [cdk-nag](https://github.com/cdklabs/cdk-nag).\n- First class support for [monorepos](https://monorepo.tools/).\n- [Bring Your Own Resources](#bring-your-own-resources) — import existing AWS resources (CloudFront distributions, ECS clusters, ALBs, S3 buckets, DynamoDB tables).\n- [AWS GovCloud (US)](https://aws.amazon.com/govcloud-us) compatible with `NextjsRegionalFunctions` and `NextjsRegionalContainers`.\n\n## Why\n\nThe simplest path to deploy Next.js is on [Vercel](https://vercel.com/) - the Platform-as-a-Service company behind Next.js. However, deploying to Vercel can be expensive and some developers want all of their workloads running _directly_ on AWS. Developers can deploy Next.js on AWS through [AWS Amplify Hosting](https://docs.aws.amazon.com/amplify/latest/userguide/ssr-Amplifysupport.html), but Amplify does not support all Next.js features and manages AWS resources for you so they cannot be customized. If Amplify meets your requirements we recommend you use it, but if you want to use all Next.js features or want more visibility into the AWS resources then this construct is for you.\n\n## Design Principles\n\n- Integrate through Next.js's official interfaces. Build on the [Deployment Adapter](https://nextjs.org/docs/app/guides/deployment-adapters) API and [`@next/routing`](https://www.npmjs.com/package/@next/routing) rather than Next.js internals, so new Next.js versions rarely break this construct. Where no public interface exists yet, the dependency is listed in [Next.js private APIs](docs/nextjs-private-apis.md).\n- Security first.\n- One architecture does not fit all.\n- Enable customization everywhere.\n\n## Prerequisites\n\n- Next.js app running v16.3 or higher (`next build` fails on older versions). If you don't have one yet - follow [these steps](https://nextjs.org/docs/getting-started) to create one.\n- [AWS Cloud Development Kit](https://docs.aws.amazon.com/cdk/v2/guide/home.html) app either in the same package or separate package. cdk-nextjs supports monorepos.\n- A Docker compatible container engine, but **only** for `NextjsGlobalContainers` and `NextjsRegionalContainers` - we recommend [Rancher Desktop](https://rancherdesktop.io/) with dockerd (moby). The two Functions types deploy zip Lambdas and need no container engine.\n- [Node.js](https://nodejs.org/en) v24 (or LTS)\n\n## Getting Started\n\n1. Install `cdk-nextjs` in the package(s) containing your CDK and Next.js app with `npm i cdk-nextjs`\n2. Deploy your Next.js app to AWS: `cdk deploy`. Make sure you have [AWS credentials](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-configure.html) configured.\n3. Visit URL printed in terminal (CloudFormation Output) to view your Next.js app!\n\nNo `next.config` change is needed: cdk-nextjs runs `next build` itself, and sets [`NEXT_ADAPTER_PATH`](https://nextjs.org/docs/app/api-reference/config/next-config-js/adapterPath) on that build so Next.js loads cdk-nextjs's [Deployment Adapter](https://nextjs.org/docs/app/guides/deployment-adapters).\n\n### Registering the adapter yourself\n\nSet `adapterPath` in `next.config` in three cases. An explicit `adapterPath` always wins over `NEXT_ADAPTER_PATH`, so this is also how you pin a specific adapter.\n\n- **cdk-nextjs isn't running your build** — `skipBuild: true`, or you build in CI and hand the output to CDK.\n- **cdk-nextjs isn't a dependency of the Next.js app**, only of the CDK app. cdk-nextjs resolves the adapter from your app's directory, so it can't find it in that layout.\n- **cdk-nextjs is linked from outside your project root** — a `link:`/`file:` dependency on a checkout elsewhere on disk, as this repo's own examples use. The symlink resolves out of the project, and the adapter derives its cache handler path from its own location, so Next.js gets a `cacheHandler` outside `turbopack.root` and Turbopack rejects it. Setting `adapterPath` fixes this because the build resolves it, after whatever put the adapter in place.\n\n```ts\nimport { NextConfig } from \"next\";\n\nconst nextConfig: NextConfig = {\n  // ...\n  adapterPath: require.resolve(\"cdk-nextjs/adapter\"),\n};\n\nexport default nextConfig;\n```\n\n`require.resolve` works in an ESM `next.config.ts` too, because Next.js transpiles the config to CJS before evaluating it.\n\n### cdk-nextjs Created Dockerfile\n\nFor the Containers types, cdk-nextjs generates a Dockerfile in your Next.js app's directory. It cannot clean the file up after the image is built, so either commit it or gitignore it.\n\nEvery generated Dockerfile starts with the line `# ~~ Generated by cdk-nextjs ~~`, and cdk-nextjs **overwrites** any file carrying it — that way an upgrade that changes how the image is built does not leave a stale Dockerfile behind. To customize it, delete that first line; cdk-nextjs then leaves the file alone. If you edited a generated file without deleting the header, cdk-nextjs saves your version beside it as `<name>.Dockerfile.bak` before replacing it; gitignore that too.\n\n## Basic Example CDK App\n\n```ts\nimport { App, Stack, StackProps } from \"aws-cdk-lib\";\nimport { Construct } from \"constructs\";\nimport { NextjsGlobalFunctions } from \"cdk-nextjs\";\nimport { join } from \"node:path\";\n\nclass WebStack extends Stack {\n  constructor(scope: Construct, id: string, props?: StackProps) {\n    super(scope, id, props);\n    new NextjsGlobalFunctions(this, \"Nextjs\", {\n      buildDirectory: join(import.meta.dirname),\n    });\n  }\n}\n\nconst app = new App();\n\nnew WebStack(app, \"web-stack\");\n```\n\nSee [examples/](./examples/) for more usage examples.\n\n## Architecture\n\nHow requests are served inside the compute — the adapter runtime, and where it deliberately differs from `next start` — is in [docs/adapter-runtime.md](./docs/adapter-runtime.md).\n\n### `NextjsGlobalFunctions`\n\nArchitecture includes [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) Functions to respond to dynamic requests and [CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html) Distribution to globally serve requests and distribute static assets. Use this construct when you have unpredictable traffic, can afford occasional latency (i.e. cold starts - [typically 1% of production traffic](https://aws.amazon.com/blogs/compute/operating-lambda-performance-optimization-part-1/)), and/or want the most granular pricing model. ([code](./src/root-constructs/nextjs-global-functions.ts))\n\n![NextjsGlobalFunctions architecture: User to CloudFront, which serves S3 static assets and forwards to a Lambda function backed by a DynamoDB table and S3 cache bucket](https://raw.githubusercontent.com/cdklabs/cdk-nextjs/main/docs/diagrams/nextjs-global-functions.svg)\n\n### `NextjsGlobalContainers`\n\nArchitecture includes [ECS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) containers to respond to dynamic requests and [CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html) Distribution to globally serve requests and distribute static assets. Use this option when you have predictable traffic, need the lowest latency, and/or can afford a less granular pricing model. ([code](./src/root-constructs/nextjs-global-containers.ts))\n\n![NextjsGlobalContainers architecture: User to CloudFront, which serves S3 static assets and forwards to an Application Load Balancer and ECS Fargate containers in a VPC, backed by a DynamoDB table and S3 cache bucket](https://raw.githubusercontent.com/cdklabs/cdk-nextjs/main/docs/diagrams/nextjs-global-containers.svg)\n\n### `NextjsRegionalContainers`\n\nArchitecture includes [ECS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) containers to respond to dynamic requests and [Application Load Balancer](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/) to regionally serve requests. Use this options when you cannot use Amazon CloudFront (i.e. [AWS GovCloud](https://aws.amazon.com/govcloud-us/?whats-new.sort-by=item.additionalFields.postDateTime&whats-new.sort-order=desc)). ([code](./src/root-constructs/nextjs-regional-containers.ts#L41))\n\n![NextjsRegionalContainers architecture: User to an Application Load Balancer and ECS Fargate containers in a VPC, backed by a DynamoDB table and S3 cache bucket](https://raw.githubusercontent.com/cdklabs/cdk-nextjs/main/docs/diagrams/nextjs-regional-containers.svg)\n\n### `NextjsRegionalFunctions`\n\nArchitecture includes [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) Functions to respond to dynamic requests and [API Gateway REST API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html) to regionally serve requests and distribute static assets. Use this options when you cannot use Amazon CloudFront (i.e. [AWS GovCloud](https://aws.amazon.com/govcloud-us/?whats-new.sort-by=item.additionalFields.postDateTime&whats-new.sort-order=desc)). ([code](./src/root-constructs/nextjs-regional-functions.ts))\n\n![NextjsRegionalFunctions architecture: User to an API Gateway REST API, which serves S3 static assets and forwards to a Lambda function backed by a DynamoDB table and S3 cache bucket](https://raw.githubusercontent.com/cdklabs/cdk-nextjs/main/docs/diagrams/nextjs-regional-functions.svg)\n\n## Configuration\n\nThe variables below are read at runtime by the cache handler inside your deployed\nLambda functions or containers. Set them on the compute through `overrides`:\n\n```ts\n// NextjsGlobalFunctions / NextjsRegionalFunctions\noverrides: {\n  nextjsFunctions: {\n    functionProps: { environment: { CDK_NEXTJS_MEMORY_CACHE_TTL_MS: \"0\" } },\n  },\n},\n\n// NextjsGlobalContainers / NextjsRegionalContainers\noverrides: {\n  nextjsContainers: {\n    taskImageOptions: { environment: { CDK_NEXTJS_MEMORY_CACHE_TTL_MS: \"0\" } },\n  },\n},\n```\n\nValues you pass are merged over the ones the construct sets, so the same mechanism\noverrides the [infrastructure variables](#infrastructure-configuration) too.\n\n### Cache Configuration\n\n#### `CDK_NEXTJS_MEMORY_CACHE_TTL_MS`\n\nTime to live in milliseconds for in-memory cache entries. After this duration, entries expire and are removed from the cache.\n\n**Note**: Every memory hit is checked against the tag revalidation markers, so an entry revalidated on another instance is not served from memory. A tag's marker is read from DynamoDB only on its first use and a rolling re-read every few minutes; in between, revalidations arrive through the revalidation log (one `Query` per [`CDK_NEXTJS_TAG_REFRESH_MS`](#cdk_nextjs_tag_refresh_ms)). Memory still saves the S3 read and body parse. Set this to `0` to disable the memory cache entirely (all requests will fall through to S3 + DynamoDB).\n\n**Default**: `3600000` (1 hour)\n\n**Examples**:\n\n- Short TTL (5 minutes): `300000` - for frequently changing data\n- Medium TTL (1 hour): `3600000` - balanced between freshness and performance\n- Long TTL (24 hours): `86400000` - for mostly static content\n\n**Trade-offs**:\n\n- Lower values: More cache misses, fresher data, higher S3/DynamoDB costs\n- Higher values: Fewer cache misses, better performance, but longer stale data windows\n\n#### `CDK_NEXTJS_MEMORY_CACHE_MAX_ENTRIES`\n\nMaximum number of cache entries to store in memory. When this limit is reached, the least recently used (LRU) entry is evicted.\n\n**Default**: `1000`\n\n**Examples**:\n\n- Small cache: `100` - minimal memory footprint for simple apps\n- Medium cache: `1000` - good balance for typical applications\n- Large cache: `10000` - for high-traffic apps with many unique pages\n\n**Trade-offs**:\n\n- Lower values: Less memory usage, more cache evictions\n- Higher values: More memory usage, fewer cache evictions, better hit rates\n\n**Memory considerations**: Each entry stores the full cache value (HTML, JSON, etc.). A typical page cache might be 10-100KB, so 1000 entries ≈ 10-100MB of memory. Consider your compute environment's memory limits (Lambda: 128MB-10GB, Fargate: 512MB-30GB) and size accordingly.\n\n### `'use cache'` and `'use cache: remote'`\n\nThe adapter registers two [`cacheHandlers`](https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandlers)\nnext to the `cacheHandler` it already sets, unless your `next.config` names a\nhandler of its own for either:\n\n| Directive             | `cacheHandlers` name | Stored                           | Tags                    |\n| --------------------- | -------------------- | -------------------------------- | ----------------------- |\n| `'use cache'`         | `default`            | each instance's memory           | DynamoDB, all instances |\n| `'use cache: remote'` | `remote`             | S3 cache bucket, memory in front | DynamoDB, all instances |\n\n- **`'use cache: remote'`** is shared: an entry any instance generates is the one\n  every instance serves, until it expires or a tag is revalidated. Use it for\n  results you don't want each Lambda instance or task to compute on its own. It\n  costs an S3 `GetObject` the first time an instance reads an entry, and a\n  `PutObject` per generated entry. Objects live under\n  `<buildId>/_use-cache/` in the cache bucket and are pruned with the build.\n- **`'use cache'`** stays per instance, as Next.js intends — but `revalidateTag`,\n  `updateTag` and `revalidatePath` now expire it on every instance, not only the\n  one that ran them. Next.js's built-in handler keeps tags in process memory, so\n  before this every other instance kept serving the revalidated value, even into\n  pages re-rendered because of that revalidation.\n\nBoth read the same per-tag marker rows in the revalidation table that ISR and\nthe data cache use. A tag an instance has not seen yet — an entry read from S3,\na page's implicit `revalidatePath` tags — is read from its marker before it is\ntrusted, once per instance.\n\nAfter that, an instance doesn't re-read the tags it tracks to learn what\nchanged. Each `revalidateTag`/`updateTag` also writes a row to a revalidation\nlog in the same table (`pk = <buildId>#log`, expiring after 15 minutes through\nthe table's `ttl` attribute). At most once per\n[`CDK_NEXTJS_TAG_REFRESH_MS`](#cdk_nextjs_tag_refresh_ms),\neach instance sends one DynamoDB `Query` for the rows written since its last\none and applies those for tags it tracks. So a revalidation on another instance\nis honored within that window (1 second by default), and on the instance that ran\nit immediately. An idle instance's query costs 0.5 RCU a second, where\nre-reading up to 1000 tracked tags cost about 500. Each tag's marker is still\nre-read every 7.5 to 10 minutes, a few each second rather than all at once (about 8\nRCU a second at the most an instance tracks, 10,000 tags). After a gap the log\nmay no longer cover (a Lambda frozen between invocations, a run of failed\nqueries), an instance forgets its tracked markers and reads each again as it's\nneeded. ISR and the data cache share the same copy of the markers, so one\n`revalidateTag` writes each tag's rows once and one `Query` serves them all.\n\nIf you pass your own `revalidationTable`, enabling TTL on its `ttl` attribute is\nrecommended. Without it the log rows (about 100 bytes per revalidated tag) are\nkept until a deploy replaces their build, whose post-deploy step deletes them.\n\nTwo instances that generate the same `'use cache: remote'` entry at the same\nmoment both store it; each serves its own copy until that copy's `revalidate`\ntime, after which S3's is used.\n\n#### `CDK_NEXTJS_TAG_REFRESH_MS`\n\nHow often, at most, in milliseconds, an instance asks the revalidation log what\nother instances revalidated, for `'use cache'`, ISR and the data cache alike. A\n`revalidateTag` elsewhere goes unseen for up to about the window plus a second\n(2 s by default), since `'use cache'` doesn't wait for the answer - and for\nlonger while a query is slow or failing, or for a page render that started\ninside the window, which reads what the instance knew when it began. It's one DynamoDB `Query`,\nhowever many tags the instance tracks, shared by every request on the instance\nduring the window. `0` asks before every cache check, and waits for the answer\n(`'use cache'` only while the instance holds an entry the answer could expire).\nOtherwise `'use cache'` reads don't wait for it, and it applies from the\ninstance's next request. The exception is an instance that hasn't caught up for\nover a second past the window (it sat idle or was frozen): it waits for the\nanswer, before rendering the page for a page request. `'use cache: remote'`\nalways waits.\n\n**Default**: `1000`\n\n#### `CDK_NEXTJS_USE_CACHE_MEMORY_BYTES`\n\nSize bound, in bytes, of each handler's in-memory store: all of `'use cache'`,\nand the memory tier in front of S3 for `'use cache: remote'`. Least recently used\nentries are evicted first.\n\n**Default**: `52428800` (50 MB, Next.js's own default)\n\n### Infrastructure Configuration\n\nThe construct sets these itself and they typically don't need to be modified:\n\n#### `CDK_NEXTJS_BUILD_ID`\n\nUnique identifier for the Next.js build. Used for cache isolation between deployments.\n\n#### `CDK_NEXTJS_CACHE_BUCKET_NAME`\n\nS3 bucket name for storing cached data (optimized images, data cache, full route cache, `'use cache: remote'`).\n\n#### `CDK_NEXTJS_REVALIDATION_TABLE_NAME`\n\nDynamoDB table name for tracking cache revalidations and tag-to-cache-key mappings.\n\n#### `DEBUG`\n\nNot set by default. Set it to `cdk-nextjs:*` to enable debug logs. This is especially useful to see cache handler activity.\n\n### `next.config.js` options cdk-nextjs reads\n\nBoth are read out of your build, so you set them in one place — your app — and the\ninfrastructure follows.\n\n#### `basePath`\n\nBecomes the S3 key prefix for static assets and the prefix on every CloudFront\ncache behavior. See [Resource Isolation](#resource-isolation); the `basePath`\nprop only exists to be explicit about it.\n\n#### `assetPrefix`\n\n- **A path** (`assetPrefix: \"/cdn\"`) — Next.js emits bundle URLs as\n  `/cdn/_next/static/...`, on top of `basePath` rather than under it, while the\n  objects stay in S3 under `<basePath>/_next/static/...`. `NextjsGlobalFunctions`\n  and `NextjsGlobalContainers` add a cache behavior for\n  `<assetPrefix>/_next/static*` pointing at the assets bucket, with a CloudFront\n  Function that rewrites the prefix back to the S3 keys. It costs one of the 25\n  cache behaviors cdk-nextjs budgets for you. **Not supported on\n  `NextjsRegionalFunctions` or `NextjsRegionalContainers`** — nothing there maps\n  the prefix back, so bundles would 404; synth warns if your app sets one.\n- **An absolute URL** (`assetPrefix: \"https://cdn.example.com\"`) — names an origin\n  cdk-nextjs doesn't serve, so nothing is added, on any construct. Point that host\n  at the assets bucket yourself, including the `basePath` prefix the objects are\n  stored under.\n- **An absolute URL with a path** (`assetPrefix: \"https://cdn.example.com/cdn\"`) —\n  its path is treated exactly like the path case above, because `next build`\n  compiles a `/cdn/_next/:path+` rewrite of its own: `next start` serves bundles\n  under that path too, so the Global constructs answer there as well. Useful when\n  that host is a second domain on the same distribution.\n\n## Splitting a Large App Across Functions\n\nOnly for `NextjsGlobalFunctions` and `NextjsRegionalFunctions`, and only if you\nneed it. AWS Lambda caps a function's unzipped code at 250 MB. If your app\nexceeds it, cdk-nextjs fails at synth with the measured size and points you here:\n\n```\nFunction group \"default\" is 274 MB unzipped, over Lambda's 250 MB limit. Use the\n`functionGroups` prop to package routes into separate functions. Note that\nsplitting only removes route-local code — anything reachable from a shared layout\nor the `next` runtime is in every group.\n```\n\n`functionGroups` declares which routes get their own Lambda. Everything you do\nnot name stays on the `default` function:\n\n```ts\nnew NextjsGlobalFunctions(this, \"Nextjs\", {\n  buildDirectory: join(import.meta.dirname, \"..\", \"web\"),\n  functionGroups: [\n    { name: \"reports\", routes: [\"/dashboard/reports/**\"] },\n    { name: \"admin\", routes: [\"/admin\", \"/admin/**\", \"/settings\"] },\n  ],\n});\n```\n\nEach group becomes one Lambda function containing only the routes it owns (plus\nthe framework closure every function needs), and one CloudFront behavior — or API\nGateway resource, for `NextjsRegionalFunctions` — per pattern.\n\n**Route patterns** are either an exact path (`/settings`) or a subtree\n(`/admin/**`). A subtree owns what is _under_ it, not the path itself:\n`/admin/**` does not claim `/admin`. To own a page and everything under it, list\nboth, as the example above does: `[\"/admin\", \"/admin/**\"]`. Where two groups\ncould both match, the longest pattern wins, so `/api/**` and `/api/reports/**`\ncan coexist in different groups. Dynamic segments (`/blog/[slug]`), route group\nsegments (`/(marketing)/about`), `/`, and `/**` are rejected at synth —\nCloudFront matches literal path prefixes and cannot express them. `/index` is\naccepted for an App Router `app/index/page.tsx`, but not for a Pages Router home\npage, which is the same file as `/`.\n\n**What is routed for you.** Patterns decide which _files_ a group packages; the\nedge then has to send every URL those files serve to that group. cdk-nextjs\nderives these without extra patterns:\n\n- A Pages Router page's data URL, `/_next/data/<buildId>/<page>.json`. The\n  behavior carries the literal build ID, so it changes on every deploy; a\n  client still on the previous build falls through to the `default` function,\n  which answers 404, and the Next.js client reloads the page.\n- The `trailingSlash` form of an exact pattern (`/pricing/`). CloudFront gets a\n  behavior for it; on `NextjsRegionalFunctions` none is needed, because API\n  Gateway already routes `/pricing/` to the `/pricing` resource.\n- The parent of an optional catch-all. `/shop/**` moving\n  `app/shop/[[...slug]]/page.tsx` also routes `/shop`, which the same file\n  serves. Do not add `/shop` yourself: it matches no route and is rejected.\n- An [interception route](https://nextjs.org/docs/app/api-reference/file-conventions/intercepting-routes)\n  is packaged with the group that owns the URL it intercepts, not by its own\n  path: `app/feed/(..)photo/[id]` follows `/photo/[id]`, because a soft\n  navigation requests `/photo/1` and Next.js rewrites it in whichever function\n  receives it.\n\n**What synth rejects.** After assigning routes, cdk-nextjs replays the\nCloudFront behaviors over every URL each file serves and fails when one would\nreach a function without its file, naming the file, the URL and the pattern to\nadd. That covers:\n\n- A file behind several templates that a pattern only partly covers — root\n  params (`app/[locale]/page.tsx` prerendered as `/en` and `/de`) grouped with\n  `/en` alone. A dynamic first segment can never be routed, so such a file stays\n  in `default`.\n- An intercepted URL space split between groups (`/photo/[id]` in one,\n  `/photo/1` in another), since the intercepting file cannot be in both.\n- A `next.config` rewrite whose source reaches one group and whose destination\n  file is in another: rewrites run inside the function that received the\n  request. Only rewrites with a literal destination are checked.\n- A group pattern that duplicates a top-level `public/` entry's behavior\n  (`public/docs/` and `/docs/**`), or sits under one (`/docs/guide/**`), which\n  would send the group's routes to S3.\n\nNot checked, because it is only known at request time: **a middleware\n`NextResponse.rewrite()`** to a route in another group reaches the function that\nreceived the original URL, which lacks the route's file. It answers 404 (or a\n308 to the canonical URL when only the case differs) and logs a warning naming\nthe group that owns the route. Keep a middleware rewrite's source and\ndestination in the same group. The same goes\nfor a `next.config` rewrite whose destination is built from its parameters\n(`/b/:slug` → `/blog/:slug`), and for a dynamic segment of a `default` route\nthat overlaps a group's literal path (`/[section]/intro` against `/docs/**`).\nLikewise **a Pages Router `res.revalidate()`** renders the page in the function\nthat called it, so it can only revalidate pages in its own group; the error\nnames the group that owns the page. Use `revalidatePath()` or `revalidateTag()`\nacross groups. And **an `<Image>` whose `src` is a route in another group**\n(`/api/avatar/42` under an `/api/**` group) can't be optimized: `/_next/image`\nruns in the `default` function, which fetches a local source that isn't a\n`public/` or `_next/static` file by running its route in-process, and it doesn't\ncarry that route, so the image request fails. Keep image-serving routes in\n`default`, or point `src` at a `public/` file or a remote URL.\n\n**What splitting does and does not save.** Every function ships the same `next`\nruntime closure, so splitting only moves route-_local_ code and its dependencies.\nA group whose routes import a large library is worth extracting; splitting an app\nin half does not halve either function.\n\nNotes:\n\n- Group names must be valid CDK construct ids (letters, digits, `-`). `default`\n  is reserved.\n- A pattern that matches no route in the build is a synth error, not a silent\n  no-op — it is almost always a typo.\n- Cannot be combined with `i18n`: locale-prefixed routes would need one\n  CloudFront behavior per locale per pattern.\n- Group patterns (and the routes derived from them above) count against the\n  same CloudFront behavior budget as your `public/` entries (see\n  [Limitations](#limitations)).\n- Per-group `overrides` let you size each function independently:\n  `{ name: \"reports\", routes: [...], overrides: { functionProps: { memorySize: 2048 } } }`.\n\n## Running Code on Every Viewer Request\n\n`NextjsGlobalFunctions` and `NextjsGlobalContainers` take a\n`viewerRequestFunctionCode` prop: CloudFront Function code that runs first on\nevery request, on every behavior cdk-nextjs adds — pages, API routes,\n`_next/image`, `_next/static` and `public/` files alike. It's the place for a\ngate the whole site has to pass, such as HTTP Basic auth before launch:\n\n```ts\nimport { FunctionCode, KeyValueStore } from \"aws-cdk-lib/aws-cloudfront\";\n\nconst credentials = new KeyValueStore(this, \"Credentials\");\nnew NextjsGlobalFunctions(this, \"Nextjs\", {\n  buildDirectory: join(import.meta.dirname),\n  viewerRequestKeyValueStore: credentials,\n  viewerRequestFunctionCode: FunctionCode.fromInline(`\n    import cf from \"cloudfront\";\n    const kvs = cf.kvs();\n    async function viewerRequest(event) {\n      const auth = event.request.headers.authorization;\n      try {\n        if (auth && auth.value === \"Basic \" + (await kvs.get(\"basic-auth\"))) {\n          // verified: don't pass the site's credentials on to the origin\n          delete event.request.headers.authorization;\n          return;\n        }\n      } catch (e) {\n        // no \"basic-auth\" key yet: stay locked\n      }\n      return {\n        statusCode: 401,\n        statusDescription: \"Unauthorized\",\n        headers: { \"www-authenticate\": { value: 'Basic realm=\"preview\"' } },\n      };\n    }\n  `),\n});\n```\n\nThen put the credentials in the store, outside the template:\n\n```sh\nKVS_ARN=... # the store's ARN\naws cloudfront-keyvaluestore put-key --kvs-arn \"$KVS_ARN\" \\\n  --key basic-auth --value \"$(printf 'user:pass' | base64 | tr -d '\\n')\" \\\n  --if-match \"$(aws cloudfront-keyvaluestore describe-key-value-store \\\n    --kvs-arn \"$KVS_ARN\" --query ETag --output text)\"\n```\n\nThe code must define `viewerRequest(event)`, as a function (`async` or not)\nor a `var`/`let`/`const`. It's a CloudFront Function handler in all but name:\nreturn a response to answer the viewer, or the request (or nothing) to carry\non.\n\nWhy not a function of your own on viewer-request? CloudFront allows one per\nevent type per behavior, and on Global Functions cdk-nextjs's own one\noverwrites `X-Forwarded-Host` and redirects repeated slashes. So your code is\nspliced into that function, ahead of cdk-nextjs's logic, which still runs after\nit, so your code can't undo the `X-Forwarded-Host` overwrite. Middleware can't\ndo this instead: on Global Functions CloudFront signs the request to the\nFunction URL with the `Authorization` header, and static assets never reach the\nserver at all.\n\n- cdk-nextjs's CloudFront Functions run on `cloudfront-js-2.0`, so your code\n  can be `async`, and `import cf from \"cloudfront\"` works when it comes first,\n  as it does above.\n- `viewerRequestKeyValueStore` is associated with every viewer-request function\n  your code is copied into (up to three, one per kind of behavior), so\n  `cf.kvs()` reads it with no ID wherever the code runs. Credentials written\n  inline in the code instead end up in the CloudFormation template.\n- The combined function, cdk-nextjs's code included, must fit CloudFront's\n  10 KB limit; synth fails if it doesn't (or warns, if the code contains a\n  CDK token, whose size isn't known until deploy).\n- Your code shares the file with cdk-nextjs's `handler`, so it can't use the\n  name `handler` at all, even in a comment or a string; synth refuses it.\n- A viewer-request association in `overrides.*BehaviorOptions.functionAssociations`\n  on a behavior this covers is refused at synth; put that logic in\n  `viewerRequestFunctionCode` instead. So is\n  `overrides.distributionProps.defaultBehavior` without a `basePath`, since it\n  would replace the default behavior the code runs on; customize it through\n  `overrides.dynamicBehaviorOptions`.\n- A bring-your-own `distribution`'s default behavior is yours, so it isn't\n  covered. Only the behaviors cdk-nextjs adds are; under a `basePath`, those\n  include the ones that stand in for the default behavior.\n\n## Bring Your Own Resources\n\ncdk-nextjs supports importing existing AWS resources instead of creating new ones. This is especially useful for per-branch (MR/PR) environments where you deploy shared infrastructure (VPC, ECS cluster, ALB) once and spin up lightweight branch stacks that reuse it.\n\n### Supported Resources\n\n| Resource                    | Prop                 | Available On                                         |\n| --------------------------- | -------------------- | ---------------------------------------------------- |\n| S3 Cache Bucket             | `cacheBucket`        | All constructs                                       |\n| DynamoDB Revalidation Table | `revalidationTable`  | All constructs                                       |\n| S3 Static Assets Bucket     | `staticAssetsBucket` | All constructs                                       |\n| CloudFront Distribution     | `distribution`       | `NextjsGlobalFunctions`, `NextjsGlobalContainers`    |\n| ECS Cluster                 | `ecsCluster`         | `NextjsGlobalContainers`, `NextjsRegionalContainers` |\n| ALB                         | `alb`                | `NextjsGlobalContainers`, `NextjsRegionalContainers` |\n\n### Resource Isolation\n\n- **Cache bucket and DynamoDB table** must be dedicated to one deployment. Sharing either between deployments (branches, stages, apps) is not supported: each deploy's post-deploy step prunes every cache object and revalidation entry that isn't from its own current build, so deploying one branch wipes the others' caches. Buckets and tables are cheap, so give each deployment its own, or leave `cacheBucket`/`revalidationTable` unset and let cdk-nextjs create them (they are removed with the stack).\n- **Static assets bucket** can be shared, but only between deployments with different `basePath`s, which become their S3 key prefixes. Pruning only looks at `<basePath>/_next/`, so it never touches another prefix. Two deployments under the same prefix (for example two subdomain previews both 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. `NextjsGlobalFunctions` and `NextjsGlobalContainers` read the `basePath` out of your Next.js build and use it as the S3 key prefix, since CloudFront serves assets from S3 by request path and the two can't differ. Set the `basePath` prop only if you want to be explicit about it; a value that disagrees with your app's fails at synth. Each deployment also adds an ownership tag per static asset upload (1 to 3, by whether the build has `public/` files and service workers) to a bucket created in your CDK app; an imported bucket gets none. S3 allows 50 tags per bucket, so such a bucket holds at least 16 deployments.\n\n### Shared ALB and `removeAutoCreatedListener()`\n\n`ApplicationLoadBalancedFargateService` always creates a listener on port 80 — there is no opt-out. When you import an ALB that already has a listener on that port, the duplicate causes a deployment failure. Since CDK doesn't expose a way to prevent this, `removeAutoCreatedListener()` surgically removes the generated CloudFormation resources: the `CfnListener`, its security group ingress rule, rebuilds the ECS service `DependsOn` without the deleted listener, and removes auto-created `CfnOutput` resources:\n\n```ts\nconst nextjs = new NextjsRegionalContainers(this, \"Nextjs\", {\n  // ...\n  alb: sharedAlb,\n  ecsCluster: sharedCluster,\n});\nnextjs.nextjsContainers.removeAutoCreatedListener();\n```\n\n### Examples\n\nSee [examples/bring-your-own/](./examples/bring-your-own/) for a complete deployable example with a shared VPC, ECS cluster, and ALB, per-branch host-header routing, and a cache bucket, revalidation table, and static assets bucket per branch.\n\n## Preview Environments (Per-Branch Deployments)\n\ncdk-nextjs can deploy ephemeral preview environments per merge request (MR) or pull request (PR). The recommended approach uses subdomain-based routing (`pr-123.app.example.com`) so each preview environment runs the same Next.js build as production — no `basePath` configuration or separate builds required.\n\nSee [examples/bring-your-own/](./examples/bring-your-own/) for a fully deployable example using `NextjsRegionalContainers` with a shared VPC, ALB, and ECS Cluster (connected via SSM Parameter Store), and S3 buckets and a DynamoDB table owned by each branch stack.\n\nEach preview environment needs its own cache bucket and revalidation table (see [Resource Isolation](#resource-isolation)). Since every preview serves the same build at the root, give each its own static assets bucket too. Leaving `cacheBucket`, `revalidationTable`, and `staticAssetsBucket` unset does this: cdk-nextjs creates them in the branch stack and deletes them when it's torn down.\n\n### Prerequisites\n\n- Wildcard DNS record: `*.app.example.com` → your routing layer (ALB, CloudFront, API Gateway)\n- Wildcard ACM certificate: `*.app.example.com`\n\n### Per-Architecture Recommendations\n\n#### `NextjsGlobalContainers` and `NextjsRegionalContainers` (ALB-based)\n\nSubdomain routing via ALB host-based listener rules. This is the fastest and simplest approach. For `NextjsGlobalContainers`, CloudFront forwards the `Host` header to the ALB origin, so the ALB handles all branch routing — no CloudFront changes needed per branch.\n\nSee [examples/bring-your-own/](./examples/bring-your-own/) for the full implementation.\n\n#### `NextjsRegionalFunctions` (API Gateway)\n\nSubdomain routing via API Gateway custom domain mappings.\n\n1. Per branch, deploy a cdk-nextjs stack that creates its own API Gateway, Lambda function, S3 buckets, and DynamoDB table\n2. Create an API Gateway custom domain (`pr-123.app.example.com`) mapped to the branch's API stage\n3. Tear down the branch stack on MR close\n\n#### `NextjsGlobalFunctions` (Lambda + CloudFront)\n\nRequires a separate cdk-nextjs stack per branch, each with its own CloudFront distribution. CloudFront cannot route to different Lambda Function URL origins based on the `Host` header — origin selection is determined by cache behavior path patterns, not request headers.\n\n1. Per branch, deploy a full cdk-nextjs stack that creates its own CloudFront distribution, Lambda function, S3 buckets, and DynamoDB table\n2. Point `pr-123.app.example.com` DNS to the branch's CloudFront distribution\n3. Tear down the branch stack on MR close\n\nNote: CloudFront distributions take several minutes to create/update, so this architecture has the slowest preview environment spin-up time.\n\n## Limitations\n\n- If using `NextjsGlobalFunctions` or `NextjsGlobalContainers` (which use CloudFront), each top level file/directory in `public/` takes a CloudFront cache behavior, and a distribution's default quota is 75 behaviors (cdk-nextjs uses 3 to 6 itself). We recommend you put all of your public assets into one top level directory (i.e. public/static) so you don't reach this limit. If you raise the quota for your account, set `maxCacheBehaviors` on the distribution props (`overrides.nextjsGlobalFunctions.nextjsDistributionProps`, or the Containers equivalent) to match. The synth check only counts the behaviors cdk-nextjs adds, so if you pass your own `distribution` (or add behaviors through `overrides.nextjsDistribution.distributionProps`), lower `maxCacheBehaviors` by the behaviors it already has. See [CloudFront Quotas](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html) for more information.\n- If using `NextjsGlobalFunctions` or `NextjsGlobalContainers`, on-demand revalidation ([revalidatePath](https://nextjs.org/docs/app/api-reference/functions/revalidatePath), [revalidateTag](https://nextjs.org/docs/app/api-reference/functions/revalidateTag)) creates the CloudFront invalidations for you (so does the Pages Router's `res.revalidate()`, for the page's HTML and `_next/data` copies), but [invalidations](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html) are eventually consistent: until one completes (usually seconds, occasionally minutes), some edge locations can still serve the previous copy.\n  - **Burst limit.** CloudFront allows 15 wildcard invalidation paths in progress per distribution, and each page cdk-nextjs invalidates is one wildcard path (`/blog*`). Next.js sends every `revalidatePath`/`revalidateTag` from one request as a single call, one invalidation per cache-life profile, however many pages it covers. A Pages Router `res.revalidate()` sends one invalidation per call, and a page regenerated after a stale-while-revalidate `revalidateTag(tag, profile)` sends one more when it lands. When the quota is full, cdk-nextjs retries the request as a single `/*` (a colder edge, never a stale page). If that is also rejected, it logs `Failed to create CloudFront invalidation` and the page stays stale at the edge until its `s-maxage` expires.\n  - **For bulk updates** (a CMS webhook touching many pages), call `revalidateTag` with a tag the pages share, or `revalidatePath` for each page within one request, rather than looping `res.revalidate()`. If you need to know when invalidations are dropped, add a CloudWatch Logs metric filter on that log line.\n- If using `NextjsGlobalFunctions`, a client-supplied `Authorization` header does not reach your app: CloudFront signs each request to the Lambda Function URL with SigV4, which uses that header. Send credentials under a different name (e.g. `x-authorization`) and read that header in your app. cdk-nextjs does not rename it for you — it no longer uses [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter), so `AWS_LWA_AUTHORIZATION_SOURCE` no longer applies.\n- If using `NextjsGlobalFunctions`, a `POST` or `PUT` with a request body must carry an `x-amz-content-sha256` header holding the hex SHA-256 of that body. This is [AWS behavior](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-lambda.html), not a cdk-nextjs choice: CloudFront signs the origin request to the Lambda Function URL with SigV4 but does not hash the body, and Lambda rejects an unsigned payload with `403 InvalidSignatureException`. Requests from your own pages are handled for you — cdk-nextjs injects a `fetch`/`XMLHttpRequest` wrapper into the client bundle that adds the header, so server actions, route handlers, `fetch` and `XMLHttpRequest` from the browser work untouched, whatever the body type. The exception is a native `<form method=\"post\">` submitted before the page hydrates (a server action form without JavaScript, or clicked before the bundle loads): the browser sends it, not the wrapper, so it has no header and gets the 403. **Anything that is not that browser bundle has to add the header itself**: `curl`, a mobile app, a webhook provider, another service calling your API routes. Server-to-server callers can compute it with the AWS SDK's `Sha256`, or with `crypto.createHash(\"sha256\").update(body).digest(\"hex\")`. The other three deployment types are unaffected.\n- If using `NextjsGlobalFunctions`, a `HEAD` request is answered with `content-length: 0`, whatever length your handler declares. This is Lambda Function URL behavior: the same runtime's declared length reaches the client through API Gateway (`NextjsRegionalFunctions`) and from an ALB, with or without CloudFront in front (the two Containers types).\n- Group patterns declared via [`functionGroups`](#splitting-a-large-app-across-functions) also count against the CloudFront behavior limit above.\n- If using `NextjsRegionalFunctions` without a custom domain, API Gateway REST APIs require a [stage name](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-stages.html) (default: `/prod`) to be specified. This causes links to pages and static assets to break because they're not prefixed with the stage name. You can work around this issue by specifying [basePath](https://nextjs.org/docs/app/api-reference/config/next-config-js/basePath) in next.config.js as your stage name — leave the construct's `basePath` prop unset when you do, since API Gateway strips the stage before matching resources. API Gateway strips the stage from the path it passes to Lambda; cdk-nextjs puts it back for an app whose `basePath` starts with it, reading the stage off each request, so no middleware is needed and a renamed stage needs no configuration. Mapping a custom domain at the root avoids all of this — see [examples/regional-functions/README.md](./examples/regional-functions/README.md#with-a-custom-domain-no-stage-workarounds).\n\n## Additional Security Recommendations\n\nThis construct by default implements all AWS security best practices that a CDK construct library reasonably can considering cost and complexity. Below are additional security practices we recommend you implement within your CDK app. Please see them below:\n\n- [VPC Flow Logs](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html). See [examples/](./examples) for sample implementation.\n- [Scan ECR Images For Vulnerabilities](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-scanning.html).\n- For `NextjsGlobalFunctions` and `NextjsGlobalContainers`, [CloudFront Access Logs](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/AccessLogs.html). See [examples/](./examples) for sample implementation.\n- For `NextjsGlobalContainers` and `NextjsRegionalContainers`, use [ALB HTTPS Listener](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-https-listener.html)\n- If using `NextjsGlobalContainers` and `NextjsRegionalContainers`, enable `ReadonlyRootFilesystem`. This will remove ability to use Static On-Demand feature of Next.js so it's not enabled by default, but is recommended for security.\n\n## Estimated Costs\n\n### Assumptions\n\nThe following basic assumptions were used for a typical medium Next.js app. See [docs/usage.xlsx](./docs/usage.xlsx) for detailed assumptions and usage per construct type that you can plug into AWS Pricing Calculator.\n\n| Metric                                                       | Value |\n| ------------------------------------------------------------ | ----- |\n| Monthly Active Users                                         | 1K    |\n| Pages Visited Per Month Per User                             | 100   |\n| Avg Request Size                                             | 50KB  |\n| Static Requests Per Page (js, css, etc)                      | 15    |\n| Static Requests Cache Hit %                                  | 50%   |\n| Static Assets Size                                           | 10GB  |\n| Dynamic Requests Per Page (document, optimized images, etc.) | 5     |\n| Dynamic Cache Read %                                         | 50%   |\n| Dynamic Cache Write %                                        | 5%    |\n| Dynamic Cache Data Size                                      | 10GB  |\n| Average Dynamic Cache Request Size                           | 100KB |\n| Dynamic Revalidate Tag %                                     | 1%    |\n\nMore Details:\n\n- Assume ARM architecture for compute\n- AWS Region: us-east-1\n- Excludes charges related to: CloudWatch Logs, NAT Gateway data processing\n\n### NextjsGlobalFunctions\n\n[AWS Pricing Calculator](https://calculator.aws/#/estimate?id=23611f6fea87ef05d5fe87c33135ddde43b17a98)\n\n| Service    | Monthly Usage                                  | Estimated Monthly Cost (USD) |\n| ---------- | ---------------------------------------------- | ---------------------------- |\n| Lambda     | 500K requests, 2 GB memory, 150ms avg duration | $0.00 (Always Free Tier)     |\n| CloudFront | 2M requests, 100 GB transfer to internet       | $0.00 (Always Free Tier)     |\n| S3         | 20 GB storage, 1M GET, 250K PUT requests       | $2.11                        |\n| DynamoDB   | 10 GB storage, 5K Reads, 5K Writes             | $2.50                        |\n| Total      |                                                | $8.09                        |\n\n### NextjsGlobalContainers\n\n[AWS Pricing Calculator](https://calculator.aws/#/estimate?id=02f0073e612d1eee2a7ccace2c636adc5f0acab7)\n\n| Service     | Monthly Usage                            | Estimated Monthly Cost (USD) |\n| ----------- | ---------------------------------------- | ---------------------------- |\n| ECS Fargate | 1 task (1 vCPU, 2 GB)                    | $28.44                       |\n| ALB         | 1 LB, 1.04GB/hr, 5.79 conn/sec           | $22.50                       |\n| CloudFront  | 2M requests, 100 GB transfer to internet | $0.00 (Always Free Tier)     |\n| S3          | 20 GB storage, 1M GET, 250K PUT requests | $2.11                        |\n| DynamoDB    | 10 GB storage, 5K Reads, 5K Writes       | $2.50                        |\n| VPC         | NAT Gateway, 2 AZs                       | $65.70                       |\n| Total       |                                          | $121.25                      |\n\n### NextjsRegionalContainers\n\n[AWS Pricing Calculator](https://calculator.aws/#/estimate?id=e214abe60eb4e24fc5866d07ef4355393261af3c)\n\n| Service     | Monthly Usage                              | Estimated Monthly Cost (USD) |\n| ----------- | ------------------------------------------ | ---------------------------- |\n| ECS Fargate | 1 task (2 vCPU, 4 GB), always on           | $28.44                       |\n| ALB         | 1 LB, 4.17 GB/hr, 23.15 conn/sec           | $40.78                       |\n| S3          | 10 GB storage, 250K GET, 250K PUT requests | $1.58                        |\n| DynamoDB    | 10 GB storage, 5K Reads, 5K Writes         | $2.50                        |\n| VPC         | NAT Gateway, 2 AZs                         | $65.70                       |\n| Total       |                                            | $139.00                      |\n\n### NextjsRegionalFunctions\n\n[AWS Pricing Calculator](https://calculator.aws/#/estimate?id=60da38c7993c1baeee2fee4bd19ba6441608bb15)\n\n| Service     | Monthly Usage                                  | Estimated Monthly Cost (USD) |\n| ----------- | ---------------------------------------------- | ---------------------------- |\n| Lambda      | 500K requests, 2 GB memory, 150ms avg duration | $0.00 (Always Free Tier)     |\n| API Gateway | 2M requests                                    | $7.00                        |\n| S3          | 10 GB storage, 250K GET, 250K PUT requests     | $1.58                        |\n| DynamoDB    | 10 GB storage, 5K Reads, 5K Writes             | $2.50                        |\n| Total       |                                                | $11.08                       |\n\n## Performance\n\nMeasured with [k6](https://grafana.com/docs/k6/latest/) from EC2 in us-east-1, the region of the stacks under test (one load generator per stack), against a small benchmark app ([`examples/bench-app`](./examples/bench-app)) that makes no calls outside its own stack. Functions run the default 2048 MB Lambda functions. Containers run the default 1 vCPU / 2 GB Fargate tasks, with CPU autoscaling from 2 to 10 tasks added (the default is one task and no autoscaling). Methodology, caveats, and how to reproduce the numbers: [`examples/load-tests`](./examples/load-tests).\n\nWhat each route measures:\n\n- `static-asset`, `static`, `image`: CloudFront's cache on the Global constructs, and the construct itself on the Regional ones.\n- `isr`: the cache until the page is stale (10 s), then a background revalidation through the S3 + DynamoDB cache.\n- `ssr`, `stream`, `rsc`, `api`: the construct's compute on every request, on every construct.\n\n<!-- tables generated by `pnpm report` in examples/load-tests -->\n\n| Construct                  | `ssr` at 10 req/s | `ssr` at 50 req/s                         | `ssr` capacity | `isr` capacity | Cold start p50 |\n| -------------------------- | ----------------- | ----------------------------------------- | -------------- | -------------- | -------------- |\n| `NextjsGlobalFunctions`    | 36 / 103          | 33 / 84                                   | ≥ 6560 req/s   | ≥ 6560 req/s   | 1390 ms        |\n| `NextjsGlobalContainers`   | 19 / 44           | 18 / 219                                  | 194 req/s      | ≥ 6400 req/s   | –              |\n| `NextjsRegionalContainers` | 22 / 172          | 1972 / 39536 ⚠️ 0.54% errors, 76% dropped | 675 req/s      | ≥ 6075 req/s   | –              |\n| `NextjsRegionalFunctions`  | 32 / 114          | 30 / 103                                  | ≥ 6560 req/s   | ≥ 6560 req/s   | 1380 ms        |\n\n_Latency is p50 / p99 in ms, with every route loaded at that rate at once. Capacity is the highest rate sustained with p99 under 1000 ms and under 1% errors._\n\nWhat this means for choosing one:\n\n- **Functions constructs scale with no sizing.** Both held at least 6,560 req/s of SSR, the load generator's limit, at the same latency as at 10 req/s. The cost is a cold start of about 1.4 s on a new execution environment.\n- **Containers constructs are fastest per request but need sizing.** Two 1 vCPU tasks served SSR at 19–22 ms p50 against Lambda's ~30 ms, but tasks take minutes to add. Past capacity they don't degrade gradually: tasks too busy to answer the ALB health check are replaced, which leaves fewer tasks for the same load. Leave headroom.\n- **CloudFront carries the Global constructs' cached traffic.** Prerendered pages, ISR hits, images and assets were answered at the edge in 2–3 ms at every rate. On the Regional constructs every request reaches the construct: `NextjsRegionalContainers` serves assets and image optimization from the same tasks, so 50 req/s on every route at once (400 req/s) is already more than two tasks handle.\n- **Cached pages scale on every construct.** ISR hits held at least 6,000 req/s on all four: at the edge on the Global constructs, and through the S3 + DynamoDB cache on the Regional ones, where each instance holds a tag's revalidation marker for a second (`CDK_NEXTJS_TAG_REFRESH_MS`, see the [Caching Guide](./docs/caching-guide.md)).\n\n<details>\n<summary><code>NextjsGlobalFunctions</code></summary>\n\nLatency per route, p50 / p99 in ms, with every route at the same rate at once:\n\n| Route         | 10 req/s  | 50 req/s  | 250 req/s | 1000 req/s | CDN hits |\n| ------------- | --------- | --------- | --------- | ---------- | -------- |\n| static-asset  | 2.1 / 4.8 | 2.1 / 4.7 | 2.0 / 4.9 | 2.1 / 11   | 100%     |\n| static        | 3.3 / 7.5 | 3.2 / 6.8 | 3.1 / 7.3 | 3.2 / 13   | 100%     |\n| isr           | 3.3 / 7.4 | 3.3 / 7.7 | 3.2 / 7.2 | 3.2 / 12   | 100%     |\n| ssr           | 36 / 103  | 33 / 84   | 31 / 86   | 29 / 73    | 0%       |\n| stream        | 233 / 268 | 230 / 261 | 228 / 259 | 226 / 252  | 0%       |\n| stream (TTFB) | 32 / 89   | 29 / 66   | 27 / 65   | 25 / 57    |          |\n| rsc           | 32 / 67   | 28 / 61   | 27 / 60   | 25 / 52    | 0%       |\n| api           | 29 / 79   | 26 / 55   | 24 / 61   | 23 / 47    | 0%       |\n| image         | 3.2 / 6.3 | 3.1 / 6.8 | 3.1 / 7.0 | 3.1 / 12   | 100%     |\n\nCapacity: `isr` ≥ 6560 req/s, `ssr` ≥ 6560 req/s.\n\nCold start, time to first byte of `/ssr` on a new execution environment: p50 1390 ms, p90 1451 ms (warm: 84 ms).\n\nBrowser, p75 in ms, under 50 req/s per route:\n\n| Route  | LCP | TTFB | Client-side navigation |\n| ------ | --- | ---- | ---------------------- |\n| static | 76  | 13   | 15                     |\n| ssr    | 80  | 39   | 53                     |\n| isr    | 52  | 8.7  | 12                     |\n| stream | 64  | 34   | 38                     |\n| image  | 52  | 6.7  | 10                     |\n\n</details>\n\n<details>\n<summary><code>NextjsGlobalContainers</code></summary>\n\nLatency per route, p50 / p99 in ms, with every route at the same rate at once:\n\n| Route         | 10 req/s  | 50 req/s  | CDN hits |\n| ------------- | --------- | --------- | -------- |\n| static-asset  | 1.4 / 3.9 | 1.5 / 3.7 | 100%     |\n| static        | 1.9 / 4.8 | 1.8 / 3.7 | 100%     |\n| isr           | 2.0 / 4.4 | 1.7 / 4.0 | 100%     |\n| ssr           | 19 / 44   | 18 / 219  | 0%       |\n| stream        | 217 / 242 | 217 / 359 | 0%       |\n| stream (TTFB) | 17 / 45   | 16 / 207  |          |\n| rsc           | 12 / 26   | 12 / 86   | 0%       |\n| api           | 11 / 23   | 10 / 81   | 0%       |\n| image         | 2.0 / 4.7 | 1.7 / 4.1 | 100%     |\n\nCapacity: `isr` ≥ 6400 req/s, `ssr` 194 req/s.\n\nBrowser, p75 in ms, under 50 req/s per route:\n\n| Route  | LCP | TTFB | Client-side navigation |\n| ------ | --- | ---- | ---------------------- |\n| static | 88  | 12   | 17                     |\n| ssr    | 80  | 26   | 39                     |\n| isr    | 56  | 6.1  | 13                     |\n| stream | 64  | 20   | 25                     |\n| image  | 52  | 5.4  | 11                     |\n\n</details>\n\n<details>\n<summary><code>NextjsRegionalContainers</code></summary>\n\nLatency per route, p50 / p99 in ms, with every route at the same rate at once:\n\n| Route         | 10 req/s  | 50 req/s                                  | CDN hits |\n| ------------- | --------- | ----------------------------------------- | -------- |\n| static-asset  | 18 / 159  | 1698 / 28824 ⚠️ 0.40% errors, 72% dropped | no CDN   |\n| static        | 41 / 163  | 916 / 28298 ⚠️ 0.46% errors, 66% dropped  | no CDN   |\n| isr           | 40 / 169  | 697 / 27146 ⚠️ 0.36% errors, 57% dropped  | no CDN   |\n| ssr           | 22 / 172  | 1972 / 39536 ⚠️ 0.54% errors, 76% dropped | no CDN   |\n| stream        | 221 / 354 | 1909 / 27423 ⚠️ 0.44% errors, 72% dropped | no CDN   |\n| stream (TTFB) | 19 / 166  | 1881 / 27162                              |          |\n| rsc           | 9.4 / 64  | 433 / 26066 ⚠️ 0.25% errors, 39% dropped  | no CDN   |\n| api           | 6.9 / 55  | 429 / 26041 ⚠️ 0.25% errors, 38% dropped  | no CDN   |\n| image         | 140 / 440 | 1599 / 27489 ⚠️ 0.22% errors, 69% dropped | no CDN   |\n\nCapacity: `isr` ≥ 6075 req/s, `ssr` 675 req/s.\n\nBrowser, p75 in ms, under 10 req/s per route. `static` is each visit's first page: on a plain-HTTP origin, Chrome tries HTTPS first and falls back after about 3 s (HTTPS-Upgrades), which real visitors pay too. Put a certificate on the ALB to avoid it.\n\n| Route  | LCP  | TTFB | Client-side navigation |\n| ------ | ---- | ---- | ---------------------- |\n| static | 3100 | 3047 | 16                     |\n| ssr    | 68   | 14   | 27                     |\n| isr    | 88   | 43   | 13                     |\n| stream | 48   | 11   | 13                     |\n| image  | 212  | 38   | 9.6                    |\n\n</details>\n\n<details>\n<summary><code>NextjsRegionalFunctions</code></summary>\n\nLatency per route, p50 / p99 in ms, with every route at the same rate at once:\n\n| Route         | 10 req/s  | 50 req/s  | 250 req/s | 1000 req/s | CDN hits |\n| ------------- | --------- | --------- | --------- | ---------- | -------- |\n| static-asset  | 34 / 76   | 32 / 72   | 30 / 72   | 30 / 68    | no CDN   |\n| static        | 58 / 138  | 57 / 140  | 57 / 147  | 57 / 127   | no CDN   |\n| isr           | 58 / 149  | 56 / 124  | 56 / 145  | 55 / 125   | no CDN   |\n| ssr           | 32 / 114  | 30 / 103  | 29 / 115  | 29 / 98    | no CDN   |\n| stream        | 229 / 293 | 227 / 288 | 227 / 299 | 226 / 282  | no CDN   |\n| stream (TTFB) | 27 / 85   | 25 / 84   | 25 / 97   | 24 / 76    |          |\n| rsc           | 27 / 76   | 26 / 73   | 25 / 83   | 25 / 70    | no CDN   |\n| api           | 24 / 84   | 22 / 70   | 22 / 97   | 22 / 67    | no CDN   |\n| image         | 127 / 210 | 125 / 221 | 125 / 236 | 123 / 211  | no CDN   |\n\nCapacity: `isr` ≥ 6560 req/s, `ssr` ≥ 6560 req/s.\n\nCold start, time to first byte of `/ssr` on a new execution environment: p50 1380 ms, p90 1442 ms (warm: 71 ms).\n\nBrowser, p75 in ms, under 50 req/s per route:\n\n| Route  | LCP | TTFB | Client-side navigation |\n| ------ | --- | ---- | ---------------------- |\n| static | 128 | 70   | 17                     |\n| ssr    | 88  | 35   | 50                     |\n| isr    | 108 | 62   | 13                     |\n| stream | 64  | 31   | 36                     |\n| image  | 220 | 60   | 9.6                    |\n\n</details>\n\n## Guides\n\n- [Caching Guide](./docs/caching-guide.md)\n- [Pruning Guide](./docs/pruning-guide.md)\n- [Native Dependencies Guide](./docs/native-dependencies-guide.md)\n- [Next Build Output Guide](./docs/next-build-output-guide.ts)\n- [Development Guide](./docs/development-guide.ts)\n\n## Contributing\n\nSteps to build locally:\n\n1. `git clone https://github.com/cdklabs/cdk-nextjs.git`\n2. `cd cdk-nextjs`\n3. `pnpm i && pnpm compile && pnpm build`\n\nThis project uses Projen, so make sure to not edit [Projen](https://projen.io/) created files and only edit .projenrc.ts.\n\n## FAQ\n\nQ: How does this compare to [cdk-nextjs-standalone](https://github.com/jetbridge/cdk-nextjs) or [OpenNext](https://opennext.js.org)?<br/>\nA: cdk-nextjs builds on Next.js's official [Deployment Adapter](https://nextjs.org/docs/app/guides/deployment-adapters) API and runs requests through [`@next/routing`](https://www.npmjs.com/package/@next/routing), the routing library Next.js publishes for platform adapters. Next.js tells cdk-nextjs what it built, and routing follows the same rules as `next start`. Nothing re-implements Next.js's router or patches its server. The few Next.js internals cdk-nextjs does load (the image optimizer and static file server) are loaded as they are, not modified. This keeps upgrades cheap and breaking changes rare. cdk-nextjs is tested against Next.js's own end-to-end test suite; [harness-coverage.md](docs/harness-coverage.md) lists the cases that differ and why.\n\nQ: Why does cdk-nextjs depend upon Next.js v16.3 or higher?\nA: cdk-nextjs builds through the public [Adapter API](https://nextjs.org/docs/app/api-reference/config/next-config-js/adapterPath), and 16.3 is the first version whose build output carries everything it reads (middleware matchers and per-file asset hashes). 16.2 also added the [Image Optimization Caching](https://nextjs.org/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath#image-optimization-caching) it relies on. The runtime bundles `@next/routing` at the version it was tested against (see `package.json`), and newer Next.js 16 releases are expected to work.\n\nQ: How does cdk-nextjs support caching in Next.js?<br/>\nA: See [Caching Guide](./docs/caching-guide.md)\n\nQ: How customizable is the `cdk-nextjs` package for different use cases?<br/>\nA: The `cdk-nextjs` package offers deep customization through _prop-based_ overrides. These can be accessed in the construct props, allowing you to override settings like VPC configurations, CloudFront distribution, and ECS/Fargate setup. For example, you can modify `nextjsBuildProps` to customize the build process or use `nextjsDistributionProps` to adjust how CloudFront handles caching and routing. This level of control makes it easy to adapt the infrastructure to your application’s specific performance, networking, or deployment needs.\n\nQ: How can I use a custom domain with `cdk-nextjs`?<br/>\nA: See [low-cost example](./examples/low-cost/app.ts).\n\nQ: What is difference between `NextjsGlobalFunctionsProps.overrides.nextjsDistribution` and `NextjsGlobalFunctionsProps.overrides.nextjsGlobalFunctions.nextjsDistributionProps`<br/>\nA: `NextjsGlobalFunctionsProps.overrides.nextjsDistribution` allows you to customize any construct's props _within_ `NextjsDistribution` and is likely what you want whereas `NextjsGlobalFunctionsProps.overrides.nextjsGlobalFunctions.nextjsDistributionProps` allows you to customize the props passed into the construct: `NextjsDistribution`. This principle also applies to other similarly named overrides.\n\nQ: How can I `cdk bootstrap --cloudformation-execution-policies ...` my AWS Account with limited permissions for cdk-nextjs to deploy?<br />\nA: See [docs/cdk-nextjs-cfn-exec-policy.json](./docs/cdk-nextjs-cfn-exec-policy.json). Note, this IAM Policy is scoped to all cdk-nextjs constructs so you can remove services if you know the construct you're using doesn't use that service.\n\n## Acknowledgements\n\nThis construct was built on the shoulders of giants. Thank you to the contributors of [cdk-nextjs-standalone](https://github.com/jetbridge/cdk-nextjs) and [OpenNext](https://opennext.js.org).\n\n## 🥂 Thanks Contributors\n\nThank you for helping other developers deploy Next.js apps on AWS\n\n<a href=\"https://github.com/cdklabs/cdk-nextjs/graphs/contributors\">\n  <img src=\"https://contrib.rocks/image?repo=cdklabs/cdk-nextjs\" />\n</a>\n"
   },
   "repository": {
     "type": "git",
@@ -11311,7 +11311,7 @@
         },
         "locationInModule": {
           "filename": "src/nextjs-distribution.ts",
-          "line": 209
+          "line": 260
         },
         "parameters": [
           {
@@ -11337,7 +11337,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/nextjs-distribution.ts",
-        "line": 159
+        "line": 198
       },
       "name": "NextjsDistribution",
       "properties": [
@@ -11347,7 +11347,7 @@
           },
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 160
+            "line": 199
           },
           "name": "distribution",
           "type": {
@@ -11368,7 +11368,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/nextjs-distribution.ts",
-        "line": 153
+        "line": 192
       },
       "name": "NextjsDistributionFunctionGroup",
       "properties": [
@@ -11381,7 +11381,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 156
+            "line": 195
           },
           "name": "functionUrl",
           "type": {
@@ -11396,7 +11396,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 154
+            "line": 193
           },
           "name": "name",
           "type": {
@@ -11416,7 +11416,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/nextjs-distribution.ts",
-        "line": 57
+        "line": 68
       },
       "name": "NextjsDistributionOverrides",
       "properties": [
@@ -11428,7 +11428,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 58
+            "line": 69
           },
           "name": "distributionProps",
           "optional": true,
@@ -11444,7 +11444,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 62
+            "line": 73
           },
           "name": "dynamicBehaviorOptions",
           "optional": true,
@@ -11460,7 +11460,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 63
+            "line": 74
           },
           "name": "dynamicCachePolicyProps",
           "optional": true,
@@ -11476,7 +11476,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 65
+            "line": 76
           },
           "name": "dynamicFunctionUrlOriginWithOACProps",
           "optional": true,
@@ -11492,7 +11492,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 64
+            "line": 75
           },
           "name": "dynamicResponseHeadersPolicyProps",
           "optional": true,
@@ -11508,7 +11508,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 66
+            "line": 77
           },
           "name": "dynamicVpcOriginWithEndpointProps",
           "optional": true,
@@ -11524,7 +11524,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 59
+            "line": 70
           },
           "name": "imageBehaviorOptions",
           "optional": true,
@@ -11540,7 +11540,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 60
+            "line": 71
           },
           "name": "imageCachePolicyProps",
           "optional": true,
@@ -11556,7 +11556,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 61
+            "line": 72
           },
           "name": "imageResponseHeadersPolicyProps",
           "optional": true,
@@ -11572,7 +11572,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 69
+            "line": 80
           },
           "name": "s3BucketOriginProps",
           "optional": true,
@@ -11588,7 +11588,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 67
+            "line": 78
           },
           "name": "staticBehaviorOptions",
           "optional": true,
@@ -11604,7 +11604,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 68
+            "line": 79
           },
           "name": "staticResponseHeadersPolicyProps",
           "optional": true,
@@ -11625,7 +11625,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/nextjs-distribution.ts",
-        "line": 72
+        "line": 83
       },
       "name": "NextjsDistributionProps",
       "properties": [
@@ -11639,7 +11639,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 77
+            "line": 88
           },
           "name": "assetsBucket",
           "type": {
@@ -11654,7 +11654,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 115
+            "line": 126
           },
           "name": "nextjsType",
           "type": {
@@ -11670,7 +11670,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 124
+            "line": 135
           },
           "name": "publicDirEntries",
           "type": {
@@ -11693,7 +11693,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 96
+            "line": 107
           },
           "name": "assetPrefix",
           "optional": true,
@@ -11711,7 +11711,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 101
+            "line": 112
           },
           "name": "basePath",
           "optional": true,
@@ -11728,7 +11728,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 105
+            "line": 116
           },
           "name": "certificate",
           "optional": true,
@@ -11744,7 +11744,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 106
+            "line": 117
           },
           "name": "distribution",
           "optional": true,
@@ -11762,7 +11762,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 137
+            "line": 148
           },
           "name": "functionGroupBehaviors",
           "optional": true,
@@ -11785,7 +11785,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 130
+            "line": 141
           },
           "name": "functionGroups",
           "optional": true,
@@ -11807,7 +11807,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 110
+            "line": 121
           },
           "name": "functionUrl",
           "optional": true,
@@ -11824,7 +11824,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 114
+            "line": 125
           },
           "name": "loadBalancer",
           "optional": true,
@@ -11844,7 +11844,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 149
+            "line": 160
           },
           "name": "maxCacheBehaviors",
           "optional": true,
@@ -11861,13 +11861,53 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 119
+            "line": 130
           },
           "name": "overrides",
           "optional": true,
           "type": {
             "fqn": "cdk-nextjs.NextjsDistributionOverrides"
           }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- none",
+            "remarks": "It must define `viewerRequest(event)` (a function, sync or async, or a\n`var`/`let`/`const`): return a response to answer the viewer, or the\nrequest (or nothing) to carry on. It is spliced into cdk-nextjs's own\nviewer-request functions, ahead of their logic, so it may not use the\nname `handler`, and the combined function must fit CloudFront's 10 KB.\nIt runs on `cloudfront-js-2.0`, so it may be async and read\n{@link viewerRequestKeyValueStore} with `cf.kvs()`. A bring-your-own\n{@link distribution}'s default behavior isn't covered.",
+            "see": "https://github.com/cdklabs/cdk-nextjs#running-code-on-every-viewer-request",
+            "stability": "stable",
+            "summary": "CloudFront Function code run first on every viewer request, on every behavior cdk-nextjs adds, static assets included — HTTP Basic auth on a pre-launch site, geo-gating."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/nextjs-distribution.ts",
+            "line": 178
+          },
+          "name": "viewerRequestFunctionCode",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_cloudfront.FunctionCode"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- none",
+            "remarks": "Read it with `cf.kvs()`, no ID needed.",
+            "see": "https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/functions-custom-methods.html",
+            "stability": "stable",
+            "summary": "A CloudFront KeyValueStore associated with every viewer-request function {@link viewerRequestFunctionCode} is copied into (up to three, one per kind of behavior), so values it reads — Basic auth credentials, an allowlist — live outside the CloudFormation template and change without a deploy."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/nextjs-distribution.ts",
+            "line": 188
+          },
+          "name": "viewerRequestKeyValueStore",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_cloudfront.IKeyValueStore"
+          }
         }
       ],
       "symbolId": "src/nextjs-distribution:NextjsDistributionProps"
@@ -12423,7 +12463,7 @@
         },
         "locationInModule": {
           "filename": "src/root-constructs/nextjs-global-containers.ts",
-          "line": 106
+          "line": 125
         },
         "parameters": [
           {
@@ -12449,7 +12489,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-containers.ts",
-        "line": 88
+        "line": 107
       },
       "name": "NextjsGlobalContainers",
       "properties": [
@@ -12461,7 +12501,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 97
+            "line": 116
           },
           "name": "url",
           "overrides": "cdk-nextjs.NextjsBaseConstruct",
@@ -12475,7 +12515,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 89
+            "line": 108
           },
           "name": "nextjsContainers",
           "type": {
@@ -12488,7 +12528,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 90
+            "line": 109
           },
           "name": "nextjsDistribution",
           "type": {
@@ -12501,7 +12541,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 91
+            "line": 110
           },
           "name": "nextjsPostDeploy",
           "type": {
@@ -12524,7 +12564,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-containers.ts",
-        "line": 25
+        "line": 29
       },
       "name": "NextjsGlobalContainersConstructOverrides",
       "properties": [
@@ -12536,7 +12576,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 26
+            "line": 30
           },
           "name": "nextjsContainersProps",
           "optional": true,
@@ -12552,7 +12592,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 27
+            "line": 31
           },
           "name": "nextjsDistributionProps",
           "optional": true,
@@ -12578,7 +12618,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-containers.ts",
-        "line": 35
+        "line": 39
       },
       "name": "NextjsGlobalContainersOverrides",
       "properties": [
@@ -12590,7 +12630,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 37
+            "line": 41
           },
           "name": "nextjsContainers",
           "optional": true,
@@ -12606,7 +12646,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 38
+            "line": 42
           },
           "name": "nextjsDistribution",
           "optional": true,
@@ -12622,7 +12662,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 36
+            "line": 40
           },
           "name": "nextjsGlobalContainers",
           "optional": true,
@@ -12646,7 +12686,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-containers.ts",
-        "line": 41
+        "line": 45
       },
       "name": "NextjsGlobalContainersProps",
       "properties": [
@@ -12661,7 +12701,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 75
+            "line": 79
           },
           "name": "healthCheckPath",
           "type": {
@@ -12678,7 +12718,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 48
+            "line": 52
           },
           "name": "alb",
           "optional": true,
@@ -12696,7 +12736,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 53
+            "line": 57
           },
           "name": "distribution",
           "optional": true,
@@ -12714,7 +12754,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 58
+            "line": 62
           },
           "name": "ecsCluster",
           "optional": true,
@@ -12731,13 +12771,52 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 79
+            "line": 83
           },
           "name": "overrides",
           "optional": true,
           "type": {
             "fqn": "cdk-nextjs.NextjsGlobalContainersOverrides"
           }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- none",
+            "remarks": "It must define\n`viewerRequest(event)`, as a function or a `var`/`let`/`const`.",
+            "see": "NextjsDistributionProps.viewerRequestFunctionCode *",
+            "stability": "stable",
+            "summary": "CloudFront Function code run first on every viewer request, static assets included — HTTP Basic auth on a pre-launch site, say."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/root-constructs/nextjs-global-containers.ts",
+            "line": 91
+          },
+          "name": "viewerRequestFunctionCode",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_cloudfront.FunctionCode"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- none",
+            "see": "NextjsDistributionProps.viewerRequestKeyValueStore *",
+            "stability": "stable",
+            "summary": "A CloudFront KeyValueStore `viewerRequestFunctionCode` can read with `cf.kvs()`, so credentials stay out of the template."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/root-constructs/nextjs-global-containers.ts",
+            "line": 98
+          },
+          "name": "viewerRequestKeyValueStore",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_cloudfront.IKeyValueStore"
+          }
         }
       ],
       "symbolId": "src/root-constructs/nextjs-global-containers:NextjsGlobalContainersProps"
@@ -12756,7 +12835,7 @@
         },
         "locationInModule": {
           "filename": "src/root-constructs/nextjs-global-functions.ts",
-          "line": 92
+          "line": 111
         },
         "parameters": [
           {
@@ -12782,7 +12861,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-functions.ts",
-        "line": 74
+        "line": 93
       },
       "name": "NextjsGlobalFunctions",
       "properties": [
@@ -12794,7 +12873,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 83
+            "line": 102
           },
           "name": "url",
           "overrides": "cdk-nextjs.NextjsBaseConstruct",
@@ -12808,7 +12887,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 76
+            "line": 95
           },
           "name": "nextjsDistribution",
           "type": {
@@ -12821,7 +12900,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 75
+            "line": 94
           },
           "name": "nextjsFunctions",
           "type": {
@@ -12834,7 +12913,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 77
+            "line": 96
           },
           "name": "nextjsPostDeploy",
           "type": {
@@ -12857,7 +12936,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-functions.ts",
-        "line": 28
+        "line": 32
       },
       "name": "NextjsGlobalFunctionsConstructOverrides",
       "properties": [
@@ -12869,7 +12948,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 29
+            "line": 33
           },
           "name": "nextjsDistributionProps",
           "optional": true,
@@ -12895,7 +12974,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-functions.ts",
-        "line": 37
+        "line": 41
       },
       "name": "NextjsGlobalFunctionsOverrides",
       "properties": [
@@ -12907,7 +12986,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 40
+            "line": 44
           },
           "name": "nextjsDistribution",
           "optional": true,
@@ -12923,7 +13002,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 39
+            "line": 43
           },
           "name": "nextjsFunctions",
           "optional": true,
@@ -12939,7 +13018,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 38
+            "line": 42
           },
           "name": "nextjsGlobalFunctions",
           "optional": true,
@@ -12963,7 +13042,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-functions.ts",
-        "line": 43
+        "line": 47
       },
       "name": "NextjsGlobalFunctionsProps",
       "properties": [
@@ -12977,7 +13056,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 48
+            "line": 52
           },
           "name": "distribution",
           "optional": true,
@@ -12997,7 +13076,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 61
+            "line": 65
           },
           "name": "functionGroups",
           "optional": true,
@@ -13019,13 +13098,52 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 65
+            "line": 69
           },
           "name": "overrides",
           "optional": true,
           "type": {
             "fqn": "cdk-nextjs.NextjsGlobalFunctionsOverrides"
           }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- none",
+            "remarks": "It must define\n`viewerRequest(event)`, as a function or a `var`/`let`/`const`.",
+            "see": "NextjsDistributionProps.viewerRequestFunctionCode *",
+            "stability": "stable",
+            "summary": "CloudFront Function code run first on every viewer request, static assets included — HTTP Basic auth on a pre-launch site, say."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/root-constructs/nextjs-global-functions.ts",
+            "line": 77
+          },
+          "name": "viewerRequestFunctionCode",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_cloudfront.FunctionCode"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- none",
+            "see": "NextjsDistributionProps.viewerRequestKeyValueStore *",
+            "stability": "stable",
+            "summary": "A CloudFront KeyValueStore `viewerRequestFunctionCode` can read with `cf.kvs()`, so credentials stay out of the template."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/root-constructs/nextjs-global-functions.ts",
+            "line": 84
+          },
+          "name": "viewerRequestKeyValueStore",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_cloudfront.IKeyValueStore"
+          }
         }
       ],
       "symbolId": "src/root-constructs/nextjs-global-functions:NextjsGlobalFunctionsProps"
@@ -18558,7 +18676,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 66
+            "line": 87
           },
           "name": "assetPrefix",
           "optional": true,
@@ -18576,7 +18694,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 81
+            "line": 102
           },
           "name": "assetsBucket",
           "optional": true,
@@ -18594,7 +18712,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 46
+            "line": 67
           },
           "name": "basePath",
           "optional": true,
@@ -18611,7 +18729,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 39
+            "line": 60
           },
           "name": "certificate",
           "optional": true,
@@ -18627,7 +18745,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 34
+            "line": 55
           },
           "name": "distribution",
           "optional": true,
@@ -18644,7 +18762,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 30
+            "line": 51
           },
           "name": "functionUrl",
           "optional": true,
@@ -18661,7 +18779,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 25
+            "line": 46
           },
           "name": "loadBalancer",
           "optional": true,
@@ -18680,7 +18798,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 20
+            "line": 41
           },
           "name": "maxCacheBehaviors",
           "optional": true,
@@ -18696,7 +18814,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 75
+            "line": 96
           },
           "name": "nextjsType",
           "optional": true,
@@ -18713,7 +18831,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 71
+            "line": 92
           },
           "name": "publicDirEntries",
           "optional": true,
@@ -18725,6 +18843,44 @@
               "kind": "array"
             }
           }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- none",
+            "remarks": "It must define `viewerRequest(event)` (a function, sync or async, or a\n`var`/`let`/`const`): return a response to answer the viewer, or the\nrequest (or nothing) to carry on. It is spliced into cdk-nextjs's own\nviewer-request functions, ahead of their logic, so it may not use the\nname `handler`, and the combined function must fit CloudFront's 10 KB.\nIt runs on `cloudfront-js-2.0`, so it may be async and read\n{@link viewerRequestKeyValueStore} with `cf.kvs()`. A bring-your-own\n{@link distribution}'s default behavior isn't covered.",
+            "stability": "stable",
+            "summary": "CloudFront Function code run first on every viewer request, on every behavior cdk-nextjs adds, static assets included — HTTP Basic auth on a pre-launch site, geo-gating."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
+            "line": 29
+          },
+          "name": "viewerRequestFunctionCode",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_cloudfront.FunctionCode"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- none",
+            "remarks": "Read it with `cf.kvs()`, no ID needed.",
+            "stability": "stable",
+            "summary": "A CloudFront KeyValueStore associated with every viewer-request function {@link viewerRequestFunctionCode} is copied into (up to three, one per kind of behavior), so values it reads — Basic auth credentials, an allowlist — live outside the CloudFormation template and change without a deploy."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
+            "line": 15
+          },
+          "name": "viewerRequestKeyValueStore",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_cloudfront.IKeyValueStore"
+          }
         }
       ],
       "symbolId": "src/generated-structs/OptionalNextjsDistributionProps:OptionalNextjsDistributionProps"
@@ -19929,6 +20085,6 @@
       "symbolId": "src/nextjs-build/nextjs-build:PublicDirEntry"
     }
   },
-  "version": "0.7.12",
-  "fingerprint": "IKtjSb7QgT6alsb7At2pCRFLa7qU/0B4Qq6HYygyQ24="
+  "version": "0.7.13",
+  "fingerprint": "6ATOojt9o1v/PGHf4L8nYMKFUDATsQfbiMHtqZRzNxg="
 }