cdk-nextjs 0.5.16 → 0.6.0

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), and [full route cache](https://nextjs.org/docs/app/building-your-application/caching#full-route-cache) 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).\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.2 or higher. 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- Docker compatible container engine - we recommend [Rancher Desktop](https://rancherdesktop.io/) with dockerd (moby).\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. Update next.config.ts to include `adapterPath`:\n\n```ts\nimport { NextConfig } from \"next\";\n\nconst nextConfig: NextConfig = {\n  // ...\n  adapterPath: import.meta.resolve(\"cdk-nextjs/adapter\"), // for ESM\n  // adapterPath: require.resolve(\"cdk-nextjs/adapter\"), // for CJS\n};\n\nexport default nextConfig;\n```\n\n3. 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.\n4. Visit URL printed in terminal (CloudFormation Output) to view your Next.js app!\n\n### cdk-nextjs Created Dockerfile\n\ncdk-nextjs will generate a Dockerfile in your Next.js app's directory. cdk-nextjs does not have the ability to clean up the Dockerfile after the container is built so you can either add it to source control or gitignore it. When detectd, cdk-nextjs will not overwrite this Dockerfile so you're free to customize it.\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      healthCheckPath: \"/api/health\",\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\ncdk-nextjs supports configuration via environment variables. These are automatically set by the construct during deployment, but you can override them for custom behavior.\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**Important**: Due to the distributed nature of compute instances (Lambda functions, ECS Fargate containers, etc.), the memory cache by default provides eventual consistency across instances. Tag revalidations will clear the cache on the instance that processes the revalidation, but other instances may serve stale data until their cache entries expire. If you require strong consistency, set this to `0` to disable the memory cache (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### Infrastructure Configuration\n\nThe following environment variables are automatically set by the construct and 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).\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\nSet to `cdk-nextjs:*` to set debug logs. This is especially useful to see cache handler activity.\n\n## Architecture\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- Treat Next.js as black box. Minimize reliance on Next.js internal APIs to reduce chance of incompatibility between this construct and future versions of Next.js.\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 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** are isolated by `buildId` prefix. Multiple branches safely share one bucket/table with no conflicts.\n- **Static assets bucket** — Next.js includes content hashes in static asset filenames, so different branches deploying the same file will produce identical content. It's safe for branches to overwrite each other. If you're already using `basePath` for routing, assets will naturally be prefixed by it.\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 shared infrastructure and per-branch host-header routing.\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 ALB, ECS Cluster, S3 buckets, and DynamoDB table — connected via SSM Parameter Store.\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. Deploy shared infrastructure once: S3 buckets, DynamoDB table\n2. Per branch, deploy a cdk-nextjs stack that imports shared resources and creates its own API Gateway\n3. Create an API Gateway custom domain (`pr-123.app.example.com`) mapped to the branch's API stage\n4. 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. Deploy shared infrastructure once: S3 buckets, DynamoDB table\n2. Per branch, deploy a full cdk-nextjs stack that imports shared resources (`cacheBucket`, `revalidationTable`, `staticAssetsBucket`) but creates its own CloudFront distribution and Lambda function\n3. Point `pr-123.app.example.com` DNS to the branch's CloudFront distribution\n4. 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), the number of top level files/directories cannot exceed 25, the max number of behaviors a CloudFront Distribution supports. 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. See [CloudFront Quotas](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html) for more information.\n- If using `NextjsGlobalFunctions`, when [revalidating data in Next.js](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation) (i.e. [revalidatePath](https://nextjs.org/docs/app/api-reference/functions/revalidatePath)), the CloudFront Cache will still hold stale data. You'll need to use AWS SDK JS V3 [CreateInvalidationCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-cloudfront/Class/CreateInvalidationCommand/) to manually invalidate the path in CloudFront. See more [here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html).\n- If using `NextjsGlobalFunctions`, setting an Authorization header won't work by default because of Lambda Function URL with IAM Auth is already using the Authorization header. You can use the `AWS_LWA_AUTHORIZATION_SOURCE` environment variable of [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter) to set an alternative Authorization header in the client which will then be set to the Authorization header when it reaches your app.\n- `NextjsRegionalFunctions` streaming depends on whether your server Lambda supports response streaming (e.g. [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter)'s `AWS_LWA_INVOKE_MODE`) — override `overrides.nextjsApi.dynamicIntegrationProps.responseTransferMode` to `BUFFERED` if it doesn't, otherwise API Gateway returns a 500 for every request.\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. Additionally, you'll need to add middleware logic to rewrite requests to include the stage name because API Gateway does not include the stage name in the path passed to Lambda. See [examples/app-playground/middleware.ts](./examples/app-playground/middleware.ts).\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\n[Artillery Playwright](https://www.artillery.io/docs/reference/engines/playwright#overview) app playground example load tests results with 1K concurrent users. Reproduce with `pnpm test-fargate:lg` within `examples/load-tests`.\n\n### NextjsGlobalFunctions\n\n<details>\n<summary>`NextjsGlobalFunctions` Performance Details</summary>\n\n```bash\nbrowser.page.TTFB.https://abc123.cloudfront.net/isr:\n  min: ......................................................................... 6.3\n  max: ......................................................................... 5017.4\n  mean: ........................................................................ 11.5\n  median: ...................................................................... 10.3\n  p95: ......................................................................... 15.6\n  p99: ......................................................................... 22.9\nbrowser.page.TTFB.https://abc123.cloudfront.net/isr/1:\n  min: ......................................................................... 3.2\n  max: ......................................................................... 560.6\n  mean: ........................................................................ 9.4\n  median: ...................................................................... 5.4\n  p95: ......................................................................... 11.1\n  p99: ......................................................................... 162.4\nbrowser.page.TTFB.https://abc123.cloudfront.net/isr/2:\n  min: ......................................................................... 3.1\n  max: ......................................................................... 1511.9\n  mean: ........................................................................ 9.2\n  median: ...................................................................... 5.2\n  p95: ......................................................................... 10.7\n  p99: ......................................................................... 149.9\nbrowser.page.TTFB.https://abc123.cloudfront.net/isr/3:\n  min: ......................................................................... 3.4\n  max: ......................................................................... 131.1\n  mean: ........................................................................ 7.1\n  median: ...................................................................... 5.3\n  p95: ......................................................................... 10.1\n  p99: ......................................................................... 64.7\nbrowser.page.TTFB.https://abc123.cloudfront.net/ssg:\n  min: ......................................................................... 6.4\n  max: ......................................................................... 5015.1\n  mean: ........................................................................ 11.5\n  median: ...................................................................... 10.3\n  p95: ......................................................................... 15.6\n  p99: ......................................................................... 23.3\nbrowser.page.TTFB.https://abc123.cloudfront.net/ssg/3:\n  min: ......................................................................... 2.9\n  max: ......................................................................... 98\n  mean: ........................................................................ 5.1\n  median: ...................................................................... 4.6\n  p95: ......................................................................... 8.2\n  p99: ......................................................................... 12.8\nbrowser.page.TTFB.https://abc123.cloudfront.net/ssr:\n  min: ......................................................................... 6.4\n  max: ......................................................................... 5018.6\n  mean: ........................................................................ 11.3\n  median: ...................................................................... 10.3\n  p95: ......................................................................... 15.6\n  p99: ......................................................................... 23.3\nbrowser.page.TTFB.https://abc123.cloudfront.net/ssr/2:\n  min: ......................................................................... 83.4\n  max: ......................................................................... 150.7\n  mean: ........................................................................ 119\n  median: ...................................................................... 111.1\n  p95: ......................................................................... 147\n  p99: ......................................................................... 147\nbrowser.page.TTFB.https://abc123.cloudfront.net/streaming:\n  min: ......................................................................... 6.4\n  max: ......................................................................... 5015.2\n  mean: ........................................................................ 11.8\n  median: ...................................................................... 10.3\n  p95: ......................................................................... 15.6\n  p99: ......................................................................... 23.3\n```\n\n</details>\n\n![1K concurrent users](./docs/1k-concurrent-users-executions.png)\n\n### NextjsGlobalContainers\n\n<details>\n<summary>`NextjsGlobalContainers` Performance Details</summary>\n\n```bash\nTODO\n```\n\n</details>\n\n### NextjsRegionalContainers\n\n<details>\n<summary>`NextjsRegionalContainers` Performance Details</summary>\n\n```bash\nTODO\n```\n\n### NextjsRegionalFunctions\n\n<details>\n<summary>`NextjsRegionalFunctions` Performance Details</summary>\n\n```bash\nTODO\n```\n\n</details>\n\n## Guides\n\n- [Caching Guide](./docs/caching-guide.md)\n- [Pruning Guide](./docs/pruning-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)?<br/>\nA: cdk-nextjs-standalone relies on [OpenNext](https://github.com/sst/open-next). OpenNext injects custom code to interact with private Next.js APIs. While OpenNext is able to make some optimizations that are great for serverless environments, this comes at an increase maintenance cost and increased chances for breaking changes. A goal of cdk-nextjs is to customize Next.js as little as possible to reduce the maintenance burden and decrease chances of breaking changes.\n\nQ: Why does cdk-nextjs depend upon Next.js v16.2 or higher?\nA: This version is required for [Image Optimization Caching](https://nextjs.org/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath#image-optimization-caching) so that cdk-nextjs can depend upon public Next.js API.\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: Why use container image for `NextjsGlobalFunctions`?<br />\nA: Read [The case for containers on Lambda (with benchmarks)](https://aaronstuyvenberg.com/posts/containers-on-lambda). Also, we depend upon [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter) to transform lambda event payloads into HTTP requests that Next.js expects.\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 [open-next](https://github.com/sst/open-next).\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), and [full route cache](https://nextjs.org/docs/app/building-your-application/caching#full-route-cache) 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).\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.2 or higher. 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- Docker compatible container engine - we recommend [Rancher Desktop](https://rancherdesktop.io/) with dockerd (moby).\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. Update next.config.ts to include `adapterPath`:\n\n```ts\nimport { NextConfig } from \"next\";\n\nconst nextConfig: NextConfig = {\n  // ...\n  adapterPath: import.meta.resolve(\"cdk-nextjs/adapter\"), // for ESM\n  // adapterPath: require.resolve(\"cdk-nextjs/adapter\"), // for CJS\n};\n\nexport default nextConfig;\n```\n\n3. 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.\n4. Visit URL printed in terminal (CloudFormation Output) to view your Next.js app!\n\n### cdk-nextjs Created Dockerfile\n\ncdk-nextjs will generate a Dockerfile in your Next.js app's directory. cdk-nextjs does not have the ability to clean up the Dockerfile after the container is built so you can either add it to source control or gitignore it. When detectd, cdk-nextjs will not overwrite this Dockerfile so you're free to customize it.\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      healthCheckPath: \"/api/health\",\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\ncdk-nextjs supports configuration via environment variables. These are automatically set by the construct during deployment, but you can override them for custom behavior.\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**Important**: Due to the distributed nature of compute instances (Lambda functions, ECS Fargate containers, etc.), the memory cache by default provides eventual consistency across instances. Tag revalidations will clear the cache on the instance that processes the revalidation, but other instances may serve stale data until their cache entries expire. If you require strong consistency, set this to `0` to disable the memory cache (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### Infrastructure Configuration\n\nThe following environment variables are automatically set by the construct and 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).\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\nSet to `cdk-nextjs:*` to set debug logs. This is especially useful to see cache handler activity.\n\n## Architecture\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- Treat Next.js as black box. Minimize reliance on Next.js internal APIs to reduce chance of incompatibility between this construct and future versions of Next.js.\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 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** are isolated by `buildId` prefix. Multiple branches safely share one bucket/table with no conflicts.\n- **Static assets bucket** — Next.js includes content hashes in static asset filenames, so different branches deploying the same file will produce identical content. It's safe for branches to overwrite each other. If you're already using `basePath` for routing, assets will naturally be prefixed by it — `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.\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 shared infrastructure and per-branch host-header routing.\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 ALB, ECS Cluster, S3 buckets, and DynamoDB table — connected via SSM Parameter Store.\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. Deploy shared infrastructure once: S3 buckets, DynamoDB table\n2. Per branch, deploy a cdk-nextjs stack that imports shared resources and creates its own API Gateway\n3. Create an API Gateway custom domain (`pr-123.app.example.com`) mapped to the branch's API stage\n4. 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. Deploy shared infrastructure once: S3 buckets, DynamoDB table\n2. Per branch, deploy a full cdk-nextjs stack that imports shared resources (`cacheBucket`, `revalidationTable`, `staticAssetsBucket`) but creates its own CloudFront distribution and Lambda function\n3. Point `pr-123.app.example.com` DNS to the branch's CloudFront distribution\n4. 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), the number of top level files/directories cannot exceed 25, the max number of behaviors a CloudFront Distribution supports. 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. See [CloudFront Quotas](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html) for more information.\n- If using `NextjsGlobalFunctions`, when [revalidating data in Next.js](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation) (i.e. [revalidatePath](https://nextjs.org/docs/app/api-reference/functions/revalidatePath)), the CloudFront Cache will still hold stale data. You'll need to use AWS SDK JS V3 [CreateInvalidationCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-cloudfront/Class/CreateInvalidationCommand/) to manually invalidate the path in CloudFront. See more [here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html).\n- If using `NextjsGlobalFunctions`, setting an Authorization header won't work by default because of Lambda Function URL with IAM Auth is already using the Authorization header. You can use the `AWS_LWA_AUTHORIZATION_SOURCE` environment variable of [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter) to set an alternative Authorization header in the client which will then be set to the Authorization header when it reaches your app.\n- `NextjsRegionalFunctions` streaming depends on whether your server Lambda supports response streaming (e.g. [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter)'s `AWS_LWA_INVOKE_MODE`) — override `overrides.nextjsApi.dynamicIntegrationProps.responseTransferMode` to `BUFFERED` if it doesn't, otherwise API Gateway returns a 500 for every request.\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. Additionally, you'll need to add middleware logic to rewrite requests to include the stage name because API Gateway does not include the stage name in the path passed to Lambda. See [examples/app-playground/middleware.ts](./examples/app-playground/middleware.ts). 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\n[Artillery Playwright](https://www.artillery.io/docs/reference/engines/playwright#overview) app playground example load tests results with 1K concurrent users. Reproduce with `pnpm test-fargate:lg` within `examples/load-tests`.\n\n### NextjsGlobalFunctions\n\n<details>\n<summary>`NextjsGlobalFunctions` Performance Details</summary>\n\n```bash\nbrowser.page.TTFB.https://abc123.cloudfront.net/isr:\n  min: ......................................................................... 6.3\n  max: ......................................................................... 5017.4\n  mean: ........................................................................ 11.5\n  median: ...................................................................... 10.3\n  p95: ......................................................................... 15.6\n  p99: ......................................................................... 22.9\nbrowser.page.TTFB.https://abc123.cloudfront.net/isr/1:\n  min: ......................................................................... 3.2\n  max: ......................................................................... 560.6\n  mean: ........................................................................ 9.4\n  median: ...................................................................... 5.4\n  p95: ......................................................................... 11.1\n  p99: ......................................................................... 162.4\nbrowser.page.TTFB.https://abc123.cloudfront.net/isr/2:\n  min: ......................................................................... 3.1\n  max: ......................................................................... 1511.9\n  mean: ........................................................................ 9.2\n  median: ...................................................................... 5.2\n  p95: ......................................................................... 10.7\n  p99: ......................................................................... 149.9\nbrowser.page.TTFB.https://abc123.cloudfront.net/isr/3:\n  min: ......................................................................... 3.4\n  max: ......................................................................... 131.1\n  mean: ........................................................................ 7.1\n  median: ...................................................................... 5.3\n  p95: ......................................................................... 10.1\n  p99: ......................................................................... 64.7\nbrowser.page.TTFB.https://abc123.cloudfront.net/ssg:\n  min: ......................................................................... 6.4\n  max: ......................................................................... 5015.1\n  mean: ........................................................................ 11.5\n  median: ...................................................................... 10.3\n  p95: ......................................................................... 15.6\n  p99: ......................................................................... 23.3\nbrowser.page.TTFB.https://abc123.cloudfront.net/ssg/3:\n  min: ......................................................................... 2.9\n  max: ......................................................................... 98\n  mean: ........................................................................ 5.1\n  median: ...................................................................... 4.6\n  p95: ......................................................................... 8.2\n  p99: ......................................................................... 12.8\nbrowser.page.TTFB.https://abc123.cloudfront.net/ssr:\n  min: ......................................................................... 6.4\n  max: ......................................................................... 5018.6\n  mean: ........................................................................ 11.3\n  median: ...................................................................... 10.3\n  p95: ......................................................................... 15.6\n  p99: ......................................................................... 23.3\nbrowser.page.TTFB.https://abc123.cloudfront.net/ssr/2:\n  min: ......................................................................... 83.4\n  max: ......................................................................... 150.7\n  mean: ........................................................................ 119\n  median: ...................................................................... 111.1\n  p95: ......................................................................... 147\n  p99: ......................................................................... 147\nbrowser.page.TTFB.https://abc123.cloudfront.net/streaming:\n  min: ......................................................................... 6.4\n  max: ......................................................................... 5015.2\n  mean: ........................................................................ 11.8\n  median: ...................................................................... 10.3\n  p95: ......................................................................... 15.6\n  p99: ......................................................................... 23.3\n```\n\n</details>\n\n![1K concurrent users](./docs/1k-concurrent-users-executions.png)\n\n### NextjsGlobalContainers\n\n<details>\n<summary>`NextjsGlobalContainers` Performance Details</summary>\n\n```bash\nTODO\n```\n\n</details>\n\n### NextjsRegionalContainers\n\n<details>\n<summary>`NextjsRegionalContainers` Performance Details</summary>\n\n```bash\nTODO\n```\n\n### NextjsRegionalFunctions\n\n<details>\n<summary>`NextjsRegionalFunctions` Performance Details</summary>\n\n```bash\nTODO\n```\n\n</details>\n\n## Guides\n\n- [Caching Guide](./docs/caching-guide.md)\n- [Pruning Guide](./docs/pruning-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)?<br/>\nA: cdk-nextjs-standalone relies on [OpenNext](https://github.com/sst/open-next). OpenNext injects custom code to interact with private Next.js APIs. While OpenNext is able to make some optimizations that are great for serverless environments, this comes at an increase maintenance cost and increased chances for breaking changes. A goal of cdk-nextjs is to customize Next.js as little as possible to reduce the maintenance burden and decrease chances of breaking changes.\n\nQ: Why does cdk-nextjs depend upon Next.js v16.2 or higher?\nA: This version is required for [Image Optimization Caching](https://nextjs.org/docs/app/api-reference/config/next-config-js/incrementalCacheHandlerPath#image-optimization-caching) so that cdk-nextjs can depend upon public Next.js API.\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: Why use container image for `NextjsGlobalFunctions`?<br />\nA: Read [The case for containers on Lambda (with benchmarks)](https://aaronstuyvenberg.com/posts/containers-on-lambda). Also, we depend upon [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter) to transform lambda event payloads into HTTP requests that Next.js expects.\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 [open-next](https://github.com/sst/open-next).\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",
@@ -9059,7 +9059,7 @@
         },
         "locationInModule": {
           "filename": "src/nextjs-api.ts",
-          "line": 90
+          "line": 127
         },
         "parameters": [
           {
@@ -9085,7 +9085,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/nextjs-api.ts",
-        "line": 79
+        "line": 91
       },
       "name": "NextjsApi",
       "properties": [
@@ -9097,12 +9097,28 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 83
+            "line": 95
           },
           "name": "api",
           "type": {
             "fqn": "aws-cdk-lib.aws_apigateway.RestApi"
           }
+        },
+        {
+          "docs": {
+            "remarks": "Prefers a custom domain configured through `overrides.restApiProps.domainName`\nover the execute-api endpoint.\n\nA domain attached after this construct is created (`api.addDomainName()`) is\nstill used for the host, but CDK keeps its base path mappings private, so a\nmapping added that way won't show up here.",
+            "stability": "stable",
+            "summary": "Public URL of the app, including every path segment the API nests it under."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/nextjs-api.ts",
+            "line": 106
+          },
+          "name": "url",
+          "type": {
+            "primitive": "string"
+          }
         }
       ],
       "symbolId": "src/nextjs-api:NextjsApi"
