cdk-nextjs 0.7.11 → 0.7.13

package/API.md

@@ -2606,8 +2606,11 @@ Any object.
 | --- | --- | --- |
 | <code><a href="#cdk-nextjs.NextjsStaticAssets.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
 | <code><a href="#cdk-nextjs.NextjsStaticAssets.property.keyPrefix">keyPrefix</a></code> | <code>string</code> | S3 key prefix the assets are actually uploaded under, normalized to a bare path segment (empty when they live at the bucket root). |
+| <code><a href="#cdk-nextjs.NextjsStaticAssets.property.publicDeployment">publicDeployment</a></code> | <code>aws-cdk-lib.aws_s3_deployment.BucketDeployment</code> | Uploads `public/`, separately from `staticDeployment` because its files keep their names when they change and so can't be `immutable`. |
+| <code><a href="#cdk-nextjs.NextjsStaticAssets.property.serviceWorkerDeployment">serviceWorkerDeployment</a></code> | <code>aws-cdk-lib.aws_s3_deployment.BucketDeployment</code> | Uploads `.next/static/service-worker` with `Cache-Control: public, max-age=0, must-revalidate`, as Next.js serves it: a service worker keeps its URL across builds, so it can't be `immutable`. Absent if the build has no service worker. |
+| <code><a href="#cdk-nextjs.NextjsStaticAssets.property.staticDeployment">staticDeployment</a></code> | <code>aws-cdk-lib.aws_s3_deployment.BucketDeployment</code> | Uploads `.next/static` to `_next/static/` with `Cache-Control: public, max-age=31536000, immutable`, except for `service-worker/` (see `serviceWorkerDeployment`). Absent if the build has no `.next/static`. |
 | <code><a href="#cdk-nextjs.NextjsStaticAssets.property.bucket">bucket</a></code> | <code>aws-cdk-lib.aws_s3.IBucket</code> | *No description.* |
-| <code><a href="#cdk-nextjs.NextjsStaticAssets.property.deployment">deployment</a></code> | <code>aws-cdk-lib.aws_s3_deployment.BucketDeployment</code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsStaticAssets.property.deployment">deployment</a></code> | <code>aws-cdk-lib.aws_s3_deployment.BucketDeployment</code> | The first of `staticDeployment`, `serviceWorkerDeployment` and `publicDeployment` the build has files for. |
 
 ---
 
@@ -2643,6 +2646,45 @@ bytes were uploaded.
 
 ---
 
+##### `publicDeployment`<sup>Optional</sup> <a name="publicDeployment" id="cdk-nextjs.NextjsStaticAssets.property.publicDeployment"></a>
+
+```typescript
+public readonly publicDeployment: BucketDeployment;
+```
+
+- *Type:* aws-cdk-lib.aws_s3_deployment.BucketDeployment
+
+Uploads `public/`, separately from `staticDeployment` because its files keep their names when they change and so can't be `immutable`.
+
+Absent if
+the build has no `public` directory.
+
+---
+
+##### `serviceWorkerDeployment`<sup>Optional</sup> <a name="serviceWorkerDeployment" id="cdk-nextjs.NextjsStaticAssets.property.serviceWorkerDeployment"></a>
+
+```typescript
+public readonly serviceWorkerDeployment: BucketDeployment;
+```
+
+- *Type:* aws-cdk-lib.aws_s3_deployment.BucketDeployment
+
+Uploads `.next/static/service-worker` with `Cache-Control: public, max-age=0, must-revalidate`, as Next.js serves it: a service worker keeps its URL across builds, so it can't be `immutable`. Absent if the build has no service worker.
+
+---
+
+##### `staticDeployment`<sup>Optional</sup> <a name="staticDeployment" id="cdk-nextjs.NextjsStaticAssets.property.staticDeployment"></a>
+
+```typescript
+public readonly staticDeployment: BucketDeployment;
+```
+
+- *Type:* aws-cdk-lib.aws_s3_deployment.BucketDeployment
+
+Uploads `.next/static` to `_next/static/` with `Cache-Control: public, max-age=31536000, immutable`, except for `service-worker/` (see `serviceWorkerDeployment`). Absent if the build has no `.next/static`.
+
+---
+
 ##### `bucket`<sup>Required</sup> <a name="bucket" id="cdk-nextjs.NextjsStaticAssets.property.bucket"></a>
 
 ```typescript
@@ -2653,7 +2695,11 @@ public readonly bucket: IBucket;
 
 ---
 
-##### `deployment`<sup>Required</sup> <a name="deployment" id="cdk-nextjs.NextjsStaticAssets.property.deployment"></a>
+##### ~~`deployment`~~<sup>Required</sup> <a name="deployment" id="cdk-nextjs.NextjsStaticAssets.property.deployment"></a>
+
+- *Deprecated:* The assets are uploaded by up to three deployments, and this
+is only one of them: a dependency on it doesn't wait for the others. Use
+`staticDeployment`, `serviceWorkerDeployment` and `publicDeployment`.
 
 ```typescript
 public readonly deployment: BucketDeployment;
