cdk-nextjs 0.5.15 → 0.6.0

package/API.md

@@ -124,6 +124,7 @@ Any object.
 | --- | --- | --- |
 | <code><a href="#cdk-nextjs.NextjsApi.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
 | <code><a href="#cdk-nextjs.NextjsApi.property.api">api</a></code> | <code>aws-cdk-lib.aws_apigateway.RestApi</code> | The API Gateway REST API. |
+| <code><a href="#cdk-nextjs.NextjsApi.property.url">url</a></code> | <code>string</code> | Public URL of the app, including every path segment the API nests it under. |
 
 ---
 
@@ -151,6 +152,25 @@ The API Gateway REST API.
 
 ---
 
+##### `url`<sup>Required</sup> <a name="url" id="cdk-nextjs.NextjsApi.property.url"></a>
+
+```typescript
+public readonly url: string;
+```
+
+- *Type:* string
+
+Public URL of the app, including every path segment the API nests it under.
+
+Prefers a custom domain configured through `overrides.restApiProps.domainName`
+over the execute-api endpoint.
+
+A domain attached after this construct is created (`api.addDomainName()`) is
+still used for the host, but CDK keeps its base path mappings private, so a
+mapping added that way won't show up here.
+
+---
+
 
 ### NextjsBaseConstruct <a name="NextjsBaseConstruct" id="cdk-nextjs.NextjsBaseConstruct"></a>
 
@@ -466,9 +486,11 @@ Any object.
 | <code><a href="#cdk-nextjs.NextjsBuild.property.buildId">buildId</a></code> | <code>string</code> | Unique id for Next.js build. Used to partition cache storage and as metadata for static assets in S3 bucket. |
 | <code><a href="#cdk-nextjs.NextjsBuild.property.dotNextPath">dotNextPath</a></code> | <code>string</code> | Absolute path to the .next directory containing Next.js build artifacts. |
 | <code><a href="#cdk-nextjs.NextjsBuild.property.initCacheDir">initCacheDir</a></code> | <code>string</code> | Absolute path to the init cache directory. |
+| <code><a href="#cdk-nextjs.NextjsBuild.property.nextConfigBasePath">nextConfigBasePath</a></code> | <code>string</code> | 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`. |
 | <code><a href="#cdk-nextjs.NextjsBuild.property.publicDirEntries">publicDirEntries</a></code> | <code><a href="#cdk-nextjs.PublicDirEntry">PublicDirEntry</a>[]</code> | Absolute path to public. |
 | <code><a href="#cdk-nextjs.NextjsBuild.property.relativePathToEntrypoint">relativePathToEntrypoint</a></code> | <code>string</code> | The entrypoint JavaScript file used as an argument for Node.js to run the Next.js standalone server relative to the standalone directory. |
 | <code><a href="#cdk-nextjs.NextjsBuild.property.relativePathToPackage">relativePathToPackage</a></code> | <code>string</code> | Relative path from the standalone directory to the package containing the Next.js app. This is automatically detected from the standalone build output. |
+| <code><a href="#cdk-nextjs.NextjsBuild.property.imageOptimizationAssetPath">imageOptimizationAssetPath</a></code> | <code>string</code> | Absolute path to the directory prepared for the image optimization Lambda asset: bundled handler, glibc `sharp` binaries, and `required-server-files.json`. Only set for {@link NextjsType.GLOBAL_FUNCTIONS} and {@link NextjsType.REGIONAL_FUNCTIONS}, and only when the dedicated image optimization Lambda is enabled. |
 
 ---
 
@@ -527,6 +549,18 @@ Absolute path to the init cache directory.
 ```
 
 
+##### `nextConfigBasePath`<sup>Required</sup> <a name="nextConfigBasePath" id="cdk-nextjs.NextjsBuild.property.nextConfigBasePath"></a>
+
+```typescript
+public readonly nextConfigBasePath: string;
+```
+
+- *Type:* string
+
+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`.
+
+---
+
 ##### `publicDirEntries`<sup>Required</sup> <a name="publicDirEntries" id="cdk-nextjs.NextjsBuild.property.publicDirEntries"></a>
 
 ```typescript