@@ -9117,7 +9133,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/nextjs-api.ts",
-        "line": 27
+        "line": 28
       },
       "name": "NextjsApiOverrides",
       "properties": [
@@ -9129,7 +9145,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 31
+            "line": 32
           },
           "name": "dynamicIntegrationProps",
           "optional": true,
@@ -9145,7 +9161,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 32
+            "line": 33
           },
           "name": "imageIntegrationProps",
           "optional": true,
@@ -9161,7 +9177,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 28
+            "line": 29
           },
           "name": "restApiProps",
           "optional": true,
@@ -9177,7 +9193,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 30
+            "line": 31
           },
           "name": "s3MethodOptions",
           "optional": true,
@@ -9193,7 +9209,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 29
+            "line": 30
           },
           "name": "staticIntegrationProps",
           "optional": true,
@@ -9214,7 +9230,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/nextjs-api.ts",
-        "line": 35
+        "line": 36
       },
       "name": "NextjsApiProps",
       "properties": [
@@ -9227,7 +9243,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 48
+            "line": 49
           },
           "name": "publicDirEntries",
           "type": {
@@ -9248,7 +9264,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 69
+            "line": 70
           },
           "name": "staticAssetsBucket",
           "type": {
@@ -9264,7 +9280,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 39
+            "line": 40
           },
           "name": "basePath",
           "optional": true,