@@ -2661,6 +2707,8 @@ public readonly deployment: BucketDeployment;
 
 - *Type:* aws-cdk-lib.aws_s3_deployment.BucketDeployment
 
+The first of `staticDeployment`, `serviceWorkerDeployment` and `publicDeployment` the build has files for.
+
 ---
 
 
@@ -4384,6 +4432,8 @@ const nextjsDistributionProps: NextjsDistributionProps = { ... }
 | <code><a href="#cdk-nextjs.NextjsDistributionProps.property.loadBalancer">loadBalancer</a></code> | <code>aws-cdk-lib.aws_elasticloadbalancingv2.IApplicationLoadBalancer</code> | Required if `NextjsType.GLOBAL_CONTAINERS` or `NextjsType.REGIONAL_CONTAINERS`. |
 | <code><a href="#cdk-nextjs.NextjsDistributionProps.property.maxCacheBehaviors">maxCacheBehaviors</a></code> | <code>number</code> | The most cache behaviors the distribution may have, the default one included. |
 | <code><a href="#cdk-nextjs.NextjsDistributionProps.property.overrides">overrides</a></code> | <code><a href="#cdk-nextjs.NextjsDistributionOverrides">NextjsDistributionOverrides</a></code> | Override props for every construct. |
+| <code><a href="#cdk-nextjs.NextjsDistributionProps.property.viewerRequestFunctionCode">viewerRequestFunctionCode</a></code> | <code>aws-cdk-lib.aws_cloudfront.FunctionCode</code> | CloudFront Function code run first on every viewer request, on every behavior cdk-nextjs adds, static assets included — HTTP Basic auth on a pre-launch site, geo-gating. |
+| <code><a href="#cdk-nextjs.NextjsDistributionProps.property.viewerRequestKeyValueStore">viewerRequestKeyValueStore</a></code> | <code>aws-cdk-lib.aws_cloudfront.IKeyValueStore</code> | A CloudFront KeyValueStore associated with every viewer-request function {@link viewerRequestFunctionCode} is copied into (up to three, one per kind of behavior), so values it reads — Basic auth credentials, an allowlist — live outside the CloudFormation template and change without a deploy. |
 
 ---
 
@@ -4572,6 +4622,47 @@ Override props for every construct.
 
 ---
 