@@ -586,6 +620,18 @@ Relative path from the standalone directory to the package containing the Next.j
 ```
 
 
+##### `imageOptimizationAssetPath`<sup>Optional</sup> <a name="imageOptimizationAssetPath" id="cdk-nextjs.NextjsBuild.property.imageOptimizationAssetPath"></a>
+
+```typescript
+public readonly imageOptimizationAssetPath: string;
+```
+
+- *Type:* string
+
+Absolute path to the directory prepared for the image optimization Lambda asset: bundled handler, glibc `sharp` binaries, and `required-server-files.json`. Only set for {@link NextjsType.GLOBAL_FUNCTIONS} and {@link NextjsType.REGIONAL_FUNCTIONS}, and only when the dedicated image optimization Lambda is enabled.
+
+---
+
 
 ### NextjsCache <a name="NextjsCache" id="cdk-nextjs.NextjsCache"></a>
 
@@ -1395,7 +1441,7 @@ Any object.
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <code><a href="#cdk-nextjs.NextjsGlobalContainers.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
-| <code><a href="#cdk-nextjs.NextjsGlobalContainers.property.url">url</a></code> | <code>string</code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsGlobalContainers.property.url">url</a></code> | <code>string</code> | 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. |
 | <code><a href="#cdk-nextjs.NextjsGlobalContainers.property.nextjsBuild">nextjsBuild</a></code> | <code><a href="#cdk-nextjs.NextjsBuild">NextjsBuild</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalContainers.property.nextjsCache">nextjsCache</a></code> | <code><a href="#cdk-nextjs.NextjsCache">NextjsCache</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalContainers.property.nextjsStaticAssets">nextjsStaticAssets</a></code> | <code><a href="#cdk-nextjs.NextjsStaticAssets">NextjsStaticAssets</a></code> | *No description.* |
@@ -1425,6 +1471,8 @@ public readonly url: string;
 
 - *Type:* string
 
+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.
+
 ---
 
 ##### `nextjsBuild`<sup>Required</sup> <a name="nextjsBuild" id="cdk-nextjs.NextjsGlobalContainers.property.nextjsBuild"></a>
@@ -1609,13 +1657,14 @@ Any object.
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctions.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
-| <code><a href="#cdk-nextjs.NextjsGlobalFunctions.property.url">url</a></code> | <code>string</code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsGlobalFunctions.property.url">url</a></code> | <code>string</code> | 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. |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctions.property.nextjsBuild">nextjsBuild</a></code> | <code><a href="#cdk-nextjs.NextjsBuild">NextjsBuild</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctions.property.nextjsCache">nextjsCache</a></code> | <code><a href="#cdk-nextjs.NextjsCache">NextjsCache</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctions.property.nextjsStaticAssets">nextjsStaticAssets</a></code> | <code><a href="#cdk-nextjs.NextjsStaticAssets">NextjsStaticAssets</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctions.property.nextjsDistribution">nextjsDistribution</a></code> | <code><a href="#cdk-nextjs.NextjsDistribution">NextjsDistribution</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctions.property.nextjsFunctions">nextjsFunctions</a></code> | <code><a href="#cdk-nextjs.NextjsFunctions">NextjsFunctions</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctions.property.nextjsPostDeploy">nextjsPostDeploy</a></code> | <code><a href="#cdk-nextjs.NextjsPostDeploy">NextjsPostDeploy</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsGlobalFunctions.property.nextjsImageFunction">nextjsImageFunction</a></code> | <code><a href="#cdk-nextjs.NextjsImageFunction">NextjsImageFunction</a></code> | Only created when the (experimental, unsupported) dedicated image optimization Lambda is enabled. |
 
 ---
 
@@ -1639,6 +1688,8 @@ public readonly url: string;
 
 - *Type:* string
 
+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.
+
 ---
 
 ##### `nextjsBuild`<sup>Required</sup> <a name="nextjsBuild" id="cdk-nextjs.NextjsGlobalFunctions.property.nextjsBuild"></a>
@@ -1701,6 +1752,180 @@ public readonly nextjsPostDeploy: NextjsPostDeploy;
 
 ---
 
+##### `nextjsImageFunction`<sup>Optional</sup> <a name="nextjsImageFunction" id="cdk-nextjs.NextjsGlobalFunctions.property.nextjsImageFunction"></a>
+
+```typescript
+public readonly nextjsImageFunction: NextjsImageFunction;
+```
+
+- *Type:* <a href="#cdk-nextjs.NextjsImageFunction">NextjsImageFunction</a>
+
+Only created when the (experimental, unsupported) dedicated image optimization Lambda is enabled.
+
+`_next/image` is otherwise served by
+{@link nextjsFunctions}.
+
+---
+
+
+### NextjsImageFunction <a name="NextjsImageFunction" id="cdk-nextjs.NextjsImageFunction"></a>
+
+Dedicated Lambda function for Next.js image optimization (`src/image-optimization/handler.mts`). Kept separate from the server function so image requests get a lightweight, natively-streaming zip Lambda instead of paying the Docker/Lambda Web Adapter cold-start cost.
+
+#### Initializers <a name="Initializers" id="cdk-nextjs.NextjsImageFunction.Initializer"></a>
+
+```typescript
+import { NextjsImageFunction } from 'cdk-nextjs'
+
+new NextjsImageFunction(scope: Construct, id: string, props: NextjsImageFunctionProps)
+```
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#cdk-nextjs.NextjsImageFunction.Initializer.parameter.scope">scope</a></code> | <code>constructs.Construct</code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsImageFunction.Initializer.parameter.id">id</a></code> | <code>string</code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsImageFunction.Initializer.parameter.props">props</a></code> | <code><a href="#cdk-nextjs.NextjsImageFunctionProps">NextjsImageFunctionProps</a></code> | *No description.* |
+
+---
+
+##### `scope`<sup>Required</sup> <a name="scope" id="cdk-nextjs.NextjsImageFunction.Initializer.parameter.scope"></a>
+
+- *Type:* constructs.Construct
+
+---
+
+##### `id`<sup>Required</sup> <a name="id" id="cdk-nextjs.NextjsImageFunction.Initializer.parameter.id"></a>
+
+- *Type:* string
+
+---
+
+##### `props`<sup>Required</sup> <a name="props" id="cdk-nextjs.NextjsImageFunction.Initializer.parameter.props"></a>
+
+- *Type:* <a href="#cdk-nextjs.NextjsImageFunctionProps">NextjsImageFunctionProps</a>
+
+---
+
+#### Methods <a name="Methods" id="Methods"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#cdk-nextjs.NextjsImageFunction.toString">toString</a></code> | Returns a string representation of this construct. |
+| <code><a href="#cdk-nextjs.NextjsImageFunction.with">with</a></code> | Applies one or more mixins to this construct. |
+
+---
+
+##### `toString` <a name="toString" id="cdk-nextjs.NextjsImageFunction.toString"></a>
+
+```typescript
+public toString(): string
+```
+
+Returns a string representation of this construct.
+
+##### `with` <a name="with" id="cdk-nextjs.NextjsImageFunction.with"></a>
+
+```typescript
+public with(mixins: ...IMixin[]): IConstruct
+```
+
+Applies one or more mixins to this construct.
+
+Mixins are applied in order. The list of constructs is captured at the
+start of the call, so constructs added by a mixin will not be visited.
+Use multiple `with()` calls if subsequent mixins should apply to added
+constructs.
+
+###### `mixins`<sup>Required</sup> <a name="mixins" id="cdk-nextjs.NextjsImageFunction.with.parameter.mixins"></a>
+
+- *Type:* ...constructs.IMixin[]
+
+The mixins to apply.
+
+---
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#cdk-nextjs.NextjsImageFunction.isConstruct">isConstruct</a></code> | Checks if `x` is a construct. |
+
+---
+
+##### `isConstruct` <a name="isConstruct" id="cdk-nextjs.NextjsImageFunction.isConstruct"></a>
+
+```typescript
+import { NextjsImageFunction } from 'cdk-nextjs'
+
+NextjsImageFunction.isConstruct(x: any)
+```
+
+Checks if `x` is a construct.
+
+Use this method instead of `instanceof` to properly detect `Construct`
+instances, even when the construct library is symlinked.
+
+Explanation: in JavaScript, multiple copies of the `constructs` library on
+disk are seen as independent, completely different libraries. As a
+consequence, the class `Construct` in each copy of the `constructs` library
+is seen as a different class, and an instance of one class will not test as
+`instanceof` the other class. `npm install` will not create installations
+like this, but users may manually symlink construct libraries together or
+use a monorepo tool: in those cases, multiple copies of the `constructs`
+library can be accidentally installed, and `instanceof` will behave
+unpredictably. It is safest to avoid using `instanceof`, and using
+this type-testing method instead.
+
+###### `x`<sup>Required</sup> <a name="x" id="cdk-nextjs.NextjsImageFunction.isConstruct.parameter.x"></a>
+
+- *Type:* any
+
+Any object.
+
+---
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#cdk-nextjs.NextjsImageFunction.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
+| <code><a href="#cdk-nextjs.NextjsImageFunction.property.function">function</a></code> | <code>aws-cdk-lib.aws_lambda.Function</code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsImageFunction.property.functionUrl">functionUrl</a></code> | <code>aws-cdk-lib.aws_lambda.FunctionUrl</code> | *No description.* |
+
+---
+
+##### `node`<sup>Required</sup> <a name="node" id="cdk-nextjs.NextjsImageFunction.property.node"></a>
+
+```typescript
+public readonly node: Node;
+```
+
+- *Type:* constructs.Node
+
+The tree node.
+
+---
+
+##### `function`<sup>Required</sup> <a name="function" id="cdk-nextjs.NextjsImageFunction.property.function"></a>
+
+```typescript
+public readonly function: Function;
+```
+
+- *Type:* aws-cdk-lib.aws_lambda.Function
+
+---
+
+##### `functionUrl`<sup>Optional</sup> <a name="functionUrl" id="cdk-nextjs.NextjsImageFunction.property.functionUrl"></a>
+
+```typescript
+public readonly functionUrl: FunctionUrl;
+```
+
+- *Type:* aws-cdk-lib.aws_lambda.FunctionUrl
+
+---
+
 
 ### NextjsPostDeploy <a name="NextjsPostDeploy" id="cdk-nextjs.NextjsPostDeploy"></a>
 
@@ -2198,6 +2423,7 @@ Any object.
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctions.property.nextjsApi">nextjsApi</a></code> | <code><a href="#cdk-nextjs.NextjsApi">NextjsApi</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctions.property.nextjsFunctions">nextjsFunctions</a></code> | <code><a href="#cdk-nextjs.NextjsFunctions">NextjsFunctions</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctions.property.nextjsPostDeploy">nextjsPostDeploy</a></code> | <code><a href="#cdk-nextjs.NextjsPostDeploy">NextjsPostDeploy</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsRegionalFunctions.property.nextjsImageFunction">nextjsImageFunction</a></code> | <code><a href="#cdk-nextjs.NextjsImageFunction">NextjsImageFunction</a></code> | Only created when the (experimental, unsupported) dedicated image optimization Lambda is enabled. |
 
 ---
 
@@ -2283,6 +2509,21 @@ public readonly nextjsPostDeploy: NextjsPostDeploy;
 
 ---
 
+##### `nextjsImageFunction`<sup>Optional</sup> <a name="nextjsImageFunction" id="cdk-nextjs.NextjsRegionalFunctions.property.nextjsImageFunction"></a>
+
+```typescript
+public readonly nextjsImageFunction: NextjsImageFunction;
+```
+
+- *Type:* <a href="#cdk-nextjs.NextjsImageFunction">NextjsImageFunction</a>
+
+Only created when the (experimental, unsupported) dedicated image optimization Lambda is enabled.
+
+`_next/image` is otherwise served by
+{@link nextjsFunctions}.
+
+---
+
 
 ### NextjsStaticAssets <a name="NextjsStaticAssets" id="cdk-nextjs.NextjsStaticAssets"></a>
 
@@ -2405,6 +2646,7 @@ Any object.
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <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.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.* |
 
@@ -2422,6 +2664,23 @@ The tree node.
 
 ---
 
+##### `keyPrefix`<sup>Required</sup> <a name="keyPrefix" id="cdk-nextjs.NextjsStaticAssets.property.keyPrefix"></a>
+
+```typescript
+public readonly keyPrefix: string;
+```
+
+- *Type:* string
+
+S3 key prefix the assets are actually uploaded under, normalized to a bare path segment (empty when they live at the bucket root).
+
+Consumers that read assets back out of the bucket (the image optimization
+Lambda, `NextjsApi`'s S3 integrations) must use this rather than the
+`basePath` prop, since `overrides.bucketDeploymentProps` can replace the
+prefix outright.
+
+---
+
 ##### `bucket`<sup>Required</sup> <a name="bucket" id="cdk-nextjs.NextjsStaticAssets.property.bucket"></a>
 
 ```typescript
