cdk-nextjs 0.5.16 → 0.6.1

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,6 +486,7 @@ 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. |
@@ -528,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
@@ -1408,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.* |
@@ -1438,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>
@@ -1622,7 +1657,7 @@ 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.* |
@@ -1653,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>
@@ -2609,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.* |
 
@@ -2626,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
@@ -2741,6 +2796,7 @@ const nextjsApiProps: NextjsApiProps = { ... }
 | <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`. |
 
 ---
@@ -2830,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
@@ -2978,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*
@@ -3213,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*
@@ -4032,7 +4152,7 @@ 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`. |
@@ -4086,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>
@@ -4662,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*
@@ -5101,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*
@@ -5290,6 +5461,7 @@ const nextjsImageFunctionProps: NextjsImageFunctionProps = { ... }
 | <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.* |
 
 ---
@@ -5342,6 +5514,23 @@ 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
@@ -5745,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*
@@ -6168,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*
@@ -10899,7 +11134,7 @@ 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`. |
@@ -10932,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>

package/README.md

@@ -281,7 +281,7 @@ cdk-nextjs supports importing existing AWS resources instead of creating new one
 ### Resource Isolation
 
 - **Cache bucket and DynamoDB table** are isolated by `buildId` prefix. Multiple branches safely share one bucket/table with no conflicts.
-- **Static assets bucket** — Next.js includes content hashes in static asset filenames, so different branches deploying the same file will produce identical content. It's safe for branches to overwrite each other. If you're already using `basePath` for routing, assets will naturally be prefixed by it.
+- **Static assets bucket** — Next.js includes content hashes in static asset filenames, so different branches deploying the same file will produce identical content. It's safe for branches to overwrite each other. If you're already using `basePath` for routing, assets will naturally be prefixed by it — `NextjsGlobalFunctions` and `NextjsGlobalContainers` read the `basePath` out of your Next.js build and use it as the S3 key prefix, since CloudFront serves assets from S3 by request path and the two can't differ. Set the `basePath` prop only if you want to be explicit about it; a value that disagrees with your app's fails at synth.
 
 ### Shared ALB and `removeAutoCreatedListener()`
 
@@ -345,7 +345,7 @@ Note: CloudFront distributions take several minutes to create/update, so this ar
 - If using `NextjsGlobalFunctions`, when [revalidating data in Next.js](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation) (i.e. [revalidatePath](https://nextjs.org/docs/app/api-reference/functions/revalidatePath)), the CloudFront Cache will still hold stale data. You'll need to use AWS SDK JS V3 [CreateInvalidationCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-cloudfront/Class/CreateInvalidationCommand/) to manually invalidate the path in CloudFront. See more [here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html).
 - If using `NextjsGlobalFunctions`, setting an Authorization header won't work by default because of Lambda Function URL with IAM Auth is already using the Authorization header. You can use the `AWS_LWA_AUTHORIZATION_SOURCE` environment variable of [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter) to set an alternative Authorization header in the client which will then be set to the Authorization header when it reaches your app.
 - `NextjsRegionalFunctions` streaming depends on whether your server Lambda supports response streaming (e.g. [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter)'s `AWS_LWA_INVOKE_MODE`) — override `overrides.nextjsApi.dynamicIntegrationProps.responseTransferMode` to `BUFFERED` if it doesn't, otherwise API Gateway returns a 500 for every request.
-- If using `NextjsRegionalFunctions` without a custom domain, API Gateway REST APIs require a [stage name](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-stages.html) (default: `/prod`) to be specified. This causes links to pages and static assets to break because they're not prefixed with the stage name. You can work around this issue by specifying [basePath](https://nextjs.org/docs/app/api-reference/config/next-config-js/basePath) in next.config.js as your stage name. Additionally, you'll need to add middleware logic to rewrite requests to include the stage name because API Gateway does not include the stage name in the path passed to Lambda. See [examples/app-playground/middleware.ts](./examples/app-playground/middleware.ts).
+- If using `NextjsRegionalFunctions` without a custom domain, API Gateway REST APIs require a [stage name](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-stages.html) (default: `/prod`) to be specified. This causes links to pages and static assets to break because they're not prefixed with the stage name. You can work around this issue by specifying [basePath](https://nextjs.org/docs/app/api-reference/config/next-config-js/basePath) in next.config.js as your stage name — leave the construct's `basePath` prop unset when you do, since API Gateway strips the stage before matching resources. Additionally, you'll need to add middleware logic to rewrite requests to include the stage name because API Gateway does not include the stage name in the path passed to Lambda. See [examples/app-playground/middleware.ts](./examples/app-playground/middleware.ts). Mapping a custom domain at the root avoids all of this — see [examples/regional-functions/README.md](./examples/regional-functions/README.md#with-a-custom-domain-no-stage-workarounds).
 
 ## Additional Security Recommendations
 

package/docs/breaking-changes.md

@@ -2,6 +2,59 @@
 
 ## 0.6.0
 
+### `basePath` is reconciled with your Next.js app's own `basePath`
+
+The `basePath` prop and the `basePath` in your app's `next.config.js` are two
+different things — where the infrastructure serves the app from (and which S3 key
+prefix the static assets land under) versus the prefix the app emits its own
+links and asset hrefs under. They used to be set independently, which silently
+404'd static assets when they disagreed. They're now checked against each other
+at synth, and derived from the app where there's only one value that can work.
+
+- `NextjsGlobalFunctions` / `NextjsGlobalContainers`: leave the prop unset and it
+  now follows your app's `basePath`. CloudFront hands its S3 origin the request
+  path verbatim as the object key, so the two can't differ — a prop that
+  disagrees with your app throws at synth.
+- `NextjsRegionalFunctions`: the prop is never derived (API Gateway strips the
+  stage before matching resources, so an app served at the `prod` stage sets
+  `basePath: "/prod"` and leaves the prop unset). If you do set it, your app's
+  `basePath` must end with it — either equal to it, or prefixed by the stage or
+  base path mapping API Gateway strips (`basePath: "/prod/base"` with the prop
+  set to `"/base"`). Anything else throws.
+- `NextjsRegionalContainers`: unchanged. The ALB forwards every path to the
+  container, which serves its own static assets, so the prop only namespaces the
+  S3 bucket and is unconstrained.
+- Surrounding slashes on the prop are now normalized away, so `"/base"`,
+  `"base"` and `"/base/"` all behave identically. Previously the prop was passed
+  through to `NextjsDistribution` as written, so a trailing slash produced cache
+  behaviors like `/base//_next/static*` against keys uploaded under
+  `base/_next/...`, and a missing leading slash produced `base/_next/static*`.
+  **If you passed `basePath` without a leading slash**, your distribution's cache
+  behavior path patterns change from `base/…` to `/base/…` on the next deploy.
+  This is an in-place update of the existing distribution, not a replacement.
+- On the Global constructs, an
+  `overrides.nextjsStaticAssets.bucketDeploymentProps.destinationKeyPrefix` that
+  doesn't match `basePath` now throws: CloudFront's S3 origin has no way to ask
+  for the objects anywhere but the request path, so a different prefix 404s every
+  static request.
+- `NextjsGlobalFunctions.url` and `NextjsGlobalContainers.url` now include
+  `basePath`, and `NextjsRegionalFunctions.url` reports the custom domain and
+  base path mapping when one is configured. All three previously returned a URL
+  the app answers with a 404 under these setups.
+
+- **Migration:** If your app sets `basePath` and you deploy a Global construct,
+  either drop the `basePath` prop or set it to the same value your app uses. The
+  first deploy after upgrading uploads the static assets under `<basePath>/` in
+  S3 and adds `<basePath>/_next/static*` (and `<basePath>/*`) cache behaviors to
+  the distribution. If you were reading `url` and appending `basePath` yourself,
+  remove that — it's included now.
+
+Note: when `.next/required-server-files.json` can't be read, cdk-nextjs assumes
+your app sets no `basePath` and now warns rather than staying silent, since that
+fallback is otherwise indistinguishable from an app that genuinely sets none.
+
+## 0.5.16
+
 ### Functions-only overrides moved off the Containers constructs
 
 `nextjsFunctionsProps` and `nextjsImageFunctionProps` moved from