+##### `viewerRequestFunctionCode`<sup>Optional</sup> <a name="viewerRequestFunctionCode" id="cdk-nextjs.NextjsDistributionProps.property.viewerRequestFunctionCode"></a>
+
+```typescript
+public readonly viewerRequestFunctionCode: FunctionCode;
+```
+
+- *Type:* aws-cdk-lib.aws_cloudfront.FunctionCode
+- *Default:* none
+
+CloudFront Function code run first on every viewer request, on every behavior cdk-nextjs adds, static assets included — HTTP Basic auth on a pre-launch site, geo-gating.
+
+It must define `viewerRequest(event)` (a function, sync or async, or a
+`var`/`let`/`const`): return a response to answer the viewer, or the
+request (or nothing) to carry on. It is spliced into cdk-nextjs's own
+viewer-request functions, ahead of their logic, so it may not use the
+name `handler`, and the combined function must fit CloudFront's 10 KB.
+It runs on `cloudfront-js-2.0`, so it may be async and read
+{@link viewerRequestKeyValueStore} with `cf.kvs()`. A bring-your-own
+{@link distribution}'s default behavior isn't covered.
+
+> [https://github.com/cdklabs/cdk-nextjs#running-code-on-every-viewer-request](https://github.com/cdklabs/cdk-nextjs#running-code-on-every-viewer-request)
+
+---
+
+##### `viewerRequestKeyValueStore`<sup>Optional</sup> <a name="viewerRequestKeyValueStore" id="cdk-nextjs.NextjsDistributionProps.property.viewerRequestKeyValueStore"></a>
+
+```typescript
+public readonly viewerRequestKeyValueStore: IKeyValueStore;
+```
+
+- *Type:* aws-cdk-lib.aws_cloudfront.IKeyValueStore
+- *Default:* none
+
+A CloudFront KeyValueStore associated with every viewer-request function {@link viewerRequestFunctionCode} is copied into (up to three, one per kind of behavior), so values it reads — Basic auth credentials, an allowlist — live outside the CloudFormation template and change without a deploy.
+
+Read it with `cf.kvs()`, no ID needed.
+
+> [https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/functions-custom-methods.html](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/functions-custom-methods.html)
+
+---
+
 ### NextjsFunctionGroup <a name="NextjsFunctionGroup" id="cdk-nextjs.NextjsFunctionGroup"></a>
 
 A set of routes to package into their own Lambda function.
@@ -5248,6 +5339,8 @@ const nextjsGlobalContainersProps: NextjsGlobalContainersProps = { ... }
 | <code><a href="#cdk-nextjs.NextjsGlobalContainersProps.property.distribution">distribution</a></code> | <code>aws-cdk-lib.aws_cloudfront.Distribution</code> | Bring your own distribution. |
 | <code><a href="#cdk-nextjs.NextjsGlobalContainersProps.property.ecsCluster">ecsCluster</a></code> | <code>aws-cdk-lib.aws_ecs.ICluster</code> | Bring your own ECS cluster. |
 | <code><a href="#cdk-nextjs.NextjsGlobalContainersProps.property.overrides">overrides</a></code> | <code><a href="#cdk-nextjs.NextjsGlobalContainersOverrides">NextjsGlobalContainersOverrides</a></code> | Override props of any construct. |
+| <code><a href="#cdk-nextjs.NextjsGlobalContainersProps.property.viewerRequestFunctionCode">viewerRequestFunctionCode</a></code> | <code>aws-cdk-lib.aws_cloudfront.FunctionCode</code> | CloudFront Function code run first on every viewer request, static assets included — HTTP Basic auth on a pre-launch site, say. |
+| <code><a href="#cdk-nextjs.NextjsGlobalContainersProps.property.viewerRequestKeyValueStore">viewerRequestKeyValueStore</a></code> | <code>aws-cdk-lib.aws_cloudfront.IKeyValueStore</code> | A CloudFront KeyValueStore `viewerRequestFunctionCode` can read with `cf.kvs()`, so credentials stay out of the template. |
 
 ---
 
@@ -5519,6 +5612,39 @@ Override props of any construct.
 
 ---
 
+##### `viewerRequestFunctionCode`<sup>Optional</sup> <a name="viewerRequestFunctionCode" id="cdk-nextjs.NextjsGlobalContainersProps.property.viewerRequestFunctionCode"></a>
+
+```typescript
+public readonly viewerRequestFunctionCode: FunctionCode;
+```
+
+- *Type:* aws-cdk-lib.aws_cloudfront.FunctionCode
+- *Default:* none
+
+CloudFront Function code run first on every viewer request, static assets included — HTTP Basic auth on a pre-launch site, say.
+
+It must define
+`viewerRequest(event)`, as a function or a `var`/`let`/`const`.
+
+> [NextjsDistributionProps.viewerRequestFunctionCode *](NextjsDistributionProps.viewerRequestFunctionCode *)
+
+---
+
+##### `viewerRequestKeyValueStore`<sup>Optional</sup> <a name="viewerRequestKeyValueStore" id="cdk-nextjs.NextjsGlobalContainersProps.property.viewerRequestKeyValueStore"></a>
+
+```typescript
+public readonly viewerRequestKeyValueStore: IKeyValueStore;
+```
+
+- *Type:* aws-cdk-lib.aws_cloudfront.IKeyValueStore
+- *Default:* none
+
+A CloudFront KeyValueStore `viewerRequestFunctionCode` can read with `cf.kvs()`, so credentials stay out of the template.
+
+> [NextjsDistributionProps.viewerRequestKeyValueStore *](NextjsDistributionProps.viewerRequestKeyValueStore *)
+
+---
+
 ### NextjsGlobalFunctionsConstructOverrides <a name="NextjsGlobalFunctionsConstructOverrides" id="cdk-nextjs.NextjsGlobalFunctionsConstructOverrides"></a>
 
 #### Initializer <a name="Initializer" id="cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.Initializer"></a>
@@ -5705,6 +5831,8 @@ const nextjsGlobalFunctionsProps: NextjsGlobalFunctionsProps = { ... }
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsProps.property.distribution">distribution</a></code> | <code>aws-cdk-lib.aws_cloudfront.Distribution</code> | Bring your own distribution. |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsProps.property.functionGroups">functionGroups</a></code> | <code><a href="#cdk-nextjs.NextjsFunctionGroup">NextjsFunctionGroup</a>[]</code> | Package sets of routes into separate Lambda functions, each fronted by its own CloudFront behaviors. |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsProps.property.overrides">overrides</a></code> | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsOverrides">NextjsGlobalFunctionsOverrides</a></code> | Override props of any construct. |
+| <code><a href="#cdk-nextjs.NextjsGlobalFunctionsProps.property.viewerRequestFunctionCode">viewerRequestFunctionCode</a></code> | <code>aws-cdk-lib.aws_cloudfront.FunctionCode</code> | CloudFront Function code run first on every viewer request, static assets included — HTTP Basic auth on a pre-launch site, say. |
+| <code><a href="#cdk-nextjs.NextjsGlobalFunctionsProps.property.viewerRequestKeyValueStore">viewerRequestKeyValueStore</a></code> | <code>aws-cdk-lib.aws_cloudfront.IKeyValueStore</code> | A CloudFront KeyValueStore `viewerRequestFunctionCode` can read with `cf.kvs()`, so credentials stay out of the template. |
 
 ---
 
@@ -5934,6 +6062,39 @@ Override props of any construct.
 
 ---
 
+##### `viewerRequestFunctionCode`<sup>Optional</sup> <a name="viewerRequestFunctionCode" id="cdk-nextjs.NextjsGlobalFunctionsProps.property.viewerRequestFunctionCode"></a>
+
+```typescript
+public readonly viewerRequestFunctionCode: FunctionCode;
+```
+
+- *Type:* aws-cdk-lib.aws_cloudfront.FunctionCode
+- *Default:* none
+
+CloudFront Function code run first on every viewer request, static assets included — HTTP Basic auth on a pre-launch site, say.
+
+It must define
+`viewerRequest(event)`, as a function or a `var`/`let`/`const`.
+
+> [NextjsDistributionProps.viewerRequestFunctionCode *](NextjsDistributionProps.viewerRequestFunctionCode *)
+
+---
+
+##### `viewerRequestKeyValueStore`<sup>Optional</sup> <a name="viewerRequestKeyValueStore" id="cdk-nextjs.NextjsGlobalFunctionsProps.property.viewerRequestKeyValueStore"></a>
+
+```typescript
+public readonly viewerRequestKeyValueStore: IKeyValueStore;
+```
+
+- *Type:* aws-cdk-lib.aws_cloudfront.IKeyValueStore
+- *Default:* none
+
+A CloudFront KeyValueStore `viewerRequestFunctionCode` can read with `cf.kvs()`, so credentials stay out of the template.
+
+> [NextjsDistributionProps.viewerRequestKeyValueStore *](NextjsDistributionProps.viewerRequestKeyValueStore *)
+
+---
+
 ### NextjsPostDeployOverrides <a name="NextjsPostDeployOverrides" id="cdk-nextjs.NextjsPostDeployOverrides"></a>
 
 #### Initializer <a name="Initializer" id="cdk-nextjs.NextjsPostDeployOverrides.Initializer"></a>
@@ -6974,7 +7135,7 @@ const nextjsStaticAssetsOverrides: NextjsStaticAssetsOverrides = { ... }
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
-| <code><a href="#cdk-nextjs.NextjsStaticAssetsOverrides.property.bucketDeploymentProps">bucketDeploymentProps</a></code> | <code>aws-cdk-lib.aws_s3_deployment.BucketDeploymentProps</code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsStaticAssetsOverrides.property.bucketDeploymentProps">bucketDeploymentProps</a></code> | <code>aws-cdk-lib.aws_s3_deployment.BucketDeploymentProps</code> | Applied to every upload (`public/`, `_next/static/` and `_next/static/service-worker/`), except that the two `_next/static` uploads always keep the `Cache-Control` Next.js sends for them. So a `cacheControl` here sets the header for `public/` files only, while anything else, such as a `distribution` to invalidate, applies to each upload in turn. |
 | <code><a href="#cdk-nextjs.NextjsStaticAssetsOverrides.property.bucketProps">bucketProps</a></code> | <code>aws-cdk-lib.aws_s3.BucketProps</code> | *No description.* |
 
 ---
@@ -6987,6 +7148,14 @@ public readonly bucketDeploymentProps: BucketDeploymentProps;
 
 - *Type:* aws-cdk-lib.aws_s3_deployment.BucketDeploymentProps
 
+Applied to every upload (`public/`, `_next/static/` and `_next/static/service-worker/`), except that the two `_next/static` uploads always keep the `Cache-Control` Next.js sends for them. So a `cacheControl` here sets the header for `public/` files only, while anything else, such as a `distribution` to invalidate, applies to each upload in turn.
+
+`sources` and `destinationBucket`, which the type requires, are ignored:
+the uploads are always the build's assets, to the bucket CloudFront and
+API Gateway read from (pass `bucket` to bring your own). `prune: true` and
+`retainOnDelete: false` are rejected, since each would break the other
+uploads.
+
 ---
 
 ##### `bucketProps`<sup>Optional</sup> <a name="bucketProps" id="cdk-nextjs.NextjsStaticAssetsOverrides.property.bucketProps"></a>
@@ -10862,6 +11031,8 @@ const optionalNextjsDistributionProps: OptionalNextjsDistributionProps = { ... }
 | <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.property.maxCacheBehaviors">maxCacheBehaviors</a></code> | <code>number</code> | The most cache behaviors the distribution may have, the default one included. |
 | <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.property.nextjsType">nextjsType</a></code> | <code><a href="#cdk-nextjs.NextjsType">NextjsType</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.property.publicDirEntries">publicDirEntries</a></code> | <code><a href="#cdk-nextjs.PublicDirEntry">PublicDirEntry</a>[]</code> | Entries (files/directories) within Next.js app's public directory. Used to add static behaviors to distribution. |
+| <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.property.viewerRequestFunctionCode">viewerRequestFunctionCode</a></code> | <code>aws-cdk-lib.aws_cloudfront.FunctionCode</code> | CloudFront Function code run first on every viewer request, on every behavior cdk-nextjs adds, static assets included — HTTP Basic auth on a pre-launch site, geo-gating. |
+| <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.property.viewerRequestKeyValueStore">viewerRequestKeyValueStore</a></code> | <code>aws-cdk-lib.aws_cloudfront.IKeyValueStore</code> | A CloudFront KeyValueStore associated with every viewer-request function {@link viewerRequestFunctionCode} is copied into (up to three, one per kind of behavior), so values it reads — Basic auth credentials, an allowlist — live outside the CloudFormation template and change without a deploy. |
 
 ---
 
@@ -11010,6 +11181,43 @@ Entries (files/directories) within Next.js app's public directory. Used to add s
 
 ---
 
+##### `viewerRequestFunctionCode`<sup>Optional</sup> <a name="viewerRequestFunctionCode" id="cdk-nextjs.OptionalNextjsDistributionProps.property.viewerRequestFunctionCode"></a>
+
+```typescript
+public readonly viewerRequestFunctionCode: FunctionCode;
+```
+
+- *Type:* aws-cdk-lib.aws_cloudfront.FunctionCode
+- *Default:* none
+
+CloudFront Function code run first on every viewer request, on every behavior cdk-nextjs adds, static assets included — HTTP Basic auth on a pre-launch site, geo-gating.
+
+It must define `viewerRequest(event)` (a function, sync or async, or a
+`var`/`let`/`const`): return a response to answer the viewer, or the
+request (or nothing) to carry on. It is spliced into cdk-nextjs's own
+viewer-request functions, ahead of their logic, so it may not use the
+name `handler`, and the combined function must fit CloudFront's 10 KB.
+It runs on `cloudfront-js-2.0`, so it may be async and read
+{@link viewerRequestKeyValueStore} with `cf.kvs()`. A bring-your-own
+{@link distribution}'s default behavior isn't covered.
+
+---
+
+##### `viewerRequestKeyValueStore`<sup>Optional</sup> <a name="viewerRequestKeyValueStore" id="cdk-nextjs.OptionalNextjsDistributionProps.property.viewerRequestKeyValueStore"></a>
+
+```typescript
+public readonly viewerRequestKeyValueStore: IKeyValueStore;
+```
+
+- *Type:* aws-cdk-lib.aws_cloudfront.IKeyValueStore
+- *Default:* none
+
+A CloudFront KeyValueStore associated with every viewer-request function {@link viewerRequestFunctionCode} is copied into (up to three, one per kind of behavior), so values it reads — Basic auth credentials, an allowlist — live outside the CloudFormation template and change without a deploy.
+
+Read it with `cf.kvs()`, no ID needed.
+
+---
+
 ### OptionalNextjsPostDeployProps <a name="OptionalNextjsPostDeployProps" id="cdk-nextjs.OptionalNextjsPostDeployProps"></a>
 
 OptionalNextjsPostDeployProps.

package/README.md

@@ -36,6 +36,17 @@ Deploy [Next.js](https://nextjs.org/) apps on [AWS](https://aws.amazon.com/) wit
 - [Bring Your Own Resources](#bring-your-own-resources) — import existing AWS resources (CloudFront distributions, ECS clusters, ALBs, S3 buckets, DynamoDB tables).
 - [AWS GovCloud (US)](https://aws.amazon.com/govcloud-us) compatible with `NextjsRegionalFunctions` and `NextjsRegionalContainers`.
 
+## Why
+
+The 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.
+
+## Design Principles
+
+- Integrate through Next.js's official interfaces. Build on the [Deployment Adapter](https://nextjs.org/docs/app/guides/deployment-adapters) API and [`@next/routing`](https://www.npmjs.com/package/@next/routing) rather than Next.js internals, so new Next.js versions rarely break this construct. Where no public interface exists yet, the dependency is listed in [Next.js private APIs](docs/nextjs-private-apis.md).
+- Security first.
+- One architecture does not fit all.
+- Enable customization everywhere.
+
 ## Prerequisites
 
 - Next.js app running v16.3 or higher (`next build` fails on older versions). If you don't have one yet - follow [these steps](https://nextjs.org/docs/getting-started) to create one.
@@ -102,6 +113,34 @@ new WebStack(app, "web-stack");
 
 See [examples/](./examples/) for more usage examples.
 
+## Architecture
+
+How requests are served inside the compute — the adapter runtime, and where it deliberately differs from `next start` — is in [docs/adapter-runtime.md](./docs/adapter-runtime.md).
+
+### `NextjsGlobalFunctions`
+
+Architecture 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))
+
+![NextjsGlobalFunctions architecture: User to CloudFront, which serves S3 static assets and forwards to a Lambda function backed by a DynamoDB table and S3 cache bucket](https://raw.githubusercontent.com/cdklabs/cdk-nextjs/main/docs/diagrams/nextjs-global-functions.svg)
+
+### `NextjsGlobalContainers`
+
+Architecture 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))
+
+![NextjsGlobalContainers architecture: User to CloudFront, which serves S3 static assets and forwards to an Application Load Balancer and ECS Fargate containers in a VPC, backed by a DynamoDB table and S3 cache bucket](https://raw.githubusercontent.com/cdklabs/cdk-nextjs/main/docs/diagrams/nextjs-global-containers.svg)
+
+### `NextjsRegionalContainers`
+
+Architecture 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))
+
+![NextjsRegionalContainers architecture: User to an Application Load Balancer and ECS Fargate containers in a VPC, backed by a DynamoDB table and S3 cache bucket](https://raw.githubusercontent.com/cdklabs/cdk-nextjs/main/docs/diagrams/nextjs-regional-containers.svg)
+
+### `NextjsRegionalFunctions`
+
+Architecture 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))
+
+![NextjsRegionalFunctions architecture: User to an API Gateway REST API, which serves S3 static assets and forwards to a Lambda function backed by a DynamoDB table and S3 cache bucket](https://raw.githubusercontent.com/cdklabs/cdk-nextjs/main/docs/diagrams/nextjs-regional-functions.svg)
+
 ## Configuration
 
 The variables below are read at runtime by the cache handler inside your deployed
@@ -415,114 +454,90 @@ Notes:
 - Per-group `overrides` let you size each function independently:
   `{ name: "reports", routes: [...], overrides: { functionProps: { memorySize: 2048 } } }`.
 
-## Architecture
+## Running Code on Every Viewer Request
 
-How requests are served inside the compute — the adapter runtime, and where it deliberately differs from `next start` — is in [docs/adapter-runtime.md](./docs/adapter-runtime.md).
-
-### `NextjsGlobalFunctions`
-
-Architecture 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))
-
-```mermaid
-architecture-beta
-    group aws(cloud)[AWS Cloud]
-    group cache[Cache Layer] in aws
-
-    service user(internet)[User]
-    service cloudfront(server)[CloudFront Distribution] in aws
-    service s3static(disk)[S3 Static Assets] in aws
-    service lambda(server)[Lambda Function] in aws
-    service dynamodb(database)[DynamoDB Table] in cache
-    service s3cache(disk)[S3 Cache Bucket] in cache
-
-    user:R --> L:cloudfront
-    cloudfront:R --> L:s3static
-    cloudfront:R --> L:lambda
-    lambda:R --> L:dynamodb
-    lambda:R --> L:s3cache
-```
-
-### `NextjsGlobalContainers`
-
-Architecture 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))
-
-```mermaid
-architecture-beta
-    group aws(cloud)[AWS Cloud]
-    group vpc[VPC] in aws
-    group cache[Cache Layer] in aws
-
-    service user(internet)[User]
-    service cloudfront(server)[CloudFront Distribution] in aws
-    service s3static(disk)[S3 Static Assets] in aws
-    service alb(server)[Application Load Balancer] in vpc
-    service fargate(server)[ECS Fargate Containers] in vpc
-    service dynamodb(database)[DynamoDB Table] in cache
-    service s3cache(disk)[S3 Cache Bucket] in cache
-
-    user:R --> L:cloudfront
-    cloudfront:R --> L:s3static
-    cloudfront:R --> L:alb
-    alb:R --> L:fargate
-    fargate:R --> L:dynamodb
-    fargate:R --> L:s3cache
-```
-
-### `NextjsRegionalContainers`
+`NextjsGlobalFunctions` and `NextjsGlobalContainers` take a
+`viewerRequestFunctionCode` prop: CloudFront Function code that runs first on
+every request, on every behavior cdk-nextjs adds — pages, API routes,
+`_next/image`, `_next/static` and `public/` files alike. It's the place for a
+gate the whole site has to pass, such as HTTP Basic auth before launch:
 