@@ -2460,6 +2719,7 @@ const nextjsApiOverrides: NextjsApiOverrides = { ... }
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <code><a href="#cdk-nextjs.NextjsApiOverrides.property.dynamicIntegrationProps">dynamicIntegrationProps</a></code> | <code>aws-cdk-lib.aws_apigateway.LambdaIntegrationOptions</code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsApiOverrides.property.imageIntegrationProps">imageIntegrationProps</a></code> | <code>aws-cdk-lib.aws_apigateway.LambdaIntegrationOptions</code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsApiOverrides.property.restApiProps">restApiProps</a></code> | <code>aws-cdk-lib.aws_apigateway.RestApiProps</code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsApiOverrides.property.s3MethodOptions">s3MethodOptions</a></code> | <code>aws-cdk-lib.aws_apigateway.MethodOptions</code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsApiOverrides.property.staticIntegrationProps">staticIntegrationProps</a></code> | <code>aws-cdk-lib.aws_apigateway.AwsIntegrationProps</code> | *No description.* |
@@ -2476,6 +2736,16 @@ public readonly dynamicIntegrationProps: LambdaIntegrationOptions;
 
 ---
 
+##### `imageIntegrationProps`<sup>Optional</sup> <a name="imageIntegrationProps" id="cdk-nextjs.NextjsApiOverrides.property.imageIntegrationProps"></a>
+
+```typescript
+public readonly imageIntegrationProps: LambdaIntegrationOptions;
+```
+
+- *Type:* aws-cdk-lib.aws_apigateway.LambdaIntegrationOptions
+
+---
+
 ##### `restApiProps`<sup>Optional</sup> <a name="restApiProps" id="cdk-nextjs.NextjsApiOverrides.property.restApiProps"></a>
 
 ```typescript
@@ -2523,8 +2793,10 @@ const nextjsApiProps: NextjsApiProps = { ... }
 | <code><a href="#cdk-nextjs.NextjsApiProps.property.publicDirEntries">publicDirEntries</a></code> | <code><a href="#cdk-nextjs.PublicDirEntry">PublicDirEntry</a>[]</code> | Path to directory of Next.js app's public directory. Used to add resources to API Gateway REST API for public directory to go directly to S3. |
 | <code><a href="#cdk-nextjs.NextjsApiProps.property.staticAssetsBucket">staticAssetsBucket</a></code> | <code>aws-cdk-lib.aws_s3.IBucket</code> | The S3 bucket containing static assets. |
 | <code><a href="#cdk-nextjs.NextjsApiProps.property.basePath">basePath</a></code> | <code>string</code> | Optional base path for the application. |
+| <code><a href="#cdk-nextjs.NextjsApiProps.property.imageFunction">imageFunction</a></code> | <code>aws-cdk-lib.aws_lambda.IFunction</code> | Dedicated image optimization Lambda for the `_next/image` route. |
 | <code><a href="#cdk-nextjs.NextjsApiProps.property.overrides">overrides</a></code> | <code><a href="#cdk-nextjs.NextjsApiOverrides">NextjsApiOverrides</a></code> | Override props for every construct. |
 | <code><a href="#cdk-nextjs.NextjsApiProps.property.serverFunction">serverFunction</a></code> | <code>aws-cdk-lib.aws_lambda.IFunction</code> | Required if `NextjsRegionalFunctions`. |
+| <code><a href="#cdk-nextjs.NextjsApiProps.property.staticAssetsKeyPrefix">staticAssetsKeyPrefix</a></code> | <code>string</code> | S3 key prefix the static assets were uploaded under, i.e. `NextjsStaticAssets.keyPrefix`, which namespaces a shared bucket. |
 | <code><a href="#cdk-nextjs.NextjsApiProps.property.vpc">vpc</a></code> | <code>aws-cdk-lib.aws_ec2.IVpc</code> | [Future] Required if `NextjsRegionalContainers`. |
 
 ---
@@ -2565,6 +2837,29 @@ Optional base path for the application.
 
 ---
 
+##### `imageFunction`<sup>Optional</sup> <a name="imageFunction" id="cdk-nextjs.NextjsApiProps.property.imageFunction"></a>
+
+```typescript
+public readonly imageFunction: IFunction;
+```
+
+- *Type:* aws-cdk-lib.aws_lambda.IFunction
+
+Dedicated image optimization Lambda for the `_next/image` route.
+
+When
+omitted, no `_next/image` resource is created and those requests fall
+through to `serverFunction` via the `{proxy+}` catch-all.
+
+When provided, it is assumed to support Lambda response streaming (as the
+dedicated image Lambda this package builds does) and is invoked with
+`ResponseTransferMode.STREAM` accordingly. If you supply a custom
+`imageFunction` that doesn't support streaming, override
+`responseTransferMode` to `BUFFERED` via `overrides.imageIntegrationProps`,
+otherwise API Gateway returns a 502.
+
+---
+
 ##### `overrides`<sup>Optional</sup> <a name="overrides" id="cdk-nextjs.NextjsApiProps.property.overrides"></a>
 
 ```typescript
@@ -2591,6 +2886,24 @@ The Lambda function for server-side rendering
 
 ---
 
