feat!: require Node.js 22.2+ and drop the Node 20 workarounds

.projenrc.ts

@@ -59,7 +59,8 @@ const project = new CdklabsConstructLibrary({
     "next@^16.4.0", // bundled in src/nextjs-build/cache-handler.ts
     "undici",
   ],
-  setNodeEngineVersion: false,
+  // Synth runs on the user's Node. 22.2 is the first 22.x with `zlib.crc32`.
+  minNodeVersion: "22.2.0",
   npmIgnoreOptions: {
     ignorePatterns: [
       "examples/**/*",
@@ -254,6 +255,9 @@ function cjsGlobalsBanner() {
 
 function bundle(): javascript.Bundle[] {
   const target = `node${nodeVersion}`;
+  // The cache handlers and the adapter are also loaded by the user's own
+  // `next build`, on whatever Node runs synth.
+  const buildTarget = `node${project.package.minNodeVersion}`;
   const bundles: javascript.Bundle[] = [];
   const addBundle = (entry: string, options: javascript.AddBundleOptions) =>
     bundles.push(project.bundler.addBundle(entry, options));
@@ -268,8 +272,8 @@ function bundle(): javascript.Bundle[] {
   // namespace ends up as `{ default }` and `.createRequire` is undefined —
   // producing "(intermediate value).createRequire is not a function" at
   // runtime (cdklabs/cdk-nextjs#270). A static import also keeps the bundles
-  // free of top-level await, so Node can still `require()` them instead of
-  // throwing ERR_REQUIRE_ASYNC_MODULE.
+  // free of top-level await, so Node (22.12+) can still `require()` them
+  // instead of throwing ERR_REQUIRE_ASYNC_MODULE.
   // Prefixed for the reason {@link cjsGlobalsBanner} documents: `build-outputs.ts`
   // imports `createRequire` by name and is in the adapter bundle's tree, so a
   // banner declaring the bare name makes the output fail to parse
@@ -281,7 +285,7 @@ function bundle(): javascript.Bundle[] {
   ].join(" ");
   addBundle("src/adapter/cache-handler.ts", {
     platform: "node",
-    target,
+    target: buildTarget,
     outfile: "../../../lib/adapter/cache-handler.mjs",
     externals: ["next"],
     format: "esm",
@@ -292,7 +296,7 @@ function bundle(): javascript.Bundle[] {
   for (const kind of ["default", "remote"]) {
     addBundle(`src/adapter/use-cache-${kind}-handler.ts`, {
       platform: "node",
-      target,
+      target: buildTarget,
       outfile: `../../../lib/adapter/use-cache-${kind}-handler.mjs`,
       externals: ["next"],
       format: "esm",
@@ -301,7 +305,7 @@ function bundle(): javascript.Bundle[] {
   }
   addBundle("src/adapter/adapter.mts", {
     platform: "node",
-    target,
+    target: buildTarget,
     outfile: "../../../lib/adapter/adapter.mjs",
     externals: ["next"],
     format: "esm",
@@ -724,6 +728,7 @@ function updatePackageJson() {
       "@babel/core": "^7.29.6",
       sharp: "^0.35.5",
       "source-map-js": "^1.2.2",
+      "handlebars@4": "^4.7.10",
     }),
   );
   packageJson?.patch(JsonPatch.add("/packageManager", `pnpm@${pnpmVersion}`));

CLAUDE.md

@@ -72,6 +72,7 @@ Tests live alongside source (`src/**/*.test.ts`) for adapter/cache code. CDK con
 - **Overrides pattern**: Every construct exposes an `overrides` prop that passes raw CDK props through, allowing users to customize underlying resources.
 - **Conventional commits**: PRs require semantic title prefixes: `feat`, `fix`, `chore`, `refactor`, `perf`, `docs`, `style`, `test`, `build`, `ci`.
 - **Releasable commits**: Only `feat`, `fix`, `chore`, `refactor`, `perf` trigger a release.
+- **Breaking changes only in a `0.X.0` release** (until 1.0): `feat`/`fix` release as a patch (`0.7.13` → `0.7.14`), and users on `^0.7` get it automatically, so a patch must not break anyone. Warn or deprecate instead, and break in the next minor. A breaking PR's title takes a `!` (`fix!:`, `feat!:`), which projen bumps to the next minor (`0.8.0`), and it targets the `next` branch, not `main`: `next` doesn't release, and is squash-merged into `main` as one `feat!:` commit when the minor ships. Non-breaking fixes still target `main`; merge `main` into `next` to keep it current. `docs/breaking-changes.md` has only `## 0.X.0` headers, so on `next` every breaking PR adds to the one `## 0.8.0` section; never add a patch header.
 - **Package manager**: pnpm (v10). Use `pnpm dlx projen <task>` or the package.json script shortcuts.
 - **Node version**: 24 (Lambda runtime target).
 - **ESLint**: import ordering is enforced (builtin → external, alphabetical). Prettier is integrated.

README.md

@@ -52,7 +52,7 @@ The simplest path to deploy Next.js is on [Vercel](https://vercel.com/) - the Pl
 - Next.js app running v16.3 or higher (`next build` fails on older versions). If you don't have one yet - follow [these steps](https://nextjs.org/docs/getting-started) to create one.
 - [AWS Cloud Development Kit](https://docs.aws.amazon.com/cdk/v2/guide/home.html) app either in the same package or separate package. cdk-nextjs supports monorepos.
 - A Docker compatible container engine, but **only** for `NextjsGlobalContainers` and `NextjsRegionalContainers` - we recommend [Rancher Desktop](https://rancherdesktop.io/) with dockerd (moby). The two Functions types deploy zip Lambdas and need no container engine.
-- [Node.js](https://nodejs.org/en) v24 (or LTS)
+- [Node.js](https://nodejs.org/en) 22.2 or higher (22, 24, or a newer LTS)
 
 ## Getting Started
 
@@ -89,6 +89,8 @@ For the Containers types, cdk-nextjs generates a Dockerfile in your Next.js app'
 
 Every generated Dockerfile starts with the line `# ~~ Generated by cdk-nextjs ~~`, and cdk-nextjs **overwrites** any file carrying it — that way an upgrade that changes how the image is built does not leave a stale Dockerfile behind. To customize it, delete that first line; cdk-nextjs then leaves the file alone. If you edited a generated file without deleting the header, cdk-nextjs saves your version beside it as `<name>.Dockerfile.bak` before replacing it; gitignore that too.
 
+The generated Dockerfile runs `apk upgrade` so the image picks up Alpine security fixes released after the `node:24-alpine` base image was published. If you own your Dockerfile, add `RUN apk upgrade --no-cache` after its `FROM` line. CDK only rebuilds the image when the app or Dockerfile changes, so a stack redeployed with an unchanged app keeps its existing image and its packages.
+
 ## Basic Example CDK App
 
 ```ts