-Architecture 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))
+```ts
+import { FunctionCode, KeyValueStore } from "aws-cdk-lib/aws-cloudfront";
 
-```mermaid
-architecture-beta
-    group aws(cloud)[AWS Cloud]
-    group vpc[VPC] in aws
-    group cache[Cache Layer] in aws
-
-    service user(internet)[User]
-    service alb(server)[Application Load Balancer] in vpc
-    service fargate(server)[ECS Fargate Containers] in vpc
-    service dynamodb(database)[DynamoDB Table] in cache
-    service s3cache(disk)[S3 Cache Bucket] in cache
-
-    user:R --> L:alb
-    alb:R --> L:fargate
-    fargate:R --> L:dynamodb
-    fargate:R --> L:s3cache
+const credentials = new KeyValueStore(this, "Credentials");
+new NextjsGlobalFunctions(this, "Nextjs", {
+  buildDirectory: join(import.meta.dirname),
+  viewerRequestKeyValueStore: credentials,
+  viewerRequestFunctionCode: FunctionCode.fromInline(`
+    import cf from "cloudfront";
+    const kvs = cf.kvs();
+    async function viewerRequest(event) {
+      const auth = event.request.headers.authorization;
+      try {
+        if (auth && auth.value === "Basic " + (await kvs.get("basic-auth"))) {
+          // verified: don't pass the site's credentials on to the origin
+          delete event.request.headers.authorization;
+          return;
+        }
+      } catch (e) {
+        // no "basic-auth" key yet: stay locked
+      }
+      return {
+        statusCode: 401,
+        statusDescription: "Unauthorized",
+        headers: { "www-authenticate": { value: 'Basic realm="preview"' } },
+      };
+    }
+  `),
+});
 ```
 
-### `NextjsRegionalFunctions`
+Then put the credentials in the store, outside the template:
 
-Architecture 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))
-
-```mermaid
-architecture-beta
-    group aws(cloud)[AWS Cloud]
-    group cache[Cache Layer] in aws
-
-    service user(internet)[User]
-    service apigateway(server)[API Gateway REST API] in aws
-    service s3static(disk)[S3 Static Assets] in aws
-    service lambda(server)[Lambda Function] in aws
-    service dynamodb(database)[DynamoDB Table] in cache
-    service s3cache(disk)[S3 Cache Bucket] in cache
-
-    user:R --> L:apigateway
-    apigateway:R --> L:s3static
-    apigateway:R --> L:lambda
-    lambda:R --> L:dynamodb
-    lambda:R --> L:s3cache
+```sh
+KVS_ARN=... # the store's ARN
+aws cloudfront-keyvaluestore put-key --kvs-arn "$KVS_ARN" \
+  --key basic-auth --value "$(printf 'user:pass' | base64 | tr -d '\n')" \
+  --if-match "$(aws cloudfront-keyvaluestore describe-key-value-store \
+    --kvs-arn "$KVS_ARN" --query ETag --output text)"
 ```
 