+##### `staticAssetsKeyPrefix`<sup>Optional</sup> <a name="staticAssetsKeyPrefix" id="cdk-nextjs.NextjsApiProps.property.staticAssetsKeyPrefix"></a>
+
+```typescript
+public readonly staticAssetsKeyPrefix: string;
+```
+
+- *Type:* string
+
+S3 key prefix the static assets were uploaded under, i.e. `NextjsStaticAssets.keyPrefix`, which namespaces a shared bucket.
+
+Independent of `basePath` above: that one is the URL prefix the REST API
+serves the app at (commonly the API Gateway stage), while this one is where
+the objects live in the bucket. `_next/static` and public directory
+requests are mapped to S3 keys directly, so they 404 unless this prefix is
+applied.
+
+---
+
 ##### `vpc`<sup>Optional</sup> <a name="vpc" id="cdk-nextjs.NextjsApiProps.property.vpc"></a>
 
 ```typescript
@@ -2739,6 +3052,29 @@ public readonly basePath: string;
 
 Prefix to the URI path the app will be served at.
 
+Also namespaces the
+static assets in S3, so it doubles as a way to host multiple apps or
+branches out of one bucket.
+
+How this relates to the `basePath` in your app's `next.config.js` depends
+on the construct, and synth fails on a combination that can't serve the
+app:
+
+- `NextjsGlobalFunctions`/`NextjsGlobalContainers`: leave this unset and it
+  follows your app's `basePath`, which is what you want — CloudFront serves
+  static assets from S3 using the request path as the object key, so the two
+  have to be identical and a mismatch 404s all of them. Setting a different
+  value throws.
+- `NextjsRegionalFunctions`: if you set this, the app's `basePath` must end
+  with it — either equal to it, or prefixed by the stage or base path
+  mapping API Gateway strips before matching resources (`basePath:
+  "/prod/base"` with this set to `"/base"`). Leaving it unset while the app
+  sets one is correct and common — an app served at the default `prod` stage
+  sets `basePath: "/prod"` and leaves this alone.
+- `NextjsRegionalContainers`: only namespaces the S3 bucket. The ALB sends
+  every path to the container, which serves its own static assets, so this
+  is unconstrained.
+
 ---
 
 *Example*
@@ -2974,6 +3310,29 @@ public readonly basePath: string;
 
 Prefix to the URI path the app will be served at.
 
+Also namespaces the
+static assets in S3, so it doubles as a way to host multiple apps or
+branches out of one bucket.
+
+How this relates to the `basePath` in your app's `next.config.js` depends
+on the construct, and synth fails on a combination that can't serve the
+app:
+
+- `NextjsGlobalFunctions`/`NextjsGlobalContainers`: leave this unset and it
+  follows your app's `basePath`, which is what you want — CloudFront serves
+  static assets from S3 using the request path as the object key, so the two
+  have to be identical and a mismatch 404s all of them. Setting a different
+  value throws.
+- `NextjsRegionalFunctions`: if you set this, the app's `basePath` must end
+  with it — either equal to it, or prefixed by the stage or base path
+  mapping API Gateway strips before matching resources (`basePath:
+  "/prod/base"` with this set to `"/base"`). Leaving it unset while the app
+  sets one is correct and common — an app served at the default `prod` stage
+  sets `basePath: "/prod"` and leaves this alone.
+- `NextjsRegionalContainers`: only namespaces the S3 bucket. The ALB sends
+  every path to the container, which serves its own static assets, so this
+  is unconstrained.
+
 ---
 
 *Example*
@@ -3638,6 +3997,7 @@ const nextjsDistributionOverrides: NextjsDistributionOverrides = { ... }
 | <code><a href="#cdk-nextjs.NextjsDistributionOverrides.property.dynamicVpcOriginWithEndpointProps">dynamicVpcOriginWithEndpointProps</a></code> | <code>aws-cdk-lib.aws_cloudfront_origins.VpcOriginWithEndpointProps</code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsDistributionOverrides.property.imageBehaviorOptions">imageBehaviorOptions</a></code> | <code>aws-cdk-lib.aws_cloudfront.AddBehaviorOptions</code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsDistributionOverrides.property.imageCachePolicyProps">imageCachePolicyProps</a></code> | <code>aws-cdk-lib.aws_cloudfront.CachePolicyProps</code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsDistributionOverrides.property.imageFunctionUrlOriginWithOACProps">imageFunctionUrlOriginWithOACProps</a></code> | <code>aws-cdk-lib.aws_cloudfront_origins.FunctionUrlOriginWithOACProps</code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsDistributionOverrides.property.imageResponseHeadersPolicyProps">imageResponseHeadersPolicyProps</a></code> | <code>aws-cdk-lib.aws_cloudfront.ResponseHeadersPolicyProps</code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsDistributionOverrides.property.s3BucketOriginProps">s3BucketOriginProps</a></code> | <code><a href="#cdk-nextjs.OptionalS3OriginBucketWithOACProps">OptionalS3OriginBucketWithOACProps</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsDistributionOverrides.property.staticBehaviorOptions">staticBehaviorOptions</a></code> | <code>aws-cdk-lib.aws_cloudfront.AddBehaviorOptions</code> | *No description.* |
@@ -3725,6 +4085,16 @@ public readonly imageCachePolicyProps: CachePolicyProps;
 
 ---
 
+##### `imageFunctionUrlOriginWithOACProps`<sup>Optional</sup> <a name="imageFunctionUrlOriginWithOACProps" id="cdk-nextjs.NextjsDistributionOverrides.property.imageFunctionUrlOriginWithOACProps"></a>
+
+```typescript
+public readonly imageFunctionUrlOriginWithOACProps: FunctionUrlOriginWithOACProps;
+```
+
+- *Type:* aws-cdk-lib.aws_cloudfront_origins.FunctionUrlOriginWithOACProps
+
+---
+
 ##### `imageResponseHeadersPolicyProps`<sup>Optional</sup> <a name="imageResponseHeadersPolicyProps" id="cdk-nextjs.NextjsDistributionOverrides.property.imageResponseHeadersPolicyProps"></a>
 
 ```typescript
@@ -3782,10 +4152,11 @@ const nextjsDistributionProps: NextjsDistributionProps = { ... }
 | <code><a href="#cdk-nextjs.NextjsDistributionProps.property.assetsBucket">assetsBucket</a></code> | <code>aws-cdk-lib.aws_s3.IBucket</code> | Bucket containing static assets. |
 | <code><a href="#cdk-nextjs.NextjsDistributionProps.property.nextjsType">nextjsType</a></code> | <code><a href="#cdk-nextjs.NextjsType">NextjsType</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsDistributionProps.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.NextjsDistributionProps.property.basePath">basePath</a></code> | <code>string</code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsDistributionProps.property.basePath">basePath</a></code> | <code>string</code> | URI path prefix the app is served at. |
 | <code><a href="#cdk-nextjs.NextjsDistributionProps.property.certificate">certificate</a></code> | <code>aws-cdk-lib.aws_certificatemanager.ICertificate</code> | Optional but only applicable for `NextjsType.GLOBAL_CONTAINERS`. |
 | <code><a href="#cdk-nextjs.NextjsDistributionProps.property.distribution">distribution</a></code> | <code>aws-cdk-lib.aws_cloudfront.Distribution</code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsDistributionProps.property.functionUrl">functionUrl</a></code> | <code>aws-cdk-lib.aws_lambda.IFunctionUrl</code> | Required if `NextjsType.GLOBAL_FUNCTIONS`. |
+| <code><a href="#cdk-nextjs.NextjsDistributionProps.property.imageFunctionUrl">imageFunctionUrl</a></code> | <code>aws-cdk-lib.aws_lambda.IFunctionUrl</code> | Function URL of the dedicated image optimization Lambda. |
 | <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.overrides">overrides</a></code> | <code><a href="#cdk-nextjs.NextjsDistributionOverrides">NextjsDistributionOverrides</a></code> | Override props for every construct. |
 
@@ -3835,6 +4206,11 @@ public readonly basePath: string;
 
 - *Type:* string
 
+URI path prefix the app is served at.
+
+Surrounding slashes are normalized
+away, so "/base", "base" and "/base/" all produce the same cache behaviors.
+
 ---
 
 ##### `certificate`<sup>Optional</sup> <a name="certificate" id="cdk-nextjs.NextjsDistributionProps.property.certificate"></a>
@@ -3871,6 +4247,24 @@ Required if `NextjsType.GLOBAL_FUNCTIONS`.
 
 ---
 