@@ -9282,7 +9298,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 65
+            "line": 66
           },
           "name": "imageFunction",
           "optional": true,
@@ -9299,7 +9315,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 43
+            "line": 44
           },
           "name": "overrides",
           "optional": true,
@@ -9317,7 +9333,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 52
+            "line": 53
           },
           "name": "serverFunction",
           "optional": true,
@@ -9325,6 +9341,24 @@
             "fqn": "aws-cdk-lib.aws_lambda.IFunction"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Independent of `basePath` above: that one is the URL prefix the REST API\nserves the app at (commonly the API Gateway stage), while this one is where\nthe objects live in the bucket. `_next/static` and public directory\nrequests are mapped to S3 keys directly, so they 404 unless this prefix is\napplied.",
+            "stability": "stable",
+            "summary": "S3 key prefix the static assets were uploaded under, i.e. `NextjsStaticAssets.keyPrefix`, which namespaces a shared bucket."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/nextjs-api.ts",
+            "line": 81
+          },
+          "name": "staticAssetsKeyPrefix",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -9335,7 +9369,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-api.ts",
-            "line": 73
+            "line": 85
           },
           "name": "vpc",
           "optional": true,
@@ -9361,7 +9395,7 @@
         },
         "locationInModule": {
           "filename": "src/root-constructs/nextjs-base-construct.ts",
-          "line": 145
+          "line": 174
         },
         "parameters": [
           {
@@ -9393,7 +9427,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-base-construct.ts",
-        "line": 131
+        "line": 153
       },
       "methods": [
         {
@@ -9403,7 +9437,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 183
+            "line": 250
           },
           "name": "computeBaseProps",
           "protected": true,
@@ -9420,7 +9454,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 230
+            "line": 297
           },
           "name": "createNextjsFunctions",
           "parameters": [
@@ -9447,7 +9481,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 253
+            "line": 320
           },
           "name": "createNextjsImageFunction",
           "parameters": [
@@ -9476,7 +9510,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 140
+            "line": 162
           },
           "name": "baseProps",
           "protected": true,
@@ -9491,7 +9525,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 138
+            "line": 160
           },
           "name": "nextjsType",
           "protected": true,