package/docs/development-guide.md

@@ -50,17 +50,19 @@ Expanding Turbopack's root to include the entire monorepo causes it to repeatedl
 
 ### The Solution (Hack)
 
-The `examples/app-playground/package.json` includes a `prebuild` script that copies the necessary files directly into `node_modules` without symlinks:
+The `examples/app-playground/package.json` includes a `sync-cdk-nextjs` script that copies the necessary files directly into `node_modules` without symlinks:
 
 ```json
-"prebuild": "rm -rf node_modules/cdk-nextjs && mkdir -p node_modules/cdk-nextjs/lib/adapter && cp ../../package.json node_modules/cdk-nextjs/package.json && cp ../../lib/adapter/adapter.mjs node_modules/cdk-nextjs/lib/adapter/adapter.mjs && cp ../../lib/adapter/cache-handler.mjs node_modules/cdk-nextjs/lib/adapter/cache-handler.mjs"
+"sync-cdk-nextjs": "rm -rf node_modules/cdk-nextjs && mkdir -p node_modules/cdk-nextjs/lib/adapter && cp ../../package.json node_modules/cdk-nextjs/package.json && cp ../../lib/adapter/adapter.mjs node_modules/cdk-nextjs/lib/adapter/adapter.mjs && cp ../../lib/adapter/cache-handler.mjs node_modules/cdk-nextjs/lib/adapter/cache-handler.mjs"
 ```
 