+##### `imageFunctionUrl`<sup>Optional</sup> <a name="imageFunctionUrl" id="cdk-nextjs.NextjsDistributionProps.property.imageFunctionUrl"></a>
+
+```typescript
+public readonly imageFunctionUrl: IFunctionUrl;
+```
+
+- *Type:* aws-cdk-lib.aws_lambda.IFunctionUrl
+
+Function URL of the dedicated image optimization Lambda.
+
+Only applicable
+to `NextjsType.GLOBAL_FUNCTIONS`, and only when the dedicated image
+function is enabled. When omitted, the `_next/image*` behavior points at
+the dynamic origin, which serves image optimization from the Next.js
+server itself.
+
+---
+
 ##### `loadBalancer`<sup>Optional</sup> <a name="loadBalancer" id="cdk-nextjs.NextjsDistributionProps.property.loadBalancer"></a>
 
 ```typescript
@@ -3895,6 +4289,84 @@ Override props for every construct.
 
 ---
 
+### NextjsFunctionsConstructOverrides <a name="NextjsFunctionsConstructOverrides" id="cdk-nextjs.NextjsFunctionsConstructOverrides"></a>
+
+Adds the overrides that only apply to the two Functions `NextjsType`s.
+
+The
+Containers types serve `_next/image` from the standalone server itself and
+have no Lambda functions to configure, so they would silently ignore these.
+
+#### Initializer <a name="Initializer" id="cdk-nextjs.NextjsFunctionsConstructOverrides.Initializer"></a>
+
+```typescript
+import { NextjsFunctionsConstructOverrides } from 'cdk-nextjs'
+
+const nextjsFunctionsConstructOverrides: NextjsFunctionsConstructOverrides = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#cdk-nextjs.NextjsFunctionsConstructOverrides.property.nextjsBuildProps">nextjsBuildProps</a></code> | <code><a href="#cdk-nextjs.OptionalNextjsBuildProps">OptionalNextjsBuildProps</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsFunctionsConstructOverrides.property.nextjsCacheProps">nextjsCacheProps</a></code> | <code><a href="#cdk-nextjs.OptionalNextjsCacheProps">OptionalNextjsCacheProps</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsFunctionsConstructOverrides.property.nextjsStaticAssetsProps">nextjsStaticAssetsProps</a></code> | <code><a href="#cdk-nextjs.NextjsStaticAssetsProps">NextjsStaticAssetsProps</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsFunctionsConstructOverrides.property.nextjsFunctionsProps">nextjsFunctionsProps</a></code> | <code><a href="#cdk-nextjs.NextjsFunctionsProps">NextjsFunctionsProps</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsFunctionsConstructOverrides.property.nextjsImageFunctionProps">nextjsImageFunctionProps</a></code> | <code><a href="#cdk-nextjs.NextjsImageFunctionProps">NextjsImageFunctionProps</a></code> | *No description.* |
+
+---
+
+##### `nextjsBuildProps`<sup>Optional</sup> <a name="nextjsBuildProps" id="cdk-nextjs.NextjsFunctionsConstructOverrides.property.nextjsBuildProps"></a>
+
+```typescript
+public readonly nextjsBuildProps: OptionalNextjsBuildProps;
+```
+
+- *Type:* <a href="#cdk-nextjs.OptionalNextjsBuildProps">OptionalNextjsBuildProps</a>
+
+---
+
+##### `nextjsCacheProps`<sup>Optional</sup> <a name="nextjsCacheProps" id="cdk-nextjs.NextjsFunctionsConstructOverrides.property.nextjsCacheProps"></a>
+
+```typescript
+public readonly nextjsCacheProps: OptionalNextjsCacheProps;
+```
+
+- *Type:* <a href="#cdk-nextjs.OptionalNextjsCacheProps">OptionalNextjsCacheProps</a>
+
+---
+
+##### `nextjsStaticAssetsProps`<sup>Optional</sup> <a name="nextjsStaticAssetsProps" id="cdk-nextjs.NextjsFunctionsConstructOverrides.property.nextjsStaticAssetsProps"></a>
+
+```typescript
+public readonly nextjsStaticAssetsProps: NextjsStaticAssetsProps;
+```
+
+- *Type:* <a href="#cdk-nextjs.NextjsStaticAssetsProps">NextjsStaticAssetsProps</a>
+
+---
+
+##### `nextjsFunctionsProps`<sup>Optional</sup> <a name="nextjsFunctionsProps" id="cdk-nextjs.NextjsFunctionsConstructOverrides.property.nextjsFunctionsProps"></a>
+
+```typescript
+public readonly nextjsFunctionsProps: NextjsFunctionsProps;
+```
+
+- *Type:* <a href="#cdk-nextjs.NextjsFunctionsProps">NextjsFunctionsProps</a>
+
+---
+
+##### `nextjsImageFunctionProps`<sup>Optional</sup> <a name="nextjsImageFunctionProps" id="cdk-nextjs.NextjsFunctionsConstructOverrides.property.nextjsImageFunctionProps"></a>
+
+```typescript
+public readonly nextjsImageFunctionProps: NextjsImageFunctionProps;
+```
+
+- *Type:* <a href="#cdk-nextjs.NextjsImageFunctionProps">NextjsImageFunctionProps</a>
+
+---
+
 ### NextjsFunctionsOverrides <a name="NextjsFunctionsOverrides" id="cdk-nextjs.NextjsFunctionsOverrides"></a>
 
 #### Initializer <a name="Initializer" id="cdk-nextjs.NextjsFunctionsOverrides.Initializer"></a>
@@ -4315,6 +4787,29 @@ public readonly basePath: string;
 
 Prefix to the URI path the app will be served at.
 
+Also namespaces the
+static assets in S3, so it doubles as a way to host multiple apps or
+branches out of one bucket.
+
+How this relates to the `basePath` in your app's `next.config.js` depends
+on the construct, and synth fails on a combination that can't serve the
+app:
+
+- `NextjsGlobalFunctions`/`NextjsGlobalContainers`: leave this unset and it
+  follows your app's `basePath`, which is what you want — CloudFront serves
+  static assets from S3 using the request path as the object key, so the two
+  have to be identical and a mismatch 404s all of them. Setting a different
+  value throws.
+- `NextjsRegionalFunctions`: if you set this, the app's `basePath` must end
+  with it — either equal to it, or prefixed by the stage or base path
+  mapping API Gateway strips before matching resources (`basePath:
+  "/prod/base"` with this set to `"/base"`). Leaving it unset while the app
+  sets one is correct and common — an app served at the default `prod` stage
+  sets `basePath: "/prod"` and leaves this alone.
+- `NextjsRegionalContainers`: only namespaces the S3 bucket. The ALB sends
+  every path to the container, which serves its own static assets, so this
+  is unconstrained.
+
 ---
 
 *Example*
@@ -4496,8 +4991,9 @@ const nextjsGlobalFunctionsConstructOverrides: NextjsGlobalFunctionsConstructOve
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsBuildProps">nextjsBuildProps</a></code> | <code><a href="#cdk-nextjs.OptionalNextjsBuildProps">OptionalNextjsBuildProps</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsCacheProps">nextjsCacheProps</a></code> | <code><a href="#cdk-nextjs.OptionalNextjsCacheProps">OptionalNextjsCacheProps</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsStaticAssetsProps">nextjsStaticAssetsProps</a></code> | <code><a href="#cdk-nextjs.NextjsStaticAssetsProps">NextjsStaticAssetsProps</a></code> | *No description.* |
-| <code><a href="#cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsDistributionProps">nextjsDistributionProps</a></code> | <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps">OptionalNextjsDistributionProps</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsFunctionsProps">nextjsFunctionsProps</a></code> | <code><a href="#cdk-nextjs.NextjsFunctionsProps">NextjsFunctionsProps</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsImageFunctionProps">nextjsImageFunctionProps</a></code> | <code><a href="#cdk-nextjs.NextjsImageFunctionProps">NextjsImageFunctionProps</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsDistributionProps">nextjsDistributionProps</a></code> | <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps">OptionalNextjsDistributionProps</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsPostDeployProps">nextjsPostDeployProps</a></code> | <code><a href="#cdk-nextjs.OptionalNextjsPostDeployProps">OptionalNextjsPostDeployProps</a></code> | *No description.* |
 
 ---
@@ -4532,23 +5028,33 @@ public readonly nextjsStaticAssetsProps: NextjsStaticAssetsProps;
 
 ---
 