@@ -9507,7 +9541,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 136
+            "line": 158
           },
           "name": "url",
           "type": {
@@ -9521,7 +9555,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 143
+            "line": 165
           },
           "name": "constructOverrides",
           "optional": true,
@@ -9530,13 +9564,31 @@
             "fqn": "cdk-nextjs.NextjsFunctionsConstructOverrides"
           }
         },
+        {
+          "docs": {
+            "remarks": "Normalized to a bare path segment, `undefined` for\nno `basePath`. Use this instead of `baseProps.basePath`.",
+            "stability": "stable",
+            "summary": "The `basePath` everything downstream is built from: the `basePath` prop when set, otherwise the app's own `basePath` for the `NextjsType`s where the two are necessarily the same."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/root-constructs/nextjs-base-construct.ts",
+            "line": 172
+          },
+          "name": "resolvedBasePath",
+          "optional": true,
+          "protected": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
         {
           "docs": {
             "stability": "stable"
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 132
+            "line": 154
           },
           "name": "nextjsBuild",
           "type": {
@@ -9549,7 +9601,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 134
+            "line": 156
           },
           "name": "nextjsCache",
           "type": {
@@ -9562,7 +9614,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 133
+            "line": 155
           },
           "name": "nextjsStaticAssets",
           "type": {
@@ -9583,7 +9635,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-base-construct.ts",
-        "line": 30
+        "line": 31
       },
       "name": "NextjsBaseConstructOverrides",
       "properties": [
@@ -9595,7 +9647,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 31
+            "line": 32
           },
           "name": "nextjsBuildProps",
           "optional": true,
@@ -9611,7 +9663,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 32
+            "line": 33
           },
           "name": "nextjsCacheProps",
           "optional": true,
@@ -9627,7 +9679,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 33
+            "line": 34
           },
           "name": "nextjsStaticAssetsProps",
           "optional": true,
