Lambda Versioned Layers: Native Node Addons Without ABI Surprises

# docker/addon-layer/Dockerfile
ARG RUNTIME=public.ecr.aws/lambda/nodejs:20
FROM ${RUNTIME} AS build
WORKDIR /opt
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
# ✅ rebuild native code for this image's Node ABI
RUN npm rebuild better-sqlite3 --build-from-source
RUN mkdir -p /layer/nodejs && cp -R node_modules /layer/nodejs/
FROM scratch
COPY --from=build /layer /

# publish distinct layers
docker build --build-arg RUNTIME=public.ecr.aws/lambda/nodejs:20 -t addon-node20 .
# pack /opt → zip → aws lambda publish-layer-version \
#   --compatible-runtimes nodejs20.x \
#   --description "better-sqlite3 abi=$(node -p process.versions.modules)"

// lib/assert-abi.ts
import { createRequire } from "node:module";
const require = createRequire(import.meta.url);

export function assertAddonAbi(expectedModules: string) {
  if (process.versions.modules !== expectedModules) {
    throw new Error(
      `abi_skew: runtime=${process.versions.modules} layer_built_for=${expectedModules}`,
    );
  }
  // touch the native binding early on cold start
  require("better-sqlite3");
}

// handler init
assertAddonAbi(process.env.ADDON_ABI!);

const layer = lambda.LayerVersion.fromLayerVersionArn(this, "Addon",
  ssm.StringParameter.valueForStringParameter(this, "/lambda/layers/addon-node20"));

new lambda.Function(this, "Fn", {
  runtime: lambda.Runtime.NODEJS_20_X, // must match layer
  layers: [layer],
  environment: { ADDON_ABI: "115" }, // node20 modules version
});