-##### `nextjsDistributionProps`<sup>Optional</sup> <a name="nextjsDistributionProps" id="cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsDistributionProps"></a>
+##### `nextjsFunctionsProps`<sup>Optional</sup> <a name="nextjsFunctionsProps" id="cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsFunctionsProps"></a>
 
 ```typescript
-public readonly nextjsDistributionProps: OptionalNextjsDistributionProps;
+public readonly nextjsFunctionsProps: NextjsFunctionsProps;
 ```
 
-- *Type:* <a href="#cdk-nextjs.OptionalNextjsDistributionProps">OptionalNextjsDistributionProps</a>
+- *Type:* <a href="#cdk-nextjs.NextjsFunctionsProps">NextjsFunctionsProps</a>
 
 ---
 
-##### `nextjsFunctionsProps`<sup>Optional</sup> <a name="nextjsFunctionsProps" id="cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsFunctionsProps"></a>
+##### `nextjsImageFunctionProps`<sup>Optional</sup> <a name="nextjsImageFunctionProps" id="cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsImageFunctionProps"></a>
 
 ```typescript
-public readonly nextjsFunctionsProps: NextjsFunctionsProps;
+public readonly nextjsImageFunctionProps: NextjsImageFunctionProps;
 ```
 
-- *Type:* <a href="#cdk-nextjs.NextjsFunctionsProps">NextjsFunctionsProps</a>
+- *Type:* <a href="#cdk-nextjs.NextjsImageFunctionProps">NextjsImageFunctionProps</a>
+
+---
+
+##### `nextjsDistributionProps`<sup>Optional</sup> <a name="nextjsDistributionProps" id="cdk-nextjs.NextjsGlobalFunctionsConstructOverrides.property.nextjsDistributionProps"></a>
+
+```typescript
+public readonly nextjsDistributionProps: OptionalNextjsDistributionProps;
+```
+
+- *Type:* <a href="#cdk-nextjs.OptionalNextjsDistributionProps">OptionalNextjsDistributionProps</a>
 
 ---
 
@@ -4587,6 +5093,7 @@ const nextjsGlobalFunctionsOverrides: NextjsGlobalFunctionsOverrides = { ... }
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsOverrides.property.nextjsDistribution">nextjsDistribution</a></code> | <code><a href="#cdk-nextjs.NextjsDistributionOverrides">NextjsDistributionOverrides</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsOverrides.property.nextjsFunctions">nextjsFunctions</a></code> | <code><a href="#cdk-nextjs.NextjsFunctionsOverrides">NextjsFunctionsOverrides</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsOverrides.property.nextjsGlobalFunctions">nextjsGlobalFunctions</a></code> | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsConstructOverrides">NextjsGlobalFunctionsConstructOverrides</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsGlobalFunctionsOverrides.property.nextjsImageFunction">nextjsImageFunction</a></code> | <code><a href="#cdk-nextjs.NextjsImageFunctionOverrides">NextjsImageFunctionOverrides</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsGlobalFunctionsOverrides.property.nextjsPostDeploy">nextjsPostDeploy</a></code> | <code><a href="#cdk-nextjs.NextjsPostDeployOverrides">NextjsPostDeployOverrides</a></code> | *No description.* |
 
 ---
@@ -4641,6 +5148,16 @@ public readonly nextjsGlobalFunctions: NextjsGlobalFunctionsConstructOverrides;
 
 ---
 