@@ -9652,7 +9704,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-base-construct.ts",
-        "line": 124
+        "line": 146
       },
       "name": "NextjsBaseConstructProps",
       "properties": [
@@ -9664,7 +9716,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 125
+            "line": 147
           },
           "name": "overrides",
           "optional": true,
@@ -9686,7 +9738,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-base-construct.ts",
-        "line": 49
+        "line": 50
       },
       "name": "NextjsBaseOverrides",
       "properties": [
@@ -9698,7 +9750,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 50
+            "line": 51
           },
           "name": "nextjsCache",
           "optional": true,
@@ -9714,7 +9766,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 51
+            "line": 52
           },
           "name": "nextjsStaticAssets",
           "optional": true,
@@ -9735,7 +9787,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-base-construct.ts",
-        "line": 54
+        "line": 55
       },
       "name": "NextjsBaseProps",
       "properties": [
@@ -9749,7 +9801,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 71
+            "line": 93
           },
           "name": "buildDirectory",
           "type": {
@@ -9766,7 +9818,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 89
+            "line": 111
           },
           "name": "healthCheckPath",
           "type": {
@@ -9777,13 +9829,14 @@
           "abstract": true,
           "docs": {
             "example": "\"/my-base-path\"",
+            "remarks": "Also namespaces the\nstatic assets in S3, so it doubles as a way to host multiple apps or\nbranches out of one bucket.\n\nHow this relates to the `basePath` in your app's `next.config.js` depends\non the construct, and synth fails on a combination that can't serve the\napp:\n\n- `NextjsGlobalFunctions`/`NextjsGlobalContainers`: leave this unset and it\n  follows your app's `basePath`, which is what you want — CloudFront serves\n  static assets from S3 using the request path as the object key, so the two\n  have to be identical and a mismatch 404s all of them. Setting a different\n  value throws.\n- `NextjsRegionalFunctions`: if you set this, the app's `basePath` must end\n  with it — either equal to it, or prefixed by the stage or base path\n  mapping API Gateway strips before matching resources (`basePath:\n  \"/prod/base\"` with this set to `\"/base\"`). Leaving it unset while the app\n  sets one is correct and common — an app served at the default `prod` stage\n  sets `basePath: \"/prod\"` and leaves this alone.\n- `NextjsRegionalContainers`: only namespaces the S3 bucket. The ALB sends\n  every path to the container, which serves its own static assets, so this\n  is unconstrained.",
             "stability": "stable",
             "summary": "Prefix to the URI path the app will be served at."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 59
+            "line": 81
           },
           "name": "basePath",
           "optional": true,
@@ -9801,7 +9854,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 64
+            "line": 86
           },
           "name": "buildCommand",
           "optional": true,
@@ -9819,7 +9872,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 77
+            "line": 99
           },
           "name": "cacheBucket",
           "optional": true,
@@ -9837,7 +9890,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 97
+            "line": 119
           },
           "name": "revalidationTable",
           "optional": true,
@@ -9856,7 +9909,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 103
+            "line": 125
           },
           "name": "skipBuild",
           "optional": true,
@@ -9874,7 +9927,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 109
+            "line": 131
           },
           "name": "staticAssetsBucket",
           "optional": true,
@@ -9892,7 +9945,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 117
+            "line": 139
           },
           "name": "vpc",
           "optional": true,
@@ -9920,7 +9973,7 @@
         },
         "locationInModule": {
           "filename": "src/nextjs-build/nextjs-build.ts",
-          "line": 99
+          "line": 108
         },
         "parameters": [
           {
@@ -9946,7 +9999,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/nextjs-build/nextjs-build.ts",
-        "line": 53
+        "line": 54
       },
       "name": "NextjsBuild",
       "properties": [
@@ -9957,7 +10010,7 @@
           },
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 58
+            "line": 59
           },
           "name": "buildId",
           "type": {
@@ -9971,7 +10024,7 @@
           },
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 86
+            "line": 87
           },
           "name": "dotNextPath",
           "type": {
@@ -9986,13 +10039,27 @@
           },
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 63
+            "line": 64
           },
           "name": "initCacheDir",
           "type": {
             "primitive": "string"
           }
         },
+        {
+          "docs": {
+            "stability": "stable",
+            "summary": "The Next.js app's own `basePath` — the URL prefix it generates its links and asset hrefs under — read out of the build's `required-server-files.json`. Normalized to a bare path segment, empty when the app sets none. Exposed so root constructs can reconcile it with the CDK `basePath` prop, which is a distinct thing; see `resolveBasePath`."
+          },
+          "locationInModule": {
+            "filename": "src/nextjs-build/nextjs-build.ts",
+            "line": 95
+          },
+          "name": "nextConfigBasePath",
+          "type": {
+            "primitive": "string"
+          }
+        },
         {
           "docs": {
             "example": "\"/Users/john/myapp/public\"",
@@ -10002,7 +10069,7 @@
           },
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 68
+            "line": 69
           },
           "name": "publicDirEntries",
           "type": {
@@ -10022,7 +10089,7 @@
           },
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 75
+            "line": 76
           },
           "name": "relativePathToEntrypoint",
           "type": {
@@ -10037,7 +10104,7 @@
           },
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 82
+            "line": 83
           },
           "name": "relativePathToPackage",
           "type": {
@@ -10051,7 +10118,7 @@
           },
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 94
+            "line": 103
           },
           "name": "imageOptimizationAssetPath",
           "optional": true,
@@ -10072,7 +10139,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/nextjs-build/nextjs-build.ts",
-        "line": 27
+        "line": 28
       },
       "name": "NextjsBuildProps",
       "properties": [
@@ -10085,7 +10152,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 36
+            "line": 37
           },
           "name": "buildDirectory",
           "type": {
@@ -10100,7 +10167,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 37
+            "line": 38
           },
           "name": "nextjsType",
           "type": {
@@ -10116,7 +10183,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 31
+            "line": 32
           },
           "name": "buildCommand",
           "optional": true,
@@ -10133,7 +10200,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 41
+            "line": 42
           },
           "name": "skipBuild",
           "optional": true,
@@ -10836,7 +10903,7 @@
         },
         "locationInModule": {
           "filename": "src/nextjs-distribution.ts",
-          "line": 140
+          "line": 152
         },
         "parameters": [
           {
@@ -10862,7 +10929,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/nextjs-distribution.ts",
-        "line": 103
+        "line": 108
       },
       "name": "NextjsDistribution",
       "properties": [
@@ -10872,7 +10939,7 @@
           },
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 104
+            "line": 109
           },
           "name": "distribution",
           "type": {
@@ -10892,7 +10959,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/nextjs-distribution.ts",
-        "line": 47
+        "line": 48
       },
       "name": "NextjsDistributionOverrides",
       "properties": [
@@ -10904,7 +10971,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 48
+            "line": 49
           },
           "name": "distributionProps",
           "optional": true,