-This runs automatically before `pnpm build`, ensuring fresh copies of the adapter files are present. While hacky, it:
+Both `build` and `dev` chain it explicitly (`npm run sync-cdk-nextjs && next …`) so the copy happens no matter which package manager invokes them. While hacky, it:
 
 - Avoids symlink issues entirely
 - Keeps Turbopack's root narrow
 - Simulates real npm package installation
 - Enables proper package export resolution
 
-For iterative development, just run `pnpm build` from the root to rebuild the adapter, then `pnpm build` in the example app—prebuild will copy the latest version.
+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`.

package/lib/adapter/adapter.mjs

@@ -1,4 +1,4 @@
-const require = (await import('node:module')).createRequire(import.meta.url);
+import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/lib/adapter/cache-handler.mjs

@@ -1,4 +1,4 @@
-const require = (await import('node:module')).createRequire(import.meta.url);
+import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/lib/generated-structs/OptionalNextjsDistributionProps.d.ts

@@ -34,6 +34,9 @@ export interface OptionalNextjsDistributionProps {
      */
     readonly certificate?: aws_certificatemanager.ICertificate;
     /**
+     * URI path prefix the app is served at.
+     * Surrounding slashes are normalized
+     * away, so "/base", "base" and "/base/" all produce the same cache behaviors.
      * @stability stable
      */
     readonly basePath?: string;

package/lib/generated-structs/OptionalNextjsDistributionProps.js

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiT3B0aW9uYWxOZXh0anNEaXN0cmlidXRpb25Qcm9wcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9nZW5lcmF0ZWQtc3RydWN0cy9PcHRpb25hbE5leHRqc0Rpc3RyaWJ1dGlvblByb3BzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIiLCJzb3VyY2VzQ29udGVudCI6WyIvLyB+fiBHZW5lcmF0ZWQgYnkgcHJvamVuLiBUbyBtb2RpZnksIGVkaXQgLnByb2plbnJjLnRzIGFuZCBydW4gXCJwbnBtIGRseCBwcm9qZW5cIi5cbmltcG9ydCB0eXBlIHsgYXdzX2NlcnRpZmljYXRlbWFuYWdlciwgYXdzX2Nsb3VkZnJvbnQsIGF3c19lbGFzdGljbG9hZGJhbGFuY2luZ3YyLCBhd3NfbGFtYmRhLCBhd3NfczMgfSBmcm9tICdhd3MtY2RrLWxpYic7XG5pbXBvcnQgdHlwZSB7IE5leHRqc1R5cGUsIFB1YmxpY0RpckVudHJ5IH0gZnJvbSAnLi4vJztcblxuLyoqXG4gKiBPcHRpb25hbE5leHRqc0Rpc3RyaWJ1dGlvblByb3BzXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgT3B0aW9uYWxOZXh0anNEaXN0cmlidXRpb25Qcm9wcyB7XG4gIC8qKlxuICAgKiBSZXF1aXJlZCBpZiBgTmV4dGpzVHlwZS5HTE9CQUxfQ09OVEFJTkVSU2Agb3IgYE5leHRqc1R5cGUuUkVHSU9OQUxfQ09OVEFJTkVSU2AuXG4gICAqIEBzdGFiaWxpdHkgc3RhYmxlXG4gICAqL1xuICByZWFkb25seSBsb2FkQmFsYW5jZXI/OiBhd3NfZWxhc3RpY2xvYWRiYWxhbmNpbmd2Mi5JQXBwbGljYXRpb25Mb2FkQmFsYW5jZXI7XG4gIC8qKlxuICAgKiBGdW5jdGlvbiBVUkwgb2YgdGhlIGRlZGljYXRlZCBpbWFnZSBvcHRpbWl6YXRpb24gTGFtYmRhLlxuICAgKiBPbmx5IGFwcGxpY2FibGVcbiAgICogdG8gYE5leHRqc1R5cGUuR0xPQkFMX0ZVTkNUSU9OU2AsIGFuZCBvbmx5IHdoZW4gdGhlIGRlZGljYXRlZCBpbWFnZVxuICAgKiBmdW5jdGlvbiBpcyBlbmFibGVkLiBXaGVuIG9taXR0ZWQsIHRoZSBgX25leHQvaW1hZ2UqYCBiZWhhdmlvciBwb2ludHMgYXRcbiAgICogdGhlIGR5bmFtaWMgb3JpZ2luLCB3aGljaCBzZXJ2ZXMgaW1hZ2Ugb3B0aW1pemF0aW9uIGZyb20gdGhlIE5leHQuanNcbiAgICogc2VydmVyIGl0c2VsZi5cbiAgICogQHN0YWJpbGl0eSBzdGFibGVcbiAgICovXG4gIHJlYWRvbmx5IGltYWdlRnVuY3Rpb25Vcmw/OiBhd3NfbGFtYmRhLklGdW5jdGlvblVybDtcbiAgLyoqXG4gICAqIFJlcXVpcmVkIGlmIGBOZXh0anNUeXBlLkdMT0JBTF9GVU5DVElPTlNgLlxuICAgKiBAc3RhYmlsaXR5IHN0YWJsZVxuICAgKi9cbiAgcmVhZG9ubHkgZnVuY3Rpb25Vcmw/OiBhd3NfbGFtYmRhLklGdW5jdGlvblVybDtcbiAgLyoqXG4gICAqIEBzdGFiaWxpdHkgc3RhYmxlXG4gICAqL1xuICByZWFkb25seSBkaXN0cmlidXRpb24/OiBhd3NfY2xvdWRmcm9udC5EaXN0cmlidXRpb247XG4gIC8qKlxuICAgKiBPcHRpb25hbCBidXQgb25seSBhcHBsaWNhYmxlIGZvciBgTmV4dGpzVHlwZS5HTE9CQUxfQ09OVEFJTkVSU2AuXG4gICAqIEBzdGFiaWxpdHkgc3RhYmxlXG4gICAqL1xuICByZWFkb25seSBjZXJ0aWZpY2F0ZT86IGF3c19jZXJ0aWZpY2F0ZW1hbmFnZXIuSUNlcnRpZmljYXRlO1xuICAvKipcbiAgICogQHN0YWJpbGl0eSBzdGFibGVcbiAgICovXG4gIHJlYWRvbmx5IGJhc2VQYXRoPzogc3RyaW5nO1xuICAvKipcbiAgICogRW50cmllcyAoZmlsZXMvZGlyZWN0b3JpZXMpIHdpdGhpbiBOZXh0LmpzIGFwcCdzIHB1YmxpYyBkaXJlY3RvcnkuIFVzZWQgdG8gYWRkIHN0YXRpYyBiZWhhdmlvcnMgdG8gZGlzdHJpYnV0aW9uLlxuICAgKiBAc3RhYmlsaXR5IHN0YWJsZVxuICAgKi9cbiAgcmVhZG9ubHkgcHVibGljRGlyRW50cmllcz86IEFycmF5PFB1YmxpY0RpckVudHJ5PjtcbiAgLyoqXG4gICAqIEBzdGFiaWxpdHkgc3RhYmxlXG4gICAqL1xuICByZWFkb25seSBuZXh0anNUeXBlPzogTmV4dGpzVHlwZTtcbiAgLyoqXG4gICAqIEJ1Y2tldCBjb250YWluaW5nIHN0YXRpYyBhc3NldHMuXG4gICAqIE11c3QgYmUgcHJvdmlkZWQgaWYgeW91IHdhbnQgdG8gc2VydmUgc3RhdGljIGZpbGVzLlxuICAgKiBAc3RhYmlsaXR5IHN0YWJsZVxuICAgKi9cbiAgcmVhZG9ubHkgYXNzZXRzQnVja2V0PzogYXdzX3MzLklCdWNrZXQ7XG59XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiT3B0aW9uYWxOZXh0anNEaXN0cmlidXRpb25Qcm9wcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9nZW5lcmF0ZWQtc3RydWN0cy9PcHRpb25hbE5leHRqc0Rpc3RyaWJ1dGlvblByb3BzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIiLCJzb3VyY2VzQ29udGVudCI6WyIvLyB+fiBHZW5lcmF0ZWQgYnkgcHJvamVuLiBUbyBtb2RpZnksIGVkaXQgLnByb2plbnJjLnRzIGFuZCBydW4gXCJwbnBtIGRseCBwcm9qZW5cIi5cbmltcG9ydCB0eXBlIHsgYXdzX2NlcnRpZmljYXRlbWFuYWdlciwgYXdzX2Nsb3VkZnJvbnQsIGF3c19lbGFzdGljbG9hZGJhbGFuY2luZ3YyLCBhd3NfbGFtYmRhLCBhd3NfczMgfSBmcm9tICdhd3MtY2RrLWxpYic7XG5pbXBvcnQgdHlwZSB7IE5leHRqc1R5cGUsIFB1YmxpY0RpckVudHJ5IH0gZnJvbSAnLi4vJztcblxuLyoqXG4gKiBPcHRpb25hbE5leHRqc0Rpc3RyaWJ1dGlvblByb3BzXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgT3B0aW9uYWxOZXh0anNEaXN0cmlidXRpb25Qcm9wcyB7XG4gIC8qKlxuICAgKiBSZXF1aXJlZCBpZiBgTmV4dGpzVHlwZS5HTE9CQUxfQ09OVEFJTkVSU2Agb3IgYE5leHRqc1R5cGUuUkVHSU9OQUxfQ09OVEFJTkVSU2AuXG4gICAqIEBzdGFiaWxpdHkgc3RhYmxlXG4gICAqL1xuICByZWFkb25seSBsb2FkQmFsYW5jZXI/OiBhd3NfZWxhc3RpY2xvYWRiYWxhbmNpbmd2Mi5JQXBwbGljYXRpb25Mb2FkQmFsYW5jZXI7XG4gIC8qKlxuICAgKiBGdW5jdGlvbiBVUkwgb2YgdGhlIGRlZGljYXRlZCBpbWFnZSBvcHRpbWl6YXRpb24gTGFtYmRhLlxuICAgKiBPbmx5IGFwcGxpY2FibGVcbiAgICogdG8gYE5leHRqc1R5cGUuR0xPQkFMX0ZVTkNUSU9OU2AsIGFuZCBvbmx5IHdoZW4gdGhlIGRlZGljYXRlZCBpbWFnZVxuICAgKiBmdW5jdGlvbiBpcyBlbmFibGVkLiBXaGVuIG9taXR0ZWQsIHRoZSBgX25leHQvaW1hZ2UqYCBiZWhhdmlvciBwb2ludHMgYXRcbiAgICogdGhlIGR5bmFtaWMgb3JpZ2luLCB3aGljaCBzZXJ2ZXMgaW1hZ2Ugb3B0aW1pemF0aW9uIGZyb20gdGhlIE5leHQuanNcbiAgICogc2VydmVyIGl0c2VsZi5cbiAgICogQHN0YWJpbGl0eSBzdGFibGVcbiAgICovXG4gIHJlYWRvbmx5IGltYWdlRnVuY3Rpb25Vcmw/OiBhd3NfbGFtYmRhLklGdW5jdGlvblVybDtcbiAgLyoqXG4gICAqIFJlcXVpcmVkIGlmIGBOZXh0anNUeXBlLkdMT0JBTF9GVU5DVElPTlNgLlxuICAgKiBAc3RhYmlsaXR5IHN0YWJsZVxuICAgKi9cbiAgcmVhZG9ubHkgZnVuY3Rpb25Vcmw/OiBhd3NfbGFtYmRhLklGdW5jdGlvblVybDtcbiAgLyoqXG4gICAqIEBzdGFiaWxpdHkgc3RhYmxlXG4gICAqL1xuICByZWFkb25seSBkaXN0cmlidXRpb24/OiBhd3NfY2xvdWRmcm9udC5EaXN0cmlidXRpb247XG4gIC8qKlxuICAgKiBPcHRpb25hbCBidXQgb25seSBhcHBsaWNhYmxlIGZvciBgTmV4dGpzVHlwZS5HTE9CQUxfQ09OVEFJTkVSU2AuXG4gICAqIEBzdGFiaWxpdHkgc3RhYmxlXG4gICAqL1xuICByZWFkb25seSBjZXJ0aWZpY2F0ZT86IGF3c19jZXJ0aWZpY2F0ZW1hbmFnZXIuSUNlcnRpZmljYXRlO1xuICAvKipcbiAgICogVVJJIHBhdGggcHJlZml4IHRoZSBhcHAgaXMgc2VydmVkIGF0LlxuICAgKiBTdXJyb3VuZGluZyBzbGFzaGVzIGFyZSBub3JtYWxpemVkXG4gICAqIGF3YXksIHNvIFwiL2Jhc2VcIiwgXCJiYXNlXCIgYW5kIFwiL2Jhc2UvXCIgYWxsIHByb2R1Y2UgdGhlIHNhbWUgY2FjaGUgYmVoYXZpb3JzLlxuICAgKiBAc3RhYmlsaXR5IHN0YWJsZVxuICAgKi9cbiAgcmVhZG9ubHkgYmFzZVBhdGg/OiBzdHJpbmc7XG4gIC8qKlxuICAgKiBFbnRyaWVzIChmaWxlcy9kaXJlY3Rvcmllcykgd2l0aGluIE5leHQuanMgYXBwJ3MgcHVibGljIGRpcmVjdG9yeS4gVXNlZCB0byBhZGQgc3RhdGljIGJlaGF2aW9ycyB0byBkaXN0cmlidXRpb24uXG4gICAqIEBzdGFiaWxpdHkgc3RhYmxlXG4gICAqL1xuICByZWFkb25seSBwdWJsaWNEaXJFbnRyaWVzPzogQXJyYXk8UHVibGljRGlyRW50cnk+O1xuICAvKipcbiAgICogQHN0YWJpbGl0eSBzdGFibGVcbiAgICovXG4gIHJlYWRvbmx5IG5leHRqc1R5cGU/OiBOZXh0anNUeXBlO1xuICAvKipcbiAgICogQnVja2V0IGNvbnRhaW5pbmcgc3RhdGljIGFzc2V0cy5cbiAgICogTXVzdCBiZSBwcm92aWRlZCBpZiB5b3Ugd2FudCB0byBzZXJ2ZSBzdGF0aWMgZmlsZXMuXG4gICAqIEBzdGFiaWxpdHkgc3RhYmxlXG4gICAqL1xuICByZWFkb25seSBhc3NldHNCdWNrZXQ/OiBhd3NfczMuSUJ1Y2tldDtcbn1cbiJdfQ==

package/lib/image-optimization/handler-utils.d.ts

@@ -2,13 +2,15 @@ import { S3Client } from "@aws-sdk/client-s3";
 /**
  * Fetches a non-absolute (local) image referenced by an `<Image>` from S3.
  *
- * `NextjsStaticAssets` uploads under `basePath` as a key prefix, so every key
- * includes it. `url` is inconsistent: next-image-loader bakes `basePath` into
+ * `url` is inconsistent: next-image-loader bakes the app's own `basePath` into
  * the href for statically imported images, while plain string paths are passed
- * through as literally written by the app. So the prefix is normalized to
- * exactly one occurrence rather than simply added or removed.
+ * through as literally written. So `nextBasePath` (the app's config) is stripped
+ * off, then `staticAssetsKeyPrefix` (`NextjsStaticAssets.keyPrefix`) applied.
+ * The two are separate arguments because nothing requires them to be the same
+ * value — e.g. an app whose `basePath` is an API Gateway stage, deployed without
+ * the CDK `basePath` prop.
  */
-export declare function fetchFromS3(s3: S3Client, bucket: string, url: string, basePath: string): Promise<{
+export declare function fetchFromS3(s3: S3Client, bucket: string, url: string, nextBasePath: string, staticAssetsKeyPrefix?: string): Promise<{
     buffer: Buffer;
     contentType: string | null;
     etag: string;