aws / aws/aws-cdk

aws-lambda-nodejs: How to setup AWS CDK to use ESM with layers / top level await

Open
#23,333 19 comments 31 reactions 0 assignees View on GitHub
@aws-cdk/aws-lambda-nodejs documentation effort/medium feature-request p2
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
2d 3h
Merged PRs (30d)
83

Description

### Describe the issue

Lambda is one of the most important services of the AWS portfolio. Significant improvements have been made allowing the NodeJS runtime (14+) to use ESM and top level await:

1. [ESM Announcement Top Level Await](https://aws.amazon.com/about-aws/whats-new/2022/01/aws-lambda-es-modules-top-level-await-node-js-14)
2. [NodeJS 18 Annoucement ](https://aws.amazon.com/about-aws/whats-new/2022/11/aws-lambda-support-node-js-18/)
3. [NodeJS 18 Blog Post (aws-cdk_v3, ESM via `NODE_PATH`, global fetch, ...)](https://aws.amazon.com/blogs/compute/node-js-18-x-runtime-now-available-in-aws-lambda/)

Yet I cannot really use that in my application due to several reasons:

1. Lambda Layers are a de facto requirement for most bigger applications. Before the NodeJS 18 release there was no support for ESM Lambda Layers. I have not checked if the new
> Support for ES module resolution using NODE_PATH

solves this issue since I did not test it ever since. Has anyone?

2. When having CDK project files with the lambda function handler code side by side in a project you will have issues with typechecking since the `.tsconfig` file shipped with `aws-cdk` does not play nice with handler code which needs other settings in `.tsconfig`. On the other hand if you change your `.tsconfig` file to other target/module/library settings the project will fail (no module errors, if you change `package.json` to `"type"="module" it will not like the `*.ts` extension, etc. etc. its a rabbit hole to which bottom I never got)

3. The state of Lambda Layer bundling is a wild landscape of self-baked solutions (of course I have my own). The issues of this are widespread and maybe better in its own thread)

I would heavily welcome if someone at AWS / AWS-CDK takes a deep dive on how to setup an aws-cdk TypeScript project with ESM / top level await / ESM layers and shows it to the rest of the world. There is too much potential improvement on the line to keep this lingering in its current state (is it only the docs?)

The whole JavaScript ecosystem with CJS / ESM etc. is a mess only few developers will fully understand (excluding me). AWS-CDK is a powerful but complex software (which I love). Implementing the above requires a lot of knowledge (at least when the solution must be compatible with future plans / releases)

Related Issues:

1. https://github.com/aws/aws-appsync-community/issues/213
2. https://github.com/aws/aws-cdk/issues/21635
3. https://github.com/aws/aws-cdk/issues/21329
4. https://github.com/aws/aws-sdk-js-v3/issues/3386
5. https://github.com/aws/aws-lambda-nodejs-runtime-interface-client/issues/93#issuecomment-2042201321

Partial solutions / approaches to some problems and additional content

1. https://github.com/coderbyheart/aws-lambda-esm-with-layer
2. https://github.com/vibe/aws-esm-modules-layer-support
3. https://twitter.com/adamdotdev/status/1523282408417677312 + https://github.com/adamelmore/cdk-top-level-await
4. https://github.com/huntharo/lambda-docker-typescript-esm

### Links

https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html

Contributor guide

Open the contributing guide

Research direction

Start with the aws-cdk-lib.aws_lambda_nodejs README linked in the issue, then review related issues 21635 and 21329 and the listed partial-solution repositories. Done would be a documented, maintainable AWS CDK TypeScript setup covering ESM, top-level await, and ESM layers, with its compatibility limits made clear.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, node.js, typescript
Domain
cloud, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.