+##### `nextjsImageFunction`<sup>Optional</sup> <a name="nextjsImageFunction" id="cdk-nextjs.NextjsGlobalFunctionsOverrides.property.nextjsImageFunction"></a>
+
+```typescript
+public readonly nextjsImageFunction: NextjsImageFunctionOverrides;
+```
+
+- *Type:* <a href="#cdk-nextjs.NextjsImageFunctionOverrides">NextjsImageFunctionOverrides</a>
+
+---
+
 ##### `nextjsPostDeploy`<sup>Optional</sup> <a name="nextjsPostDeploy" id="cdk-nextjs.NextjsGlobalFunctionsOverrides.property.nextjsPostDeploy"></a>
 
 ```typescript
@@ -4732,6 +5249,29 @@ public readonly basePath: string;
 
 Prefix to the URI path the app will be served at.
 
+Also namespaces the
+static assets in S3, so it doubles as a way to host multiple apps or
+branches out of one bucket.
+
+How this relates to the `basePath` in your app's `next.config.js` depends
+on the construct, and synth fails on a combination that can't serve the
+app:
+
+- `NextjsGlobalFunctions`/`NextjsGlobalContainers`: leave this unset and it
+  follows your app's `basePath`, which is what you want — CloudFront serves
+  static assets from S3 using the request path as the object key, so the two
+  have to be identical and a mismatch 404s all of them. Setting a different
+  value throws.
+- `NextjsRegionalFunctions`: if you set this, the app's `basePath` must end
+  with it — either equal to it, or prefixed by the stage or base path
+  mapping API Gateway strips before matching resources (`basePath:
+  "/prod/base"` with this set to `"/base"`). Leaving it unset while the app
+  sets one is correct and common — an app served at the default `prod` stage
+  sets `basePath: "/prod"` and leaves this alone.
+- `NextjsRegionalContainers`: only namespaces the S3 bucket. The ALB sends
+  every path to the container, which serves its own static assets, so this
+  is unconstrained.
+
 ---
 
 *Example*
@@ -4864,6 +5404,143 @@ Override props of any construct.
 
 ---
 
+### NextjsImageFunctionOverrides <a name="NextjsImageFunctionOverrides" id="cdk-nextjs.NextjsImageFunctionOverrides"></a>
+
+#### Initializer <a name="Initializer" id="cdk-nextjs.NextjsImageFunctionOverrides.Initializer"></a>
+
+```typescript
+import { NextjsImageFunctionOverrides } from 'cdk-nextjs'
+
+const nextjsImageFunctionOverrides: NextjsImageFunctionOverrides = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#cdk-nextjs.NextjsImageFunctionOverrides.property.functionProps">functionProps</a></code> | <code><a href="#cdk-nextjs.OptionalFunctionProps">OptionalFunctionProps</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsImageFunctionOverrides.property.functionUrlProps">functionUrlProps</a></code> | <code><a href="#cdk-nextjs.OptionalFunctionUrlProps">OptionalFunctionUrlProps</a></code> | *No description.* |
+
+---
+
+##### `functionProps`<sup>Optional</sup> <a name="functionProps" id="cdk-nextjs.NextjsImageFunctionOverrides.property.functionProps"></a>
+
+```typescript
+public readonly functionProps: OptionalFunctionProps;
+```
+
+- *Type:* <a href="#cdk-nextjs.OptionalFunctionProps">OptionalFunctionProps</a>
+
+---
+
+##### `functionUrlProps`<sup>Optional</sup> <a name="functionUrlProps" id="cdk-nextjs.NextjsImageFunctionOverrides.property.functionUrlProps"></a>
+
+```typescript
+public readonly functionUrlProps: OptionalFunctionUrlProps;
+```
+
+- *Type:* <a href="#cdk-nextjs.OptionalFunctionUrlProps">OptionalFunctionUrlProps</a>
+
+---
+
+### NextjsImageFunctionProps <a name="NextjsImageFunctionProps" id="cdk-nextjs.NextjsImageFunctionProps"></a>
+
+#### Initializer <a name="Initializer" id="cdk-nextjs.NextjsImageFunctionProps.Initializer"></a>
+
+```typescript
+import { NextjsImageFunctionProps } from 'cdk-nextjs'
+
+const nextjsImageFunctionProps: NextjsImageFunctionProps = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#cdk-nextjs.NextjsImageFunctionProps.property.imageOptimizationAssetPath">imageOptimizationAssetPath</a></code> | <code>string</code> | Absolute path to the asset prepared by `NextjsBuild`: bundled handler, glibc `sharp` binaries, and `required-server-files.json`. |
+| <code><a href="#cdk-nextjs.NextjsImageFunctionProps.property.nextjsType">nextjsType</a></code> | <code><a href="#cdk-nextjs.NextjsType">NextjsType</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsImageFunctionProps.property.staticAssetsBucket">staticAssetsBucket</a></code> | <code>aws-cdk-lib.aws_s3.IBucket</code> | S3 bucket containing static assets, read by the handler to serve non-absolute image URLs. |
+| <code><a href="#cdk-nextjs.NextjsImageFunctionProps.property.overrides">overrides</a></code> | <code><a href="#cdk-nextjs.NextjsImageFunctionOverrides">NextjsImageFunctionOverrides</a></code> | Override props of any construct. |
+| <code><a href="#cdk-nextjs.NextjsImageFunctionProps.property.staticAssetsKeyPrefix">staticAssetsKeyPrefix</a></code> | <code>string</code> | S3 key prefix the static assets were uploaded under, i.e. `NextjsStaticAssets.keyPrefix`, which namespaces a shared bucket. |
+| <code><a href="#cdk-nextjs.NextjsImageFunctionProps.property.vpc">vpc</a></code> | <code>aws-cdk-lib.aws_ec2.IVpc</code> | *No description.* |
+
+---
+
+##### `imageOptimizationAssetPath`<sup>Required</sup> <a name="imageOptimizationAssetPath" id="cdk-nextjs.NextjsImageFunctionProps.property.imageOptimizationAssetPath"></a>
+
+```typescript
+public readonly imageOptimizationAssetPath: string;
+```
+
+- *Type:* string
+
+Absolute path to the asset prepared by `NextjsBuild`: bundled handler, glibc `sharp` binaries, and `required-server-files.json`.
+
+> [{@link NextjsBuild.imageOptimizationAssetPath }]({@link NextjsBuild.imageOptimizationAssetPath })
+
+---
+
+##### `nextjsType`<sup>Required</sup> <a name="nextjsType" id="cdk-nextjs.NextjsImageFunctionProps.property.nextjsType"></a>
+
+```typescript
+public readonly nextjsType: NextjsType;
+```
+
+- *Type:* <a href="#cdk-nextjs.NextjsType">NextjsType</a>
+
+---
+
+##### `staticAssetsBucket`<sup>Required</sup> <a name="staticAssetsBucket" id="cdk-nextjs.NextjsImageFunctionProps.property.staticAssetsBucket"></a>
+
+```typescript
+public readonly staticAssetsBucket: IBucket;
+```
+
+- *Type:* aws-cdk-lib.aws_s3.IBucket
+
+S3 bucket containing static assets, read by the handler to serve non-absolute image URLs.
+
+---
+
+##### `overrides`<sup>Optional</sup> <a name="overrides" id="cdk-nextjs.NextjsImageFunctionProps.property.overrides"></a>
+
+```typescript
+public readonly overrides: NextjsImageFunctionOverrides;
+```
+
+- *Type:* <a href="#cdk-nextjs.NextjsImageFunctionOverrides">NextjsImageFunctionOverrides</a>
+
+Override props of any construct.
+
+---
+
+##### `staticAssetsKeyPrefix`<sup>Optional</sup> <a name="staticAssetsKeyPrefix" id="cdk-nextjs.NextjsImageFunctionProps.property.staticAssetsKeyPrefix"></a>
+
+```typescript
+public readonly staticAssetsKeyPrefix: string;
+```
+
+- *Type:* string
+
+S3 key prefix the static assets were uploaded under, i.e. `NextjsStaticAssets.keyPrefix`, which namespaces a shared bucket.
+
+Threaded through explicitly rather than read from the app's bundled config,
+because it's distinct from the app's own `basePath` (which next-image-loader
+bakes into hrefs) — the two diverge when the app's `basePath` comes from
+elsewhere, e.g. an API Gateway stage under `NextjsRegionalFunctions`.
+
+---
+
+##### `vpc`<sup>Optional</sup> <a name="vpc" id="cdk-nextjs.NextjsImageFunctionProps.property.vpc"></a>
+
+```typescript
+public readonly vpc: IVpc;
+```
+
+- *Type:* aws-cdk-lib.aws_ec2.IVpc
+
+---
+
 ### NextjsPostDeployOverrides <a name="NextjsPostDeployOverrides" id="cdk-nextjs.NextjsPostDeployOverrides"></a>
 
 #### Initializer <a name="Initializer" id="cdk-nextjs.NextjsPostDeployOverrides.Initializer"></a>
@@ -5257,6 +5934,29 @@ public readonly basePath: string;
 
 Prefix to the URI path the app will be served at.
 
+Also namespaces the
+static assets in S3, so it doubles as a way to host multiple apps or
+branches out of one bucket.
+
+How this relates to the `basePath` in your app's `next.config.js` depends
+on the construct, and synth fails on a combination that can't serve the
+app:
+
+- `NextjsGlobalFunctions`/`NextjsGlobalContainers`: leave this unset and it
+  follows your app's `basePath`, which is what you want — CloudFront serves
+  static assets from S3 using the request path as the object key, so the two
+  have to be identical and a mismatch 404s all of them. Setting a different
+  value throws.
+- `NextjsRegionalFunctions`: if you set this, the app's `basePath` must end
+  with it — either equal to it, or prefixed by the stage or base path
+  mapping API Gateway strips before matching resources (`basePath:
+  "/prod/base"` with this set to `"/base"`). Leaving it unset while the app
+  sets one is correct and common — an app served at the default `prod` stage
+  sets `basePath: "/prod"` and leaves this alone.
+- `NextjsRegionalContainers`: only namespaces the S3 bucket. The ALB sends
+  every path to the container, which serves its own static assets, so this
+  is unconstrained.
+
 ---
 
 *Example*
@@ -5423,8 +6123,9 @@ const nextjsRegionalFunctionsConstructOverrides: NextjsRegionalFunctionsConstruc
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsBuildProps">nextjsBuildProps</a></code> | <code><a href="#cdk-nextjs.OptionalNextjsBuildProps">OptionalNextjsBuildProps</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsCacheProps">nextjsCacheProps</a></code> | <code><a href="#cdk-nextjs.OptionalNextjsCacheProps">OptionalNextjsCacheProps</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsStaticAssetsProps">nextjsStaticAssetsProps</a></code> | <code><a href="#cdk-nextjs.NextjsStaticAssetsProps">NextjsStaticAssetsProps</a></code> | *No description.* |
-| <code><a href="#cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsApiProps">nextjsApiProps</a></code> | <code><a href="#cdk-nextjs.NextjsApiProps">NextjsApiProps</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsFunctionsProps">nextjsFunctionsProps</a></code> | <code><a href="#cdk-nextjs.NextjsFunctionsProps">NextjsFunctionsProps</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsImageFunctionProps">nextjsImageFunctionProps</a></code> | <code><a href="#cdk-nextjs.NextjsImageFunctionProps">NextjsImageFunctionProps</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsApiProps">nextjsApiProps</a></code> | <code><a href="#cdk-nextjs.NextjsApiProps">NextjsApiProps</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsPostDeployProps">nextjsPostDeployProps</a></code> | <code><a href="#cdk-nextjs.OptionalNextjsPostDeployProps">OptionalNextjsPostDeployProps</a></code> | *No description.* |
 
 ---
@@ -5459,23 +6160,33 @@ public readonly nextjsStaticAssetsProps: NextjsStaticAssetsProps;
 
 ---
 
-##### `nextjsApiProps`<sup>Optional</sup> <a name="nextjsApiProps" id="cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsApiProps"></a>
+##### `nextjsFunctionsProps`<sup>Optional</sup> <a name="nextjsFunctionsProps" id="cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsFunctionsProps"></a>
 
 ```typescript