@@ -10920,7 +10987,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 52
+            "line": 53
           },
           "name": "dynamicBehaviorOptions",
           "optional": true,
@@ -10936,7 +11003,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 53
+            "line": 54
           },
           "name": "dynamicCachePolicyProps",
           "optional": true,
@@ -10952,7 +11019,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 55
+            "line": 56
           },
           "name": "dynamicFunctionUrlOriginWithOACProps",
           "optional": true,
@@ -10968,7 +11035,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 54
+            "line": 55
           },
           "name": "dynamicResponseHeadersPolicyProps",
           "optional": true,
@@ -10984,7 +11051,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 56
+            "line": 57
           },
           "name": "dynamicVpcOriginWithEndpointProps",
           "optional": true,
@@ -11000,7 +11067,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 49
+            "line": 50
           },
           "name": "imageBehaviorOptions",
           "optional": true,
@@ -11016,7 +11083,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 50
+            "line": 51
           },
           "name": "imageCachePolicyProps",
           "optional": true,
@@ -11032,7 +11099,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 57
+            "line": 58
           },
           "name": "imageFunctionUrlOriginWithOACProps",
           "optional": true,
@@ -11048,7 +11115,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 51
+            "line": 52
           },
           "name": "imageResponseHeadersPolicyProps",
           "optional": true,
@@ -11064,7 +11131,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 60
+            "line": 61
           },
           "name": "s3BucketOriginProps",
           "optional": true,
@@ -11080,7 +11147,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 58
+            "line": 59
           },
           "name": "staticBehaviorOptions",
           "optional": true,
@@ -11096,7 +11163,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 59
+            "line": 60
           },
           "name": "staticResponseHeadersPolicyProps",
           "optional": true,
@@ -11117,7 +11184,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/nextjs-distribution.ts",
-        "line": 63
+        "line": 64
       },
       "name": "NextjsDistributionProps",
       "properties": [
@@ -11131,7 +11198,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 68
+            "line": 69
           },
           "name": "assetsBucket",
           "type": {
@@ -11146,7 +11213,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 91
+            "line": 96
           },
           "name": "nextjsType",
           "type": {
@@ -11162,7 +11229,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 100
+            "line": 105
           },
           "name": "publicDirEntries",
           "type": {
@@ -11177,12 +11244,14 @@
         {
           "abstract": true,
           "docs": {
-            "stability": "stable"
+            "remarks": "Surrounding slashes are normalized\naway, so \"/base\", \"base\" and \"/base/\" all produce the same cache behaviors.",
+            "stability": "stable",
+            "summary": "URI path prefix the app is served at."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 69
+            "line": 74
           },
           "name": "basePath",
           "optional": true,
@@ -11199,7 +11268,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 73
+            "line": 78
           },
           "name": "certificate",
           "optional": true,
@@ -11215,7 +11284,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 74
+            "line": 79
           },
           "name": "distribution",
           "optional": true,
@@ -11232,7 +11301,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 78
+            "line": 83
           },
           "name": "functionUrl",
           "optional": true,
@@ -11250,7 +11319,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 86
+            "line": 91
           },
           "name": "imageFunctionUrl",
           "optional": true,
@@ -11267,7 +11336,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 90
+            "line": 95
           },
           "name": "loadBalancer",
           "optional": true,
@@ -11284,7 +11353,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-distribution.ts",
-            "line": 95
+            "line": 100
           },
           "name": "overrides",
           "optional": true,
@@ -11384,7 +11453,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-base-construct.ts",
-        "line": 41
+        "line": 42
       },
       "name": "NextjsFunctionsConstructOverrides",
       "properties": [
@@ -11396,7 +11465,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 42
+            "line": 43
           },
           "name": "nextjsFunctionsProps",
           "optional": true,
@@ -11412,7 +11481,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-base-construct.ts",
-            "line": 43
+            "line": 44
           },
           "name": "nextjsImageFunctionProps",
           "optional": true,
@@ -11538,7 +11607,7 @@
         },
         "locationInModule": {
           "filename": "src/root-constructs/nextjs-global-containers.ts",
-          "line": 89
+          "line": 98
         },
         "parameters": [
           {
@@ -11564,18 +11633,19 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-containers.ts",
-        "line": 79
+        "line": 80
       },
       "name": "NextjsGlobalContainers",
       "properties": [
         {
           "docs": {
-            "stability": "stable"
+            "stability": "stable",
+            "summary": "Public URL of the app, including `basePath` — the app only answers under that prefix, and it's derived from the app's own `basePath` when the prop is left unset, so it's there whether or not you asked for it."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 83
+            "line": 89
           },
           "name": "url",
           "overrides": "cdk-nextjs.NextjsBaseConstruct",
@@ -11589,7 +11659,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 80
+            "line": 81
           },
           "name": "nextjsContainers",
           "type": {
@@ -11602,7 +11672,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 81
+            "line": 82
           },
           "name": "nextjsDistribution",
           "type": {
@@ -11615,7 +11685,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 82
+            "line": 83
           },
           "name": "nextjsPostDeploy",
           "type": {
@@ -11638,7 +11708,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-containers.ts",
-        "line": 31
+        "line": 32
       },
       "name": "NextjsGlobalContainersConstructOverrides",
       "properties": [
@@ -11650,7 +11720,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 32
+            "line": 33
           },
           "name": "nextjsContainersProps",
           "optional": true,
@@ -11666,7 +11736,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 33
+            "line": 34
           },
           "name": "nextjsDistributionProps",
           "optional": true,
@@ -11682,7 +11752,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 34
+            "line": 35
           },
           "name": "nextjsPostDeployProps",
           "optional": true,
@@ -11708,7 +11778,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-containers.ts",
-        "line": 42
+        "line": 43
       },
       "name": "NextjsGlobalContainersOverrides",
       "properties": [
@@ -11720,7 +11790,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 44
+            "line": 45
           },
           "name": "nextjsContainers",
           "optional": true,
@@ -11736,7 +11806,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 45
+            "line": 46
           },
           "name": "nextjsDistribution",
           "optional": true,
@@ -11752,7 +11822,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 43
+            "line": 44
           },
           "name": "nextjsGlobalContainers",
           "optional": true,
@@ -11768,7 +11838,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 46
+            "line": 47
           },
           "name": "nextjsPostDeploy",
           "optional": true,
