Overriding Node.js Runtime in AWS CDK v1 Lambda Functions

CDK v1 reached end of support yesterday, and its last release never learned about anything past Node.js 16. The Runtime enum in @aws-cdk/aws-lambda@1.204.0 stops at NODEJS_16_X, even though Lambda has offered nodejs18.x since November 2022.

That enum only exists to produce a string in the synthesized template. So reach past the L2 construct and set the string yourself:

const myFunction = new lambda.Function(this, 'MyFunction', {
    runtime: lambda.Runtime.NODEJS_16_X, // newest CDK v1 knows about
    handler: 'index.handler',
    code: lambda.Code.fromAsset('lambda'),
});

const cfnFunction = myFunction.node.defaultChild as lambda.CfnFunction;
cfnFunction.runtime = 'nodejs18.x';

lambda.Function creates its CfnFunction under the logical id Resource, which makes it the defaultChild. This is the same escape hatch as addPropertyOverride('Runtime', 'nodejs18.x'), just through a typed property instead of a stringly-typed path.

Versioning survives, which is the part I expected to break. CDK v1 hashes the function from _toCloudFormation(), so the override is included and currentVersion produces a new hash.

Check these before you ship it

Node 18 dropped the bundled AWS SDK v2. Node 16 was the last runtime to ship aws-sdk on the image. Any handler calling require('aws-sdk') without bundling it throws at invocation time, long after synth and deploy looked clean. Grep your handlers first.

The L2 still thinks it’s Node 16. Validation runs against props.runtime, not your override, so a layer declaring compatibleRuntimes: [NODEJS_18_X] fails synth. Widen it to cover Node 16 too.

It doesn’t reach NodejsFunction. That bundler derives esbuild’s --target from props.runtime, so you still get node16 output. It runs fine on Node 18, but it isn’t Node 18 output.

The escape hatch buys you a supported runtime without a migration. It doesn’t buy you a reason to skip one.