-public readonly nextjsApiProps: NextjsApiProps;
+public readonly nextjsFunctionsProps: NextjsFunctionsProps;
 ```
 
-- *Type:* <a href="#cdk-nextjs.NextjsApiProps">NextjsApiProps</a>
+- *Type:* <a href="#cdk-nextjs.NextjsFunctionsProps">NextjsFunctionsProps</a>
 
 ---
 
-##### `nextjsFunctionsProps`<sup>Optional</sup> <a name="nextjsFunctionsProps" id="cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsFunctionsProps"></a>
+##### `nextjsImageFunctionProps`<sup>Optional</sup> <a name="nextjsImageFunctionProps" id="cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsImageFunctionProps"></a>
 
 ```typescript
-public readonly nextjsFunctionsProps: NextjsFunctionsProps;
+public readonly nextjsImageFunctionProps: NextjsImageFunctionProps;
 ```
 
-- *Type:* <a href="#cdk-nextjs.NextjsFunctionsProps">NextjsFunctionsProps</a>
+- *Type:* <a href="#cdk-nextjs.NextjsImageFunctionProps">NextjsImageFunctionProps</a>
+
+---
+
+##### `nextjsApiProps`<sup>Optional</sup> <a name="nextjsApiProps" id="cdk-nextjs.NextjsRegionalFunctionsConstructOverrides.property.nextjsApiProps"></a>
+
+```typescript
+public readonly nextjsApiProps: NextjsApiProps;
+```
+
+- *Type:* <a href="#cdk-nextjs.NextjsApiProps">NextjsApiProps</a>
 
 ---
 
@@ -5513,6 +6224,7 @@ const nextjsRegionalFunctionsOverrides: NextjsRegionalFunctionsOverrides = { ...
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctionsOverrides.property.nextjsStaticAssets">nextjsStaticAssets</a></code> | <code><a href="#cdk-nextjs.NextjsStaticAssetsOverrides">NextjsStaticAssetsOverrides</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctionsOverrides.property.nextjsApi">nextjsApi</a></code> | <code><a href="#cdk-nextjs.NextjsApiOverrides">NextjsApiOverrides</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctionsOverrides.property.nextjsFunctions">nextjsFunctions</a></code> | <code><a href="#cdk-nextjs.NextjsFunctionsOverrides">NextjsFunctionsOverrides</a></code> | *No description.* |
+| <code><a href="#cdk-nextjs.NextjsRegionalFunctionsOverrides.property.nextjsImageFunction">nextjsImageFunction</a></code> | <code><a href="#cdk-nextjs.NextjsImageFunctionOverrides">NextjsImageFunctionOverrides</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctionsOverrides.property.nextjsPostDeploy">nextjsPostDeploy</a></code> | <code><a href="#cdk-nextjs.NextjsPostDeployOverrides">NextjsPostDeployOverrides</a></code> | *No description.* |
 | <code><a href="#cdk-nextjs.NextjsRegionalFunctionsOverrides.property.nextjsRegionalFunctions">nextjsRegionalFunctions</a></code> | <code><a href="#cdk-nextjs.NextjsRegionalFunctionsConstructOverrides">NextjsRegionalFunctionsConstructOverrides</a></code> | *No description.* |
 
@@ -5558,6 +6270,16 @@ public readonly nextjsFunctions: NextjsFunctionsOverrides;
 
 ---
 
+##### `nextjsImageFunction`<sup>Optional</sup> <a name="nextjsImageFunction" id="cdk-nextjs.NextjsRegionalFunctionsOverrides.property.nextjsImageFunction"></a>
+
+```typescript
+public readonly nextjsImageFunction: NextjsImageFunctionOverrides;
+```
+
+- *Type:* <a href="#cdk-nextjs.NextjsImageFunctionOverrides">NextjsImageFunctionOverrides</a>
+
+---
+
 ##### `nextjsPostDeploy`<sup>Optional</sup> <a name="nextjsPostDeploy" id="cdk-nextjs.NextjsRegionalFunctionsOverrides.property.nextjsPostDeploy"></a>
 
 ```typescript
@@ -5658,6 +6380,29 @@ public readonly basePath: string;
 
 Prefix to the URI path the app will be served at.
 
+Also namespaces the
+static assets in S3, so it doubles as a way to host multiple apps or
+branches out of one bucket.
+
+How this relates to the `basePath` in your app's `next.config.js` depends
+on the construct, and synth fails on a combination that can't serve the
+app:
+
+- `NextjsGlobalFunctions`/`NextjsGlobalContainers`: leave this unset and it
+  follows your app's `basePath`, which is what you want — CloudFront serves
+  static assets from S3 using the request path as the object key, so the two
+  have to be identical and a mismatch 404s all of them. Setting a different
+  value throws.
+- `NextjsRegionalFunctions`: if you set this, the app's `basePath` must end
+  with it — either equal to it, or prefixed by the stage or base path
+  mapping API Gateway strips before matching resources (`basePath:
+  "/prod/base"` with this set to `"/base"`). Leaving it unset while the app
+  sets one is correct and common — an app served at the default `prod` stage
+  sets `basePath: "/prod"` and leaves this alone.
+- `NextjsRegionalContainers`: only namespaces the S3 bucket. The ALB sends
+  every path to the container, which serves its own static assets, so this
+  is unconstrained.
+
 ---
 
 *Example*
@@ -10389,10 +11134,11 @@ const optionalNextjsDistributionProps: OptionalNextjsDistributionProps = { ... }
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.property.assetsBucket">assetsBucket</a></code> | <code>aws-cdk-lib.aws_s3.IBucket</code> | Bucket containing static assets. |
-| <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.property.basePath">basePath</a></code> | <code>string</code> | *No description.* |
+| <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.property.basePath">basePath</a></code> | <code>string</code> | URI path prefix the app is served at. |
 | <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.property.certificate">certificate</a></code> | <code>aws-cdk-lib.aws_certificatemanager.ICertificate</code> | Optional but only applicable for `NextjsType.GLOBAL_CONTAINERS`. |
 | <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.property.distribution">distribution</a></code> | <code>aws-cdk-lib.aws_cloudfront.Distribution</code> | *No description.* |
 | <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.property.functionUrl">functionUrl</a></code> | <code>aws-cdk-lib.aws_lambda.IFunctionUrl</code> | Required if `NextjsType.GLOBAL_FUNCTIONS`. |
+| <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.property.imageFunctionUrl">imageFunctionUrl</a></code> | <code>aws-cdk-lib.aws_lambda.IFunctionUrl</code> | Function URL of the dedicated image optimization Lambda. |
 | <code><a href="#cdk-nextjs.OptionalNextjsDistributionProps.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.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. |
@@ -10421,6 +11167,11 @@ public readonly basePath: string;
 
 - *Type:* string
 
+URI path prefix the app is served at.
+
+Surrounding slashes are normalized
+away, so "/base", "base" and "/base/" all produce the same cache behaviors.
+
 ---
 
 ##### `certificate`<sup>Optional</sup> <a name="certificate" id="cdk-nextjs.OptionalNextjsDistributionProps.property.certificate"></a>
@@ -10457,6 +11208,24 @@ Required if `NextjsType.GLOBAL_FUNCTIONS`.
 
 ---
 
+##### `imageFunctionUrl`<sup>Optional</sup> <a name="imageFunctionUrl" id="cdk-nextjs.OptionalNextjsDistributionProps.property.imageFunctionUrl"></a>
+
+```typescript
+public readonly imageFunctionUrl: IFunctionUrl;
+```
+
+- *Type:* aws-cdk-lib.aws_lambda.IFunctionUrl
+
+Function URL of the dedicated image optimization Lambda.
+
+Only applicable
+to `NextjsType.GLOBAL_FUNCTIONS`, and only when the dedicated image
+function is enabled. When omitted, the `_next/image*` behavior points at
+the dynamic origin, which serves image optimization from the Next.js
+server itself.
+
+---
+
 ##### `loadBalancer`<sup>Optional</sup> <a name="loadBalancer" id="cdk-nextjs.OptionalNextjsDistributionProps.property.loadBalancer"></a>
 
 ```typescript