cdk-nextjs 0.6.2 → 0.7.0

package/lib/root-constructs/nextjs-base-construct.d.ts

@@ -1,3 +1,4 @@
+import { IDistribution } from "aws-cdk-lib/aws-cloudfront";
 import { ITableV2 } from "aws-cdk-lib/aws-dynamodb";
 import { IVpc } from "aws-cdk-lib/aws-ec2";
 import { IBucket } from "aws-cdk-lib/aws-s3";
@@ -5,11 +6,12 @@ import { Construct } from "constructs";
 import { NextjsType } from "../constants";
 import { OptionalNextjsBuildProps } from "../generated-structs/OptionalNextjsBuildProps";
 import { OptionalNextjsCacheProps } from "../generated-structs/OptionalNextjsCacheProps";
+import { OptionalNextjsPostDeployProps } from "../generated-structs/OptionalNextjsPostDeployProps";
 import { NextjsBuild } from "../nextjs-build/nextjs-build";
 import { NextjsCache, NextjsCacheOverrides } from "../nextjs-cache";
 import { NextjsComputeBaseProps } from "../nextjs-compute/nextjs-compute-base-props";
-import { NextjsFunctions, NextjsFunctionsOverrides, NextjsFunctionsProps } from "../nextjs-compute/nextjs-functions";
-import { NextjsImageFunction, NextjsImageFunctionOverrides, NextjsImageFunctionProps } from "../nextjs-compute/nextjs-image-function";
+import { NextjsFunctionGroup, NextjsFunctions } from "../nextjs-compute/nextjs-functions";
+import { NextjsPostDeploy, NextjsPostDeployOverrides } from "../nextjs-post-deploy";
 import { NextjsStaticAssets, NextjsStaticAssetsOverrides, NextjsStaticAssetsProps } from "../nextjs-static-assets";
 /**
  * Base overrides for the props passed to constructs within root/top-level Next.js constructs
@@ -17,22 +19,15 @@ import { NextjsStaticAssets, NextjsStaticAssetsOverrides, NextjsStaticAssetsProp
 export interface NextjsBaseConstructOverrides {
     readonly nextjsBuildProps?: OptionalNextjsBuildProps;
     readonly nextjsCacheProps?: OptionalNextjsCacheProps;
+    readonly nextjsPostDeployProps?: OptionalNextjsPostDeployProps;
     readonly nextjsStaticAssetsProps?: NextjsStaticAssetsProps;
 }
-/**
- * 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.
- */
-export interface NextjsFunctionsConstructOverrides extends NextjsBaseConstructOverrides {
-    readonly nextjsFunctionsProps?: NextjsFunctionsProps;
-    readonly nextjsImageFunctionProps?: NextjsImageFunctionProps;
-}
 /**
  * Base overrides for constructs shared between all root/top-level Next.js constructs.
  */
 export interface NextjsBaseOverrides {
     readonly nextjsCache?: NextjsCacheOverrides;
+    readonly nextjsPostDeploy?: NextjsPostDeployOverrides;
     readonly nextjsStaticAssets?: NextjsStaticAssetsOverrides;
 }
 export interface NextjsBaseProps {
@@ -50,12 +45,18 @@ export interface NextjsBaseProps {
      *   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.
+     * - `NextjsRegionalFunctions`: leave this unset and it follows your app's
+     *   `basePath` minus the prefix API Gateway strips before matching resources —
+     *   the stage (`deployOptions.stageName`, default `prod`), or the base path
+     *   mapping of a custom domain set in `restApiProps.domainName`. So
+     *   `basePath: "/prod"` mounts at the root, `"/prod/base"` under `base`, and
+     *   `"/docs"` behind a custom domain mapped at the root under `docs`. On the
+     *   execute-api endpoint an app `basePath` that doesn't start with the stage
+     *   warns, since its links will miss the stage. If you set this, the app's
+     *   `basePath` must end with it. A domain attached later with
+     *   `addDomainName()` is not seen at synth; set this explicitly then — to
+     *   `"/"` when that domain's base path mapping strips your app's whole
+     *   `basePath`, which mounts every resource at the root.
      * - `NextjsRegionalContainers`: only namespaces the S3 bucket. The ALB sends
      *   every path to the container, which serves its own static assets, so this
      *   is unconstrained.
@@ -76,28 +77,26 @@ export interface NextjsBaseProps {
     readonly buildDirectory: string;
     /**
      * Bring your own S3 bucket for cache storage. When provided, cdk-nextjs
-     * will use this bucket instead of creating a new one. Cache objects are
-     * prefixed with `buildId` so multiple deployments can safely share one bucket.
-     */
-    readonly cacheBucket?: IBucket;
-    /**
-     * Path to API Route Handler that returns HTTP 200 to ensure compute health.
-     * @example "/api/health"
-     * @example
-     * // api/health/route.ts
-     * import { NextResponse } from "next/server";
+     * will use this bucket instead of creating a new one.
      *
-     * export function GET() {
-     *   return NextResponse.json("");
-     * }
+     * The bucket must be dedicated to this one deployment. Don't share it with
+     * another deployment (another branch, stage, or app): every deploy's
+     * post-deploy step deletes every object under a top-level prefix other than
+     * the current `buildId/`, which includes every other deployment's cache.
      */
-    readonly healthCheckPath: string;
+    readonly cacheBucket?: IBucket;
     /**
      * Bring your own DynamoDB table for revalidation metadata. When provided,
      * cdk-nextjs will use this table instead of creating a new one. The table
      * must have `pk` (String) as partition key and `sk` (String) as sort key.
-     * Entries are partitioned by `buildId` so multiple deployments can safely
-     * share one table.
+     * Enable TTL on its `ttl` attribute too: each tag revalidation writes a
+     * revalidation log row that expires through it, and without TTL those rows
+     * accumulate.
+     *
+     * The table must be dedicated to this one deployment. Don't share it with
+     * another deployment (another branch, stage, or app): every deploy's
+     * post-deploy step deletes the entries of the build it last recorded in the
+     * table, which with a shared table is another deployment's live build.
      */
     readonly revalidationTable?: ITableV2;
     /**
@@ -109,7 +108,13 @@ export interface NextjsBaseProps {
     /**
      * Bring your own S3 bucket for static assets. When provided, cdk-nextjs
      * will deploy static assets to this bucket instead of creating a new one.
-     * Use with `basePath` to isolate assets per branch when sharing a bucket.
+     *
+     * Unlike `cacheBucket`, this one can be shared, but only between deployments
+     * with different `basePath`s (so different S3 key prefixes). Pruning only
+     * touches `<basePath>/_next/`, so it leaves the others' assets alone. Two
+     * deployments under the same prefix overwrite each other's `public/` files
+     * and prune each other's `_next/` assets once they are past the prune
+     * TTL (30 days by default).
      */
     readonly staticAssetsBucket?: IBucket;
     /**
@@ -138,7 +143,7 @@ export declare abstract class NextjsBaseConstruct extends Construct {
     abstract get url(): string;
     protected readonly nextjsType: NextjsType;
     protected readonly baseProps: NextjsBaseConstructProps;
-    protected readonly constructOverrides?: NextjsFunctionsConstructOverrides;
+    protected readonly constructOverrides?: NextjsBaseConstructOverrides;
     /**
      * The `basePath` everything downstream is built from: the `basePath` prop when
      * set, otherwise the app's own `basePath` for the `NextjsType`s where the two
@@ -147,52 +152,91 @@ export declare abstract class NextjsBaseConstruct extends Construct {
      */
     protected readonly resolvedBasePath?: string;
     constructor(scope: Construct, id: string, props: NextjsBaseConstructProps, nextjsType: NextjsType);
+    /**
+     * Warns when a path-style `assetPrefix` would 404 every bundle on this
+     * `NextjsType` — see {@link isAssetPrefixUnserved} for which combinations those
+     * are and why a prefix equal to the app's `basePath` is not one of them.
+     *
+     * Warn rather than throw: it is the app's config, the deployment otherwise
+     * works, and an absolute `assetPrefix` (already reduced to `""` by
+     * `relativeAssetPrefix`) is the supported way to serve assets from
+     * elsewhere.
+     */
+    private warnUnservedAssetPrefix;
     /**
      * For the Global `NextjsType`s the key prefix isn't a free choice: it has to be
      * `basePath` (see `resolveBasePath`). A `destinationKeyPrefix` override that
      * moves the objects elsewhere has no way to tell the distribution about it —
-     * unlike the image Lambda and `NextjsApi`, which read
+     * unlike the functions' image optimizer and `NextjsApi`, which read
      * `NextjsStaticAssets.keyPrefix` — so fail at synth rather than 404 every
      * static request.
      */
     private validateStaticAssetsKeyPrefix;
+    /**
+     * The prefix API Gateway will strip, read from the same `restApiProps`
+     * override `NextjsApi` builds its `RestApi` from. Only meaningful for
+     * `REGIONAL_FUNCTIONS`, and read before `NextjsApi` exists because the
+     * resolved `basePath` also decides the static assets' S3 key prefix.
+     *
+     * A domain attached later with `api.addDomainName()` is invisible here, the
+     * same limitation `NextjsApi.url` documents.
+     */
+    private apiGatewayPrefix;
     /**
      * Finds construct overrides (if present) on props for any `NextjsType`
      */
     private getConstructOverrides;
+    /**
+     * `overrides.nextjsFunctions`, which only the two Functions root constructs
+     * declare. Cast for the same reason as {@link functionGroups}.
+     */
+    private get functionsOverrides();
+    /**
+     * `functionGroups`, which only the two Functions root constructs accept —
+     * Containers deploy one task definition and have no 250 MB package limit to
+     * split around.
+     *
+     * Read off `baseProps` with a cast for the same reason as
+     * {@link getConstructOverrides}: `createNextjsBuild` and
+     * `createNextjsFunctions` are shared here, but the prop is declared on the
+     * subclasses, so nothing weaker than a cast can see it. Adding it to
+     * `NextjsBaseProps` would offer it to Containers, where it does nothing.
+     */
+    protected get functionGroups(): NextjsFunctionGroup[] | undefined;
     /**
      * The health check path as the running app actually serves it.
      *
-     * Every consumer of this hits the app directly — the ALB target group forwards
-     * the path to the container unchanged, and the Lambda Web Adapter readiness
-     * check and the container's `wget` probe both target the local server — so the
-     * prefix that matters is the app's own `basePath`, not `resolvedBasePath`
-     * (which for `REGIONAL_FUNCTIONS` omits the stage the app includes, and for
-     * `REGIONAL_CONTAINERS` is only an S3 namespace). Left unprefixed, an app with
-     * a `basePath` 404s every health check, so the target never turns healthy and
-     * the deployment rolls back. `healthCheckPath` is therefore the path as the
-     * app routes it, without `basePath`; one that carries the prefix already gets
-     * it twice, which is the 0.6.0 breaking change for anyone who prefixed by hand
-     * to work around this.
-     */
-    private resolvedHealthCheckPath;
+     * Both consumers of this hit the app directly — the ALB target group forwards
+     * the path to the container unchanged, and the container's `wget` probe targets
+     * the local server — so the prefix that matters is the app's own `basePath`,
+     * not `resolvedBasePath` (which for `REGIONAL_CONTAINERS` is only an S3
+     * namespace). Left unprefixed, an app with a `basePath` 404s every health
+     * check, so the target never turns healthy and the deployment rolls back.
+     * `healthCheckPath` is therefore the path as the app routes it, without
+     * `basePath`; one that carries the prefix already gets it twice, which is the
+     * 0.6.2 breaking change for anyone who prefixed by hand to work around this.
+     *
+     * Takes the path as an argument rather than reading it off `baseProps`: only
+     * the two Containers root constructs declare `healthCheckPath`, since they're
+     * the only ones with something to health-check.
+     */
+    protected resolvedHealthCheckPath(healthCheckPath: string): string;
     /**
      * Get compute base props for both Lambda functions and containers
      */
     protected computeBaseProps(): NextjsComputeBaseProps;
+    /**
+     * Runs after the init cache upload: invalidating the CDN before the new
+     * cache is in place would only re-cache the responses the invalidation was
+     * meant to drop, and CloudFormation infers no ordering between the two
+     * custom resources on its own.
+     */
+    protected createNextjsPostDeploy(distribution?: IDistribution): NextjsPostDeploy;
     private createNextjsBuild;
     private createNextjsCache;
     private createNextjsStaticAssets;
     /**
      * Shared by `NextjsGlobalFunctions` and `NextjsRegionalFunctions`.
      */
-    protected createNextjsFunctions(overrides?: NextjsFunctionsOverrides): NextjsFunctions;
-    /**
-     * Shared by `NextjsGlobalFunctions` and `NextjsRegionalFunctions`, the only
-     * two `NextjsType`s for which `NextjsBuild` produces an image optimization
-     * asset. Only called when the dedicated image optimization Lambda is
-     * enabled, which is what makes the missing-asset check below an invariant
-     * violation rather than a supported configuration.
-     */
-    protected createNextjsImageFunction(overrides?: NextjsImageFunctionOverrides): NextjsImageFunction;
+    protected createNextjsFunctions(): NextjsFunctions;
 }