@@ -11792,7 +11862,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-containers.ts",
-        "line": 49
+        "line": 50
       },
       "name": "NextjsGlobalContainersProps",
       "properties": [
@@ -11806,7 +11876,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 56
+            "line": 57
           },
           "name": "alb",
           "optional": true,
@@ -11824,7 +11894,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 61
+            "line": 62
           },
           "name": "distribution",
           "optional": true,
@@ -11842,7 +11912,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 66
+            "line": 67
           },
           "name": "ecsCluster",
           "optional": true,
@@ -11859,7 +11929,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-containers.ts",
-            "line": 70
+            "line": 71
           },
           "name": "overrides",
           "optional": true,
@@ -11884,7 +11954,7 @@
         },
         "locationInModule": {
           "filename": "src/root-constructs/nextjs-global-functions.ts",
-          "line": 85
+          "line": 94
         },
         "parameters": [
           {
@@ -11910,18 +11980,19 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-functions.ts",
-        "line": 69
+        "line": 70
       },
       "name": "NextjsGlobalFunctions",
       "properties": [
         {
           "docs": {
-            "stability": "stable"
+            "stability": "stable",
+            "summary": "Public URL of the app, including `basePath` — the app only answers under that prefix, and it's derived from the app's own `basePath` when the prop is left unset, so it's there whether or not you asked for it."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 79
+            "line": 85
           },
           "name": "url",
           "overrides": "cdk-nextjs.NextjsBaseConstruct",
@@ -11935,7 +12006,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 77
+            "line": 78
           },
           "name": "nextjsDistribution",
           "type": {
@@ -11948,7 +12019,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 70
+            "line": 71
           },
           "name": "nextjsFunctions",
           "type": {
@@ -11961,7 +12032,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 78
+            "line": 79
           },
           "name": "nextjsPostDeploy",
           "type": {
@@ -11976,7 +12047,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 76
+            "line": 77
           },
           "name": "nextjsImageFunction",
           "optional": true,
@@ -12000,7 +12071,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-functions.ts",
-        "line": 33
+        "line": 34
       },
       "name": "NextjsGlobalFunctionsConstructOverrides",
       "properties": [
@@ -12012,7 +12083,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 34
+            "line": 35
           },
           "name": "nextjsDistributionProps",
           "optional": true,
@@ -12028,7 +12099,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 35
+            "line": 36
           },
           "name": "nextjsPostDeployProps",
           "optional": true,
@@ -12054,7 +12125,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-functions.ts",
-        "line": 43
+        "line": 44
       },
       "name": "NextjsGlobalFunctionsOverrides",
       "properties": [
@@ -12066,7 +12137,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 47
+            "line": 48
           },
           "name": "nextjsDistribution",
           "optional": true,
@@ -12082,7 +12153,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 45
+            "line": 46
           },
           "name": "nextjsFunctions",
           "optional": true,
@@ -12098,7 +12169,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 44
+            "line": 45
           },
           "name": "nextjsGlobalFunctions",
           "optional": true,
@@ -12114,7 +12185,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 46
+            "line": 47
           },
           "name": "nextjsImageFunction",
           "optional": true,
@@ -12130,7 +12201,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 48
+            "line": 49
           },
           "name": "nextjsPostDeploy",
           "optional": true,
@@ -12154,7 +12225,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-global-functions.ts",
-        "line": 51
+        "line": 52
       },
       "name": "NextjsGlobalFunctionsProps",
       "properties": [
@@ -12168,7 +12239,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 56
+            "line": 57
           },
           "name": "distribution",
           "optional": true,
@@ -12185,7 +12256,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-global-functions.ts",
-            "line": 60
+            "line": 61
           },
           "name": "overrides",
           "optional": true,
@@ -12210,7 +12281,7 @@
         },
         "locationInModule": {
           "filename": "src/nextjs-compute/nextjs-image-function.ts",
-          "line": 57
+          "line": 67
         },
         "parameters": [
           {
@@ -12236,7 +12307,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/nextjs-compute/nextjs-image-function.ts",
-        "line": 51
+        "line": 61
       },
       "name": "NextjsImageFunction",
       "properties": [
@@ -12246,7 +12317,7 @@
           },
           "locationInModule": {
             "filename": "src/nextjs-compute/nextjs-image-function.ts",
-            "line": 52
+            "line": 62
           },
           "name": "function",
           "type": {
@@ -12259,7 +12330,7 @@
           },
           "locationInModule": {
             "filename": "src/nextjs-compute/nextjs-image-function.ts",
-            "line": 53
+            "line": 63
           },
           "name": "functionUrl",
           "optional": true,
@@ -12390,7 +12461,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-compute/nextjs-image-function.ts",
-            "line": 42
+            "line": 52
           },
           "name": "overrides",
           "optional": true,
@@ -12398,6 +12469,24 @@
             "fqn": "cdk-nextjs.NextjsImageFunctionOverrides"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Threaded through explicitly rather than read from the app's bundled config,\nbecause it's distinct from the app's own `basePath` (which next-image-loader\nbakes into hrefs) — the two diverge when the app's `basePath` comes from\nelsewhere, e.g. an API Gateway stage under `NextjsRegionalFunctions`.",
+            "stability": "stable",
+            "summary": "S3 key prefix the static assets were uploaded under, i.e. `NextjsStaticAssets.keyPrefix`, which namespaces a shared bucket."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/nextjs-compute/nextjs-image-function.ts",
+            "line": 47
+          },
+          "name": "staticAssetsKeyPrefix",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -12406,7 +12495,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-compute/nextjs-image-function.ts",
-            "line": 38
+            "line": 48
           },
           "name": "vpc",
           "optional": true,
@@ -12990,7 +13079,7 @@
         },
         "locationInModule": {
           "filename": "src/root-constructs/nextjs-regional-functions.ts",
-          "line": 71
+          "line": 70
         },
         "parameters": [
           {
@@ -13016,7 +13105,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-regional-functions.ts",
-        "line": 55
+        "line": 54
       },
       "name": "NextjsRegionalFunctions",
       "properties": [
@@ -13027,7 +13116,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 65
+            "line": 64
           },
           "name": "url",
           "overrides": "cdk-nextjs.NextjsBaseConstruct",
@@ -13041,7 +13130,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 63
+            "line": 62
           },
           "name": "nextjsApi",
           "type": {
@@ -13054,7 +13143,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 56
+            "line": 55
           },
           "name": "nextjsFunctions",
           "type": {
@@ -13067,7 +13156,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 64
+            "line": 63
           },
           "name": "nextjsPostDeploy",
           "type": {
@@ -13082,7 +13171,7 @@
           },
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 62
+            "line": 61
           },
           "name": "nextjsImageFunction",
           "optional": true,
