cdk-nextjs 0.6.1 → 0.7.0

package/lib/nextjs-build/global-containers.Dockerfile

@@ -1,4 +1,7 @@
 # ~~ Generated by cdk-nextjs ~~
+# cdk-nextjs rewrites any Dockerfile carrying the line above, so that an
+# upgrade does not leave a stale one behind. To own this file yourself, delete
+# that line and cdk-nextjs will leave the rest of it alone.
 # Modified from: https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile
 
 # Production image, copy all the files and run next
@@ -14,13 +17,15 @@ ENV NODE_ENV=production
 RUN addgroup --system --gid 1001 nodejs
 RUN adduser --system --uid 1001 nextjs
 
-ARG RELATIVE_PATH_TO_PACKAGE
-# Copy from local build output instead of builder image
-COPY --chown=nextjs:nodejs .next/standalone ./
-# Copy .next/static so image optimization can read imported images (e.g. /_next/static/media/*)
-COPY --chown=nextjs:nodejs .next/static ./$RELATIVE_PATH_TO_PACKAGE/.next/static
-# Copy public directory for image optimization (Next.js needs source images)
-COPY --chown=nextjs:nodejs public ./$RELATIVE_PATH_TO_PACKAGE/public
+# The deployment root cdk-nextjs staged during `next build`: the traced assets of
+# every built output, keyed by repo-root-relative path, plus cdk-nextjs's own
+# request-handling server under cdk-nextjs-runtime/. Replaces `.next/standalone`.
+COPY --chown=nextjs:nodejs .next/cdk-nextjs-adapter/app ./
+# `.next/static` and `public` are not copied in: they are in S3, and CloudFront
+# routes their paths there. A request that reaches the server for a `public/`
+# file anyway (a rewrite onto it) is read from S3, using the list of `public/`
+# cdk-nextjs staged in cdk-nextjs-runtime/public-files.json. Image optimization
+# reads its sources from S3 as well.
 
 USER nextjs
 
@@ -28,8 +33,8 @@ EXPOSE 3000
 
 ENV PORT=3000
 
-# server.js is created by next build from the standalone output
-# https://nextjs.org/docs/pages/api-reference/next-config-js/output
+# cdk-nextjs's own server, staged above. It invokes the entrypoints `next build`
+# produced in-process; there is no `next start` and no server.js.
 # CMD will be overwritten by ECS Task Definition
 ENV HOSTNAME="0.0.0.0"
-CMD ["node" "server.js"]
+CMD ["node", "cdk-nextjs-runtime/server.mjs"]

package/lib/nextjs-build/nextjs-build.d.ts

@@ -1,3 +1,5 @@
+import { Dirent } from "node:fs";
+import { Architecture } from "aws-cdk-lib/aws-lambda";
 import { Construct } from "constructs";
 import { NextjsType } from "../constants";
 import { NextjsBaseProps } from "../root-constructs/nextjs-base-construct";
@@ -16,7 +18,76 @@ export interface NextjsBuildProps {
      * @see {@link NextjsBaseProps.skipBuild}
      */
     readonly skipBuild?: boolean;
+    /**
+     * Route groups to package into separate Lambda functions. Only the two
+     * Functions `NextjsType`s pass this; see `NextjsFunctionGroup`.
+     */
+    readonly functionGroups?: NextjsFunctionGroupRoutes[];
+    /**
+     * Lambda architecture the Functions types deploy, which decides the `sharp`
+     * binaries staged into the deployment roots. Ignored by the Containers
+     * types, whose image is built for the synth machine.
+     * @default - the architecture of the machine running synth
+     */
+    readonly architecture?: Architecture;
+}
+/**
+ * The part of a function group `NextjsBuild` needs: which routes it owns. The
+ * per-group Lambda `overrides` are `NextjsFunctions`' business.
+ */
+export interface NextjsFunctionGroupRoutes {
+    readonly name: string;
+    readonly routes: string[];
+}
+/** One staged deployment root, and the function group it belongs to. */
+export interface NextjsDeploymentRoot {
+    /**
+     * Group name, `default` for the implicit group that owns every unassigned
+     * route. The only entry is `default` when `functionGroups` is not used.
+     */
+    readonly name: string;
+    /** Absolute path to the deployment root: the Lambda zip asset's source. */
+    readonly path: string;
+    /**
+     * Route templates this root's package holds, as the adapter assigned them.
+     * Empty is legal: the default group still serves `/_next/image`, the static
+     * files the runtime reads off disk, and anything the catch-all routes to it.
+     */
+    readonly routes: string[];
+}
+/**
+ * One behavior that routes a function group's URLs to it, as the adapter
+ * checked them against what each group was packaged with.
+ */
+export interface NextjsFunctionGroupBehavior {
+    /** The function group the behavior routes to. */
+    readonly group: string;
+    /**
+     * The group pattern it came from (`/blog/**`), or the parent of an optional
+     * catch-all a subtree pattern moved into the group (`/blog` for
+     * `/blog/[[...slug]]`), which that subtree's behavior does not match.
+     */
+    readonly route: string;
+    /**
+     * The CloudFront path pattern, before basePath and without a leading slash:
+     * `blog/*`, `pricing`, `pricing/` for a `trailingSlash` app, and
+     * `_next/data/<buildId>/blog/*` for a group owning a Pages Router page.
+     */
+    readonly pattern: string;
 }
+/**
+ * What every deployment root is staged for: the build's `architecture`, else
+ * the synth machine's. Containers ignore it: Docker builds their image
+ * natively, so it can only match the synth machine.
+ */
+export declare function deploymentArchitecture(props: NextjsBuildProps): Architecture;
+/** {@link NextjsBuild.buildId}: Next.js's build ID, suffixed with the app's `deploymentId`. */
+export declare function deploymentBuildId(manifest: {
+    readonly buildId: string;
+    readonly config: {
+        readonly deploymentId: string;
+    };
+}): string;
 export interface PublicDirEntry {
     readonly name: string;
     readonly isDirectory: boolean;
@@ -27,8 +98,24 @@ export interface PublicDirEntry {
  */
 export declare class NextjsBuild extends Construct {
     /**
-     * Unique id for Next.js build. Used to partition cache storage and as
+     * Unique id for this deployment. Used to partition cache storage and as
      * metadata for static assets in S3 bucket.
+     *
+     * Next.js's build ID, suffixed with the app's `deploymentId` when it sets
+     * one. The build ID alone is not unique per deployment: setting
+     * `deploymentId` (or building with `NEXT_DEPLOYMENT_ID`) turns on skew
+     * protection, and next.js then *pins* the build ID to the constant
+     * `build-TfctsWXpff2fKS` — see `getBuildId` in `next/dist/build/index.js`,
+     * which does that deliberately so that tooling doing
+     * `.replace(escapedBuildId, …)` still has something to replace. Two
+     * successive deployments of such an app would share one cache prefix and one
+     * revalidation-table partition, and the new one would read the previous
+     * one's prerenders. Appending the deployment ID restores the "one
+     * deployment, one partition" invariant that ID exists to carry.
+     *
+     * Nothing routes on this value — the `/_next/data/<buildId>/…` URL space is
+     * routed on Next.js's own build ID, which is what the app's client bundles
+     * carry — so it is free to be longer than next.js's own.
      */
     buildId: string;
     /**
@@ -42,111 +129,213 @@ export declare class NextjsBuild extends Construct {
      */
     publicDirEntries: PublicDirEntry[];
     /**
-     * The entrypoint JavaScript file used as an argument for Node.js to run the
-     * Next.js standalone server relative to the standalone directory.
-     * @example "./server.js"
-     * @example "./packages/ui/server.js" (monorepo)
+     * The JavaScript file Node.js runs to serve requests, relative to the
+     * deployment root. cdk-nextjs's own container shell, not `next build` output,
+     * so it is the same path for every app.
+     * @example "cdk-nextjs-runtime/server.mjs"
      */
     relativePathToEntrypoint: string;
-    /**
-     * Relative path from the standalone directory to the package containing the Next.js app.
-     * This is automatically detected from the standalone build output.
-     * @example "." for non-monorepo apps
-     * @example "./apps/web" for monorepo apps
-     */
-    relativePathToPackage: string;
     /**
      * Absolute path to the .next directory containing Next.js build artifacts
      */
     dotNextPath: 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
+     * asset hrefs under — as the adapter manifest recorded it. 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`.
      */
     nextConfigBasePath: 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.
+     * The Next.js app's own `assetPrefix`, as a path with a leading slash and no
+     * trailing one, empty when the app sets none or sets an absolute URL (which
+     * names an origin cdk-nextjs does not serve).
+     *
+     * Exposed because it is the shape of `assetPrefix` the regional
+     * `NextjsType`s cannot serve — see `warnUnservedAssetPrefix`. What the
+     * distribution has to answer on is {@link nextConfigAssetPrefixPath}, which
+     * also covers the path an absolute prefix carries.
+     */
+    nextConfigAssetPrefix: string;
+    /**
+     * The path portion of the app's `assetPrefix`, whichever form it takes: "/cdn"
+     * for both `assetPrefix: "/cdn"` and `assetPrefix:
+     * "https://cdn.example.com/cdn"`, empty when there is no path to answer on.
+     *
+     * Exposed because it is a URL prefix the distribution has to answer on: Next.js
+     * emits `<assetPrefix>/_next/static/...` for every bundle and compiles a rewrite
+     * that serves those URLs' paths itself, while the objects live in S3 under
+     * `<basePath>/_next/static/...`.
+     */
+    nextConfigAssetPrefixPath: string;
+    /**
+     * Every staged deployment root, one per function group, `default` first: the
+     * staged union of each group's shipped outputs and their traced assets,
+     * written by the adapter's `onBuildComplete`. Exactly one entry (named
+     * `default`, at `.next/cdk-nextjs-adapter/app`) unless `functionGroups`
+     * splits the app. The Lambda zip assets; Containers `COPY` the `default` one.
+     */
+    deploymentRoots: NextjsDeploymentRoot[];
+    /**
+     * What routes each non-default function group's URLs to it, most specific
+     * first — the order CloudFront has to see them in, since it stops at the
+     * first match. Empty unless `functionGroups` splits the app.
+     */
+    functionGroupBehaviors: NextjsFunctionGroupBehavior[];
+    /**
+     * From the deployment root to the Next.js project dir, POSIX, `""` when
+     * the app is at the repo root. The runtime `chdir`s here; Containers pass it to
+     * their Dockerfile so `.next/static` and `public` land in the same place.
+     * @see AdapterManifest.relativeProjectDir
+     */
+    relativeProjectDir: string;
+    /**
+     * The architecture every deployment root's native dependencies (`sharp`)
+     * were staged for. The Lambdas deploying them must use the same one.
      */
-    imageOptimizationAssetPath?: string;
+    architecture: Architecture;
     private props;
     private buildCommand;
     constructor(scope: Construct, id: string, props: NextjsBuildProps);
     /**
-     * Execute local build command in the specified directory
-     */
-    private runNextBuild;
-    /**
-     * Validate Next.js build output
-     * All builds must be standalone - no fallback to regular builds
+     * Line up the groups the props asked for with the roots the build actually
+     * staged, and fail loudly when they disagree.
+     *
+     * They can disagree in both directions, and both mean the same thing — the
+     * `.next` on disk came from a build that did not see this `functionGroups` —
+     * but the causes differ: `skipBuild: true` with a build run by hand, or a
+     * stale `.next` from before the prop changed. Either way every later symptom
+     * (a Lambda missing an entrypoint, a CloudFront behavior pointing at a
+     * function that cannot serve it) is this, several steps downstream.
      */
-    private validateNextBuildOutput;
+    private resolveDeploymentRoots;
     /**
-     * Find entrypoint client side js files to patch `fetch` only for NextjsGlobalFunctions
+     * Lambda enforces 250 MB unzipped at CloudFormation time, which is minutes
+     * into a deploy and reports only a size. Splitting exists to stay under that
+     * cap, so the error that tells you to split further has to name the group, its
+     * size, and what to do — and arrive at synth.
      */
-    private patchFetchInClientJs;
+    private assertUnderLambdaLimit;
     /**
-     * Automatically finds the relative path from standalone directory to the
-     * package containing server.js by searching for server.js with a .next sibling.
-     * @returns "." for non-monorepo apps, or relative path like "app-playground" for monorepo apps
+     * Read the manifest the adapter's `onBuildComplete` wrote.
+     *
+     * Its absence means `next build` ran without cdk-nextjs's adapter registered
+     * (or with a stale `next.config`), which is worth saying plainly here: every
+     * later failure — a Lambda that cannot find `manifest.json`, an empty asset —
+     * is the same cause several steps downstream.
      */
-    private findRelativePathToServerJs;
+    private readAdapterManifest;
     /**
-     * Get build ID from .next directory
+     * Copy cdk-nextjs's own bundled request-handling shell and the manifest into
+     * `<deploymentRoot>/cdk-nextjs-runtime/`, which is where
+     * `deploymentRootOf`/`deployedManifestPath` expect to find them.
+     *
+     * Only the shell the deployment type actually runs is copied — the Lambda
+     * handler for Functions, the `node:http` server for Containers — so nothing
+     * ships ~1.5 MB of dead code and the tree says which type produced it. Both
+     * are copied from this package's `lib/`, next to the compiled construct.
+     *
+     * Every group gets the same shell *and the same manifest*: a function only
+     * knows which routes it owns so it can say so when misrouted, and that comes
+     * from {@link FUNCTION_GROUP_ENV_VAR}, not from a per-group manifest.
      */
-    private getBuildId;
+    private stageRuntime;
     /**
-     * Get public directory entries from local filesystem
+     * `NEXT_ADAPTER_PATH` for the build, so `adapterPath` in `next.config` is
+     * optional.
+     *
+     * Next.js reads the variable as the *default* value of `adapterPath`
+     * (`next/dist/server/config-shared.js`, `defaultConfig`), so an app that does
+     * set `adapterPath` still wins and nothing existing changes.
+     *
+     * Resolved from the Next.js app, not from cdk-nextjs's own `__dirname` and not
+     * left as a bare specifier. Both alternatives were tried and both are wrong:
+     *
+     * - cdk-nextjs's own location loses because the adapter resolves its sibling
+     *   cache handler relative to wherever *it* was loaded from. An adapter loaded
+     *   from outside the app's tree hands Next.js a `cacheHandler` outside
+     *   `turbopack.root`, which Turbopack rejects outright ("leaves the filesystem
+     *   root").
+     * - A bare specifier loses because Next.js resolves `adapterPath` from inside
+     *   its own config loader, i.e. from `next`'s realpath. Under pnpm that is the
+     *   virtual store (`node_modules/.pnpm/next@…/node_modules/next/`), and the
+     *   walk up from there never reaches the app's own `node_modules`.
+     *
+     * Unset when `cdk-nextjs` is not resolvable from the app, which is legitimate:
+     * the Next.js app and the CDK app can be separate packages, and only the CDK one
+     * necessarily depends on cdk-nextjs. {@link readAdapterManifest} reports the
+     * resulting failure and names this case.
+     *
+     * One setup this cannot serve, and the reason this repo's own examples still set
+     * `adapterPath`: a `link:`/`file:` dependency on a cdk-nextjs checkout *outside*
+     * the app's project root. The symlink resolves out of the project, so the
+     * `cacheHandler` escape above applies. Set `adapterPath` in `next.config` there
+     * — it is resolved by the build, after whatever put the adapter in place.
      */
-    private getLocalPublicDirEntries;
+    private adapterPathEnv;
     /**
-     * Recursively find and remove existing Sharp platform binaries
+     * Execute local build command in the specified directory
      */
-    private removeExistingSharpBinaries;
+    private runNextBuild;
     /**
-     * Download and install correct Sharp binaries for Linux MUSL
+     * Prepend `patch-fetch.js` to the client entrypoint chunks, for
+     * `NextjsGlobalFunctions` only.
+     *
+     * This is what makes POST work at all on that type. CloudFront reaches the
+     * server through a Lambda Function URL with `AuthType: AWS_IAM`, signed by an
+     * origin access control, and AWS documents the consequence: "If you use PUT or
+     * POST methods with your Lambda function URL, your users must compute the
+     * SHA256 of the body and include the payload hash value of the request body in
+     * the `x-amz-content-sha256` header when sending the request to CloudFront.
+     * Lambda doesn't support unsigned payloads."
+     *
+     * CloudFront signs GETs itself (empty-body hash) but will not hash a body, and
+     * a browser has no way to add that header on its own, so an unpatched app
+     * answers every server action, form submission and POST route handler with
+     * `403 InvalidSignatureException` before the request reaches Next.js. The
+     * patch installs `fetch`/`XMLHttpRequest` wrappers that compute the hash.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-lambda.html
      */
-    private downloadAndInstallSharpBinaries;
+    private patchFetchInClientJs;
     /**
-     * Assemble the deployment asset for the dedicated image optimization
-     * Lambda: the pre-bundled handler (from this package's own `lib/` output),
-     * `sharp`'s JS wrapper (already dereferenced from the pnpm store by Next's
-     * output file tracing into the standalone build), glibc `sharp` binaries
-     * (the standard Lambda managed runtime is Amazon Linux 2023/glibc, unlike
-     * the musl binaries the Docker/Lambda Web Adapter server function needs),
-     * and `required-server-files.json` (read by the handler at cold start to
-     * build `nextConfig`).
+     * Get public directory entries from local filesystem
      */
-    private prepareImageOptimizationAssets;
+    private getLocalPublicDirEntries;
     /**
-     * Locate `sharp`'s JS wrapper inside a standalone `node_modules`.
+     * Strip whatever platform-specific Sharp binaries `next build`'s output file
+     * tracing staged, since they're the host's (e.g. macOS/glibc) rather than the
+     * deployment target's, then install the target's. Skipping this is silent:
+     * `imageOptimizer` catches the load failure internally and returns the
+     * unoptimized original with an HTTP 200.
      *
-     * Next's output file tracing preserves the installer's on-disk layout, so
-     * npm/yarn produce a hoisted `node_modules/sharp` while pnpm only
-     * materializes `node_modules/.pnpm/sharp@<version>/node_modules/sharp`.
+     * Only a root with `sharp` staged gets the binaries: the image optimizer
+     * brings it into `default`, which serves every `/_next/image`, and another
+     * group has it only if its own routes use it. So only `default` warns when
+     * it's missing.
      */
-    private findSharpPackage;
+    private stageSharpForTarget;
     /**
-     * Copy `sharp` plus the transitive `dependencies` closure `require("sharp")`
-     * pulls in (`@img/colour`, `detect-libc`, `semver`) into `targetPath`.
+     * Recursively find and remove existing Sharp platform binaries.
+     *
+     * `root` is walked whole rather than just its `node_modules`: the staged tree
+     * is keyed by repo-root-relative path, so in a monorepo the `node_modules`
+     * holding `sharp` is several directories down. {@link isSharpBinaryPackage} is
+     * what keeps that from reaching the app's own output — the staged root holds
+     * the compiled `.next` as well as the dependencies.
      *
-     * Copying only `sharp` itself leaves those requires unresolvable, and
-     * `imageOptimizer` swallows the resulting `MODULE_NOT_FOUND` by falling back
-     * to serving the unoptimized original, so the omission is otherwise silent.
+     * @param projectDir the app's directory inside `root`, which `next` is
+     * resolved from.
+     * @returns the staged `sharp` JS wrapper to install next to, found in the same
+     * walk: a root can be hundreds of megabytes, and each group has one.
      */
-    private copySharpRuntime;
+    private removeExistingSharpBinaries;
     /**
      * Resolve the `@img/sharp-<platform>` and `@img/sharp-libvips-<platform>`
      * versions to install for a given platform.
      *
-     * These must match the `sharp` JS wrapper that output file tracing put in
-     * the standalone build: `sharp`'s `lib/libvips.js` compares the binary's
+     * These must match the `sharp` JS wrapper that output file tracing staged:
+     * `sharp`'s `lib/libvips.js` compares the binary's
      * reported libvips version against its own `minimumLibvipsVersion` and
      * throws at load when they disagree. `sharp` pins both in its
      * `optionalDependencies`, so that manifest is the authoritative source.
@@ -164,3 +353,90 @@ export declare class NextjsBuild extends Construct {
      */
     private isCachedFileValid;
 }
+/**
+ * Pick the staged `sharp` JS wrapper out of every copy found in the tree.
+ *
+ * Unlike a standalone build there is no single `node_modules` to look in: the
+ * tree mirrors repo-root-relative paths, so the search is by directory name.
+ *
+ * An app can have two `sharp` copies at different versions (its own, hoisted,
+ * and next's, nested under `next/node_modules`), and every binary goes into the
+ * one root `@img`, so the copy pinning them has to be the one `next`'s image
+ * optimizer loads: `nextSharp`, when {@link resolveNextSharp} found it. Otherwise
+ * shortest path wins as the closest to a hoisted install, sorted for
+ * determinism.
+ */
+export declare function pickStagedSharpPackage(candidates: string[], nextSharp?: string): string | undefined;
+/**
+ * The real path of the `sharp` entry point the staged `next` resolves from
+ * `projectDir`, `undefined` when either does not resolve.
+ */
+export declare function resolveNextSharp(projectDir: string): string | undefined;
+/**
+ * Whether the entry `name` in `parentPath` is an `@img/sharp-*` platform binary
+ * package, or pnpm's store entry for one.
+ *
+ * The name alone is not enough to delete a directory by. A route segment called
+ * `sharp-edges` stages `.next/server/app/sharp-edges/`, and removing it left the
+ * manifest listing an entrypoint that is no longer on disk — every request to
+ * that route 500ing with "Could not load the entrypoint". Nor is "a `sharp-`
+ * package": `sharp-ico` and `sharp-phash` are unrelated dependencies, and
+ * removing them failed the app at runtime with MODULE_NOT_FOUND. So both the
+ * scope and the place have to match:
+ *
+ * - `node_modules/@img/sharp-…`, where every platform binary actually lives
+ * - `node_modules/.pnpm/@img+sharp-…@0.35.4`, pnpm's store, whose entries are
+ *   also what the `@img` links point at (`sharp-libvips-…` matches the same way)
+ *
+ * The `node_modules` segment is required as well, so an app directory that
+ * happens to be called `@img` or `.pnpm` is still left alone.
+ */
+export declare function isSharpBinaryPackage(parentPath: string, name: string): boolean;
+/**
+ * Where the target's `@img/sharp-*` binaries go: `<root>/node_modules/@img`.
+ *
+ * Not next to the staged `sharp` package. Under pnpm that is
+ * `node_modules/.pnpm/sharp@x/node_modules/@img`, which only the store copy of
+ * `sharp` resolves from: a dereferenced link to `sharp` (a copy at
+ * `app/node_modules/sharp`, say) looks for `@img` from its own path and walks
+ * up, never into the store. Both the Functions zip (`zipDirectory`) and the
+ * Containers `COPY` keep the links, so it is the store copy that loads, and its
+ * walk up reaches the root `node_modules` too, so it serves either layout. It
+ * is also where main installed them.
+ */
+export declare function sharpBinaryDir(root: string): string;
+/**
+ * Every entry under `root`, links listed but not followed.
+ *
+ * An explicit walk rather than `readdirSync({ recursive: true })`, which on
+ * Node 24 descends into symlinked directories itself and so never returns on a
+ * cycle — two workspace packages that link each other, which is how pnpm wires a
+ * monorepo.
+ */
+export declare function listTree(root: string): Dirent[];
+/**
+ * Write {@link PUBLIC_FILES_FILE_NAME} into a deployment root's runtime
+ * directory: every file under `publicDir`, listed the way the runtime would
+ * list it off disk (`readPublicFiles`: symlinks followed, `/`-separated,
+ * sorted). An app without `public/` gets `[]`.
+ */
+export declare function writePublicFileList(runtimeDir: string, publicDir: string): void;
+/**
+ * Total bytes of a tree as its deployment zip stores it. `zipDirectory` keeps
+ * links as links, so each counts as its target path, not as the target, which
+ * is walked at its own path anyway (every link in a staged root points inside
+ * it).
+ */
+export declare function storedSize(root: string): number;
+/**
+ * `chunk` with `patch` prepended between `PATCH_FETCH_MARKER` and
+ * `PATCH_FETCH_END_MARKER`, or `undefined` when it already carries this exact
+ * patch.
+ *
+ * The opening marker carries a hash of the patch, so a chunk patched by a
+ * cdk-nextjs whose `patch-fetch.js` differs (an upgrade, over a `.next` reused
+ * with `skipBuild: true`) is not mistaken for current: the old patch is cut off
+ * at its end marker and this one put in its place, rather than the old one
+ * shipping or both stacking up.
+ */
+export declare function patchClientChunk(chunk: string, patch: string, chunkPath: string): string | undefined;