cdk-nextjs 0.7.1 → 0.7.2

package/docs/breaking-changes.md

@@ -107,8 +107,10 @@ them — only the Containers types still build images.
   deployment: a function group's own `overrides.functionProps.architecture`
   that differs is a synth error. An x86 CI runner can deploy arm64 functions. Only
   `sharp` is staged for the target. Any other native dependency in your app is
-  still traced from the build machine, so build on the architecture you deploy
-  if you have one.
+  still traced from the build machine, and synth warns naming each package
+  whose addons are all built for another platform. See the
+  [Native Dependencies Guide](./native-dependencies-guide.md) to fix or
+  acknowledge it.
 - **The post-deploy Lambda is always arm64.** It has no native dependencies,
   so it no longer follows the synth machine. The first deploy after upgrading
   from an x86 machine updates it in place.

package/docs/native-dependencies-guide.md

@@ -0,0 +1,223 @@
+# Native Dependencies Guide
+
+`next build` traces native addons (`.node` files) from the machine it runs on.
+cdk-nextjs swaps `sharp` for the platform your app deploys to, but nothing else.
+Any other native dependency built on a Mac, or on an x64 CI runner deploying
+arm64, is staged for the wrong platform and fails with `MODULE_NOT_FOUND` or
+`ERR_DLOPEN_FAILED` on the first request that loads it.
+
+Synth warns about this, naming each staged package whose addons are all for a
+platform other than the target:
+
+```
+[WARNING] /MyStack/Nextjs/NextjsBuild: [cdk-nextjs] Deployment root "default"
+has native binaries built for a platform other than linux-arm64, which it runs
+on: node_modules/@valkey/valkey-glide-darwin-arm64. ...
+[ack: cdk-nextjs:foreignNativeBinaries]
+```
+
+The target is:
+
+| Construct            | Target                                     |
+| -------------------- | ------------------------------------------ |
+| `*Functions`         | `linux-<arch>` glibc (Amazon Linux 2023)   |
+| `*Containers`        | `linux-<arch>` musl (`node:24-alpine`)     |
+
+`<arch>` is the Lambda's architecture for Functions (`arm64` or `x64`), and the
+synth machine's for Containers.
+
+The check reads only the OS and CPU of each addon, not its libc, so the wrong
+libc variant passes synth. A `-musl` package on a Functions Lambda passes synth,
+then fails at runtime with `ERR_DLOPEN_FAILED`. Use `-gnu` packages for
+Functions and `-musl` packages for Containers.
+
+There are three ways to fix it.
+
+## 1. Build on the target platform
+
+Run synth on a Linux runner of the architecture you deploy. Nothing else to do.
+
+## 2. Stage the target's package after `next build` (any package manager)
+
+Most native libraries ship each platform as its own package
+(`@valkey/valkey-glide-linux-arm64-gnu`, `@node-rs/argon2-linux-arm64-gnu`, …),
+pinned in the main package's `optionalDependencies`. After `next build`, remove
+the build machine's variant from the staged output and extract the target's in
+its place, the way cdk-nextjs does for `sharp`. Your local `node_modules` is
+untouched, so local dev keeps working.
+
+Run the script from `buildCommand`, which runs in your Next.js project directory
+before cdk-nextjs zips the staged output:
+
+```ts
+new NextjsGlobalFunctions(this, "Nextjs", {
+  buildDirectory: "./app",
+  buildCommand: "npm run build && node scripts/stage-native.mjs arm64",
+  overrides: {
+    nextjsFunctions: { functionProps: { architecture: Architecture.ARM_64 } },
+  },
+});
+```
+
+With `skipBuild: true`, `buildCommand` doesn't run, so run the script yourself
+after your own build.
+
+The warning checks the script's result: `NextjsBuild` runs the check after
+`buildCommand` and after it stages `sharp`. If the script stages nothing, for
+example because a cdk-nextjs release changed the staged layout, the foreign
+addon stays and synth warns. Run `cdk synth --strict` in CI so that a staging
+miss stops the deploy instead of shipping.
+
+`npm pack` fetches the tarball from the registry without your package manager's
+checks: it doesn't verify the lockfile's integrity hash, and it ignores rules
+such as pnpm's `minimumReleaseAge`.
+
+`scripts/stage-native.mjs`, for `@valkey/valkey-glide` on Lambda. Edit the
+constants for your package; for Containers, use the `-musl` variant.
+
+```js
+// Replaces a native package's platform variant in the cdk-nextjs staged build
+// with the one for the deploy target.
+// Usage: node scripts/stage-native.mjs <arm64|x64>
+//
+// Known limits:
+// - It downloads the tarball once for each root that uses the package.
+// - If a step fails, the temporary directory stays behind.
+// - If a root has more than one version of the main package, it stages the
+//   version from the last manifest it reads.
+import { execFileSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  unlinkSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const arch = process.argv[2];
+if (arch !== "arm64" && arch !== "x64") {
+  throw new Error(`stage-native: expected "arm64" or "x64", got "${arch}"`);
+}
+
+// Edit these for your package.
+const scope = "@valkey";
+const name = "valkey-glide";
+// Lambda's managed runtime uses glibc; Containers use `-musl`.
+const target = `${scope}/${name}-linux-${arch}-gnu`;
+
+// Platform packages are `<scope>/<name>-<os>-<arch>[-<libc>]` links and
+// directories, plus their pnpm store directories (`<scope>+<name>-…`). Match
+// the platform, not only the prefix: Turbopack links the main package as
+// `<name>-<hash>`.
+const platform = new RegExp(`^(?:${scope}\\+)?${name}-(?:darwin|linux|win32)-`);
+const isPlatformPackage = (parent, entry) =>
+  platform.test(entry) &&
+  (parent.endsWith(scope) || entry.startsWith(`${scope}+`));
+
+// One deployment root without `functionGroups`, one per group with them.
+// Relative to this script, which lives in `<project>/scripts/`.
+const adapter = join(import.meta.dirname, "..", ".next", "cdk-nextjs-adapter");
+const groups = join(adapter, "groups");
+const roots = [
+  join(adapter, "app"),
+  ...(existsSync(groups)
+    ? readdirSync(groups).map((group) => join(groups, group))
+    : []),
+].filter((root) => existsSync(root));
+
+for (const root of roots) {
+  let version;
+  const pending = [root];
+  for (let dir = pending.pop(); dir !== undefined; dir = pending.pop()) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (isPlatformPackage(dir, entry.name)) {
+        if (entry.isSymbolicLink()) {
+          // Not rmSync: the walk can remove a pnpm store directory before it
+          // reaches a link into it, and rmSync(path, { force: true }) leaves
+          // that dangling link in place without an error.
+          unlinkSync(path);
+        } else {
+          rmSync(path, { recursive: true, force: true });
+        }
+      } else if (entry.isDirectory()) {
+        if (entry.name === name && dir.endsWith(scope)) {
+          const manifest = JSON.parse(
+            readFileSync(join(path, "package.json"), "utf8"),
+          );
+          version = manifest.optionalDependencies?.[target];
+        }
+        pending.push(path);
+      }
+    }
+  }
+  if (!version) {
+    continue; // This root doesn't use the package.
+  }
+
+  // The root's node_modules is on the resolution path of the staged package
+  // and of the app's server chunks.
+  const tmp = mkdtempSync(join(tmpdir(), "stage-native-"));
+  const tarball = execFileSync("npm", ["pack", `${target}@${version}`, "--silent"], {
+    cwd: tmp,
+    encoding: "utf8",
+  }).trim();
+  execFileSync("tar", ["-xzf", tarball], { cwd: tmp });
+  // A copy, not a rename: the temporary directory can be on another file system.
+  cpSync(join(tmp, "package"), join(root, "node_modules", target), {
+    recursive: true,
+  });
+  rmSync(tmp, { recursive: true, force: true });
+  console.log(`stage-native: staged ${target}@${version} in ${root}`);
+}
+```
+
+The script depends on cdk-nextjs's staged layout (`.next/cdk-nextjs-adapter/app`
+and `.next/cdk-nextjs-adapter/groups/<name>`), which can change between minor
+versions. Libraries that don't ship per-platform packages (they build from
+source at install, or bundle every platform's prebuild in one package) need
+approach 1.
+
+## 3. Install the target's variant with pnpm
+
+pnpm can install other platforms' optional dependencies next to your own. Keep
+`current` in the list so local dev still gets the host's variant:
+
+```yaml
+# pnpm-workspace.yaml
+supportedArchitectures:
+  os: [current, linux]
+  cpu: [current, arm64]
+  libc: [current, glibc]
+```
+
+This applies to every package in the workspace, and installs every combination
+of the listed values. Tracing still only follows the variant that loads on the
+build machine, so add the target's with Next.js's `outputFileTracingIncludes`
+and drop the host's with `outputFileTracingExcludes`. Both are needed: the
+host's package stays traced beside the one you add, and still has only a
+foreign addon. Under pnpm both live in `node_modules/.pnpm`, so the globs
+match the store directories, not `node_modules/<scope>/<name>`. Approach 2 is
+usually simpler.
+
+npm's `--os`/`--cpu` install flags replace the host's platform instead of adding
+to it, which breaks local dev, so use approach 2 with npm.
+
+## Optional native dependencies
+
+Some packages load an addon inside `try`/`catch` and fall back to JavaScript
+without it: `ws` with `bufferutil`/`utf-8-validate`, and `fsevents`. Their
+foreign addon never loads, so the app works as deployed. Acknowledge the
+warning:
+
+```ts
+import { Annotations } from "aws-cdk-lib";
+
+Annotations.of(nextjs).acknowledgeWarning("cdk-nextjs:foreignNativeBinaries");
+```
+
+To fail synth on it instead, run `cdk synth --strict`.