-## Why
-
-The 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.
-
-## Design Principles
-
-- Integrate through Next.js's official interfaces. Build on the [Deployment Adapter](https://nextjs.org/docs/app/guides/deployment-adapters) API and [`@next/routing`](https://www.npmjs.com/package/@next/routing) rather than Next.js internals, so new Next.js versions rarely break this construct. Where no public interface exists yet, the dependency is listed in [Next.js private APIs](docs/nextjs-private-apis.md).
-- Security first.
-- One architecture does not fit all.
-- Enable customization everywhere.
+The code must define `viewerRequest(event)`, as a function (`async` or not)
+or a `var`/`let`/`const`. It's a CloudFront Function handler in all but name:
+return a response to answer the viewer, or the request (or nothing) to carry
+on.
+
+Why not a function of your own on viewer-request? CloudFront allows one per
+event type per behavior, and on Global Functions cdk-nextjs's own one
+overwrites `X-Forwarded-Host` and redirects repeated slashes. So your code is
+spliced into that function, ahead of cdk-nextjs's logic, which still runs after
+it, so your code can't undo the `X-Forwarded-Host` overwrite. Middleware can't
+do this instead: on Global Functions CloudFront signs the request to the
+Function URL with the `Authorization` header, and static assets never reach the
+server at all.
+
+- cdk-nextjs's CloudFront Functions run on `cloudfront-js-2.0`, so your code
+  can be `async`, and `import cf from "cloudfront"` works when it comes first,
+  as it does above.
+- `viewerRequestKeyValueStore` is associated with every viewer-request function
+  your code is copied into (up to three, one per kind of behavior), so
+  `cf.kvs()` reads it with no ID wherever the code runs. Credentials written
+  inline in the code instead end up in the CloudFormation template.
+- The combined function, cdk-nextjs's code included, must fit CloudFront's
+  10 KB limit; synth fails if it doesn't (or warns, if the code contains a
+  CDK token, whose size isn't known until deploy).
+- Your code shares the file with cdk-nextjs's `handler`, so it can't use the
+  name `handler` at all, even in a comment or a string; synth refuses it.
+- A viewer-request association in `overrides.*BehaviorOptions.functionAssociations`
+  on a behavior this covers is refused at synth; put that logic in
+  `viewerRequestFunctionCode` instead. So is
+  `overrides.distributionProps.defaultBehavior` without a `basePath`, since it
+  would replace the default behavior the code runs on; customize it through
+  `overrides.dynamicBehaviorOptions`.
+- A bring-your-own `distribution`'s default behavior is yours, so it isn't
+  covered. Only the behaviors cdk-nextjs adds are; under a `basePath`, those
+  include the ones that stand in for the default behavior.
 
 ## Bring Your Own Resources
 