@@ -13106,7 +13195,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-regional-functions.ts",
-        "line": 26
+        "line": 25
       },
       "name": "NextjsRegionalFunctionsConstructOverrides",
       "properties": [
@@ -13118,7 +13207,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 27
+            "line": 26
           },
           "name": "nextjsApiProps",
           "optional": true,
@@ -13134,7 +13223,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 28
+            "line": 27
           },
           "name": "nextjsPostDeployProps",
           "optional": true,
@@ -13160,7 +13249,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-regional-functions.ts",
-        "line": 36
+        "line": 35
       },
       "name": "NextjsRegionalFunctionsOverrides",
       "properties": [
@@ -13172,7 +13261,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 40
+            "line": 39
           },
           "name": "nextjsApi",
           "optional": true,
@@ -13188,7 +13277,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 38
+            "line": 37
           },
           "name": "nextjsFunctions",
           "optional": true,
@@ -13204,7 +13293,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 39
+            "line": 38
           },
           "name": "nextjsImageFunction",
           "optional": true,
@@ -13220,7 +13309,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 41
+            "line": 40
           },
           "name": "nextjsPostDeploy",
           "optional": true,
@@ -13236,7 +13325,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 37
+            "line": 36
           },
           "name": "nextjsRegionalFunctions",
           "optional": true,
@@ -13260,7 +13349,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/root-constructs/nextjs-regional-functions.ts",
-        "line": 44
+        "line": 43
       },
       "name": "NextjsRegionalFunctionsProps",
       "properties": [
@@ -13273,7 +13362,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/root-constructs/nextjs-regional-functions.ts",
-            "line": 48
+            "line": 47
           },
           "name": "overrides",
           "optional": true,
@@ -13298,7 +13387,7 @@
         },
         "locationInModule": {
           "filename": "src/nextjs-static-assets.ts",
-          "line": 66
+          "line": 77
         },
         "parameters": [
           {
@@ -13324,17 +13413,33 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/nextjs-static-assets.ts",
-        "line": 59
+        "line": 60
       },
       "name": "NextjsStaticAssets",
       "properties": [
+        {
+          "docs": {
+            "remarks": "Consumers that read assets back out of the bucket (the image optimization\nLambda, `NextjsApi`'s S3 integrations) must use this rather than the\n`basePath` prop, since `overrides.bucketDeploymentProps` can replace the\nprefix outright.",
+            "stability": "stable",
+            "summary": "S3 key prefix the assets are actually uploaded under, normalized to a bare path segment (empty when they live at the bucket root)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/nextjs-static-assets.ts",
+            "line": 72
+          },
+          "name": "keyPrefix",
+          "type": {
+            "primitive": "string"
+          }
+        },
         {
           "docs": {
             "stability": "stable"
           },
           "locationInModule": {
             "filename": "src/nextjs-static-assets.ts",
-            "line": 60
+            "line": 61
           },
           "name": "bucket",
           "type": {
@@ -13347,7 +13452,7 @@
           },
           "locationInModule": {
             "filename": "src/nextjs-static-assets.ts",
-            "line": 61
+            "line": 62
           },
           "name": "deployment",
           "type": {
@@ -13367,7 +13472,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/nextjs-static-assets.ts",
-        "line": 27
+        "line": 28
       },
       "name": "NextjsStaticAssetsOverrides",
       "properties": [
@@ -13379,7 +13484,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-static-assets.ts",
-            "line": 29
+            "line": 30
           },
           "name": "bucketDeploymentProps",
           "optional": true,
@@ -13395,7 +13500,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-static-assets.ts",
-            "line": 28
+            "line": 29
           },
           "name": "bucketProps",
           "optional": true,
@@ -13416,7 +13521,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/nextjs-static-assets.ts",
-        "line": 32
+        "line": 33
       },
       "name": "NextjsStaticAssetsProps",
       "properties": [
@@ -13429,7 +13534,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-static-assets.ts",
-            "line": 43
+            "line": 44
           },
           "name": "buildDirectory",
           "type": {
@@ -13445,7 +13550,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-static-assets.ts",
-            "line": 47
+            "line": 48
           },
           "name": "buildId",
           "type": {
@@ -13462,7 +13567,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-static-assets.ts",
-            "line": 52
+            "line": 53
           },
           "name": "basePath",
           "optional": true,
@@ -13480,7 +13585,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-static-assets.ts",
-            "line": 38
+            "line": 39
           },
           "name": "bucket",
           "optional": true,
@@ -13496,7 +13601,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-static-assets.ts",
-            "line": 53
+            "line": 54
           },
           "name": "overrides",
           "optional": true,
@@ -18737,7 +18842,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 56
+            "line": 59
           },
           "name": "assetsBucket",
           "optional": true,
@@ -18748,12 +18853,14 @@
         {
           "abstract": true,
           "docs": {
-            "stability": "stable"
+            "remarks": "Surrounding slashes are normalized\naway, so \"/base\", \"base\" and \"/base/\" all produce the same cache behaviors.",
+            "stability": "stable",
+            "summary": "URI path prefix the app is served at."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 41
+            "line": 44
           },
           "name": "basePath",
           "optional": true,
@@ -18854,7 +18961,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 50
+            "line": 53
           },
           "name": "nextjsType",
           "optional": true,
@@ -18871,7 +18978,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/generated-structs/OptionalNextjsDistributionProps.ts",
-            "line": 46
+            "line": 49
           },
           "name": "publicDirEntries",
           "optional": true,
@@ -19977,7 +20084,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/nextjs-build/nextjs-build.ts",
-        "line": 44
+        "line": 45
       },
       "name": "PublicDirEntry",
       "properties": [
@@ -19989,7 +20096,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 46
+            "line": 47
           },
           "name": "isDirectory",
           "type": {
@@ -20004,7 +20111,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/nextjs-build/nextjs-build.ts",
-            "line": 45
+            "line": 46
           },
           "name": "name",
           "type": {
@@ -20015,6 +20122,6 @@
       "symbolId": "src/nextjs-build/nextjs-build:PublicDirEntry"
     }
   },
-  "version": "0.5.16",
-  "fingerprint": "WkgTC64yZ4w+0WifXv7ga3U52o4WHYNoJEoUiFlMj+E="
+  "version": "0.6.0",
+  "fingerprint": "pFFkq0kZiIR22+vr8dHzSYSgrCGrr7EuMSFNU7NYwag="
 }