package/lib/nextjs-api.js

@@ -22,7 +22,7 @@ const API_PATH_PART = /^[a-zA-Z0-9:._\-$]+$/;
  * Creates an API Gateway REST API for Next.js applications
  */
 class NextjsApi extends constructs_1.Construct {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdk-nextjs.NextjsApi", version: "0.7.1" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdk-nextjs.NextjsApi", version: "0.7.2" };
     /**
      * The API Gateway REST API
      */

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

@@ -209,6 +209,16 @@ export declare class NextjsBuild extends Construct {
      * function that cannot serve it) is this, several steps downstream.
      */
     private resolveDeploymentRoots;
+    /**
+     * `next build` traces native addons from the machine it runs on, and only
+     * `sharp` is swapped for the target. Anything else built for another platform
+     * fails with MODULE_NOT_FOUND or ERR_DLOPEN_FAILED on the first request that
+     * loads it, so say which package at synth. A warning, not an error: some
+     * addons are optional (`ws`'s `bufferutil`, `fsevents`) and fall back to JS.
+     *
+     * Only the OS and CPU are checked: glibc and musl builds share a header.
+     */
+    private warnOnForeignNativeBinaries;
     /**
      * 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
@@ -414,6 +424,21 @@ export declare function sharpBinaryDir(root: string): string;
  * monorepo.
  */
 export declare function listTree(root: string): Dirent[];
+/**
+ * The platform a native addon was compiled for, read from its header:
+ * `linux-<arch>`, `darwin` or `win32`, or `undefined` for a file that is none
+ * of those.
+ */
+export declare function nativeBinaryPlatform(file: string): string | undefined;
+/**
+ * The packages under `root` that have `.node` addons but none built for
+ * `target`, so they'd fail to load there. Returned as `root`-relative paths.
+ *
+ * A package with addons for several platforms is fine as long as one of them
+ * is `target`: packages like `bufferutil` bundle a `darwin` and a
+ * `linux-x64` addon and load whichever matches the machine.
+ */
+export declare function findForeignNativePackages(root: string, target: string): string[];
 /**
  * Write {@link PUBLIC_FILES_FILE_NAME} into a deployment root's runtime
  * directory: every file under `publicDir`, listed the way the runtime would