@@ -542,7 +557,7 @@ cdk-nextjs supports importing existing AWS resources instead of creating new one
 ### Resource Isolation
 
 - **Cache bucket and DynamoDB table** must be dedicated to one deployment. Sharing either between deployments (branches, stages, apps) is not supported: each deploy's post-deploy step prunes every cache object and revalidation entry that isn't from its own current build, so deploying one branch wipes the others' caches. Buckets and tables are cheap, so give each deployment its own, or leave `cacheBucket`/`revalidationTable` unset and let cdk-nextjs create them (they are removed with the stack).
-- **Static assets bucket** can be shared, but only between deployments with different `basePath`s, which become their S3 key prefixes. Pruning only looks at `<basePath>/_next/`, so it never touches another prefix. Two deployments under the same prefix (for example two subdomain previews both at the root) overwrite each other's `public/` files and prune each other's `_next/` assets once they are past the prune TTL (30 days by default), so give those their own buckets. `NextjsGlobalFunctions` and `NextjsGlobalContainers` read the `basePath` out of your Next.js build and use it as the S3 key prefix, since CloudFront serves assets from S3 by request path and the two can't differ. Set the `basePath` prop only if you want to be explicit about it; a value that disagrees with your app's fails at synth.
+- **Static assets bucket** can be shared, but only between deployments with different `basePath`s, which become their S3 key prefixes. Pruning only looks at `<basePath>/_next/`, so it never touches another prefix. Two deployments under the same prefix (for example two subdomain previews both at the root) overwrite each other's `public/` files and prune each other's `_next/` assets once they are past the prune TTL (30 days by default), so give those their own buckets. `NextjsGlobalFunctions` and `NextjsGlobalContainers` read the `basePath` out of your Next.js build and use it as the S3 key prefix, since CloudFront serves assets from S3 by request path and the two can't differ. Set the `basePath` prop only if you want to be explicit about it; a value that disagrees with your app's fails at synth. Each deployment also adds an ownership tag per static asset upload (1 to 3, by whether the build has `public/` files and service workers) to a bucket created in your CDK app; an imported bucket gets none. S3 allows 50 tags per bucket, so such a bucket holds at least 16 deployments.
 
 ### Shared ALB and `removeAutoCreatedListener()`
 

package/docs/breaking-changes.md

@@ -1,5 +1,37 @@
 # Breaking Changes
 
+## 0.7.12
+
+### Static assets are uploaded by one deployment per `Cache-Control`
+
+`NextjsStaticAssets` now uploads `_next/static/` with
+`public, max-age=31536000, immutable` and `_next/static/service-worker/` with
+`public, max-age=0, must-revalidate`, the headers Next.js sends for them, and
+`public/` separately. Before, a single `BucketDeployment` uploaded everything
+with no `Cache-Control`. Nothing changes unless you set
+`overrides.nextjsStaticAssets.bucketDeploymentProps` or read
+`NextjsStaticAssets.deployment`:
+
+- **`prune: true` and `retainOnDelete: false` fail synth.** Each override now
+  reaches every upload. `prune: true` would make each one delete the files the
+  others uploaded. With `retainOnDelete: false`, a change of key prefix makes
+  each upload delete the old prefix while the others are writing theirs.
+  **Migration:** drop both. Old assets are already pruned after deploy by
+  `NextjsPostDeploy`, once they are past its TTL (`overrides.nextjsPostDeploy`).
+- **`sources` and `destinationBucket` are ignored.** CDK's type requires them,
+  but either one replaced the build's assets, or sent them to a bucket
+  CloudFront and API Gateway don't read from. **Migration:** pass your bucket
+  as `staticAssetsBucket` instead, and add your own `BucketDeployment` for
+  extra files.
+- **`cacheControl` applies to `public/` files only.** The `_next/static` uploads
+  always keep Next.js's headers.
+- **`NextjsStaticAssets.deployment` is deprecated.** It is now the
+  `_next/static` upload alone (or the first upload the build has), so a
+  dependency on it no longer waits for `public/`. **Migration:** depend on
+  `staticDeployment`, `serviceWorkerDeployment` and `publicDeployment`, each
+  present only when the build has files for it. `NextjsPostDeploy` already
+  waits for all of them.
+
 ## 0.7.0
 
 ### Requests are served through the adapter runtime, not `next start`
@@ -415,8 +447,10 @@ absolute URLs, cached for other viewers). Now:
 
 - associations on other event types (viewer-response, say) are added next to it;
 - an association on viewer-request throws at synth, since CloudFront allows one
-  function per event type per behavior. Move that logic to viewer-response or
-  into middleware.
+  function per event type per behavior. Move that logic into the
+  `viewerRequestFunctionCode` prop, which runs it inside cdk-nextjs's own
+  viewer-request function on every behavior, static assets included (see
+  [Running Code on Every Viewer Request](../README.md#running-code-on-every-viewer-request)).
 
 The runtime trusts `X-Forwarded-Host` only on a request Lambda reports as
 IAM-authenticated, so a Function URL overridden to `authType: NONE` builds its

package/docs/development-guide.md

@@ -66,3 +66,13 @@ Both `build` and `dev` chain it explicitly (`npm run sync-cdk-nextjs && next …
 For iterative development, just run `pnpm build` from the root to rebuild the adapter, then `pnpm build` in the example app—the sync step will copy the latest version.
 
 Note that `pnpm install` recreates the `link:../..` symlink, so always go through `pnpm build` / `pnpm dev`. Invoking `next build` or `next dev` directly skips the sync and Turbopack then fails on the symlinked path, e.g. `FileSystemPath("app-playground").join("./../../lib/adapter/cache-handler.mjs") leaves the filesystem root`.
+
+## Architecture Diagrams
+
+The README's architecture diagrams are Mermaid [`architecture-beta`](https://mermaid.js.org/syntax/architecture.html) sources in [`docs/diagrams/`](./diagrams/), rendered to SVG with AWS icons from the Iconify [`logos`](https://icon-sets.iconify.design/logos/?keyword=aws) set (`logos:aws-lambda`, `logos:aws-cloudfront`, ...). After editing a `.mmd` file:
+
+```bash
+pnpm diagrams
+```
+
+Commit the `.mmd` and the regenerated `.svg` together. `pnpm test` fails if an SVG is stale against its source. The README links the SVGs on `main`, so a PR's README preview shows the old diagrams until it merges; open the SVG in the PR's files view to see the new one.