aws-lambda-nodejs: How to setup AWS CDK to use ESM with layers / top level await
- 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
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