Using TypeScript with nodejs runtime

[Envek]

Hey! Thank you for awesome tool–it is amazing (yet magical a bit). Here I want to bring some attention to areas (with links to existing issues) where it is hard to use and customize SAM CLI. And, hopefully, start discussion for this topic.

TL;DR: Use Makefile builder to compile typescript to javascript. And I have step-by-step guide for that.

---

TypeScript has gained a lot of traction and popularity in last years both for frontend and backend usage. It gives us a lot of good things: protection against stupid bugs, code completion in editors, etc.

Unfortunately, AWS SAM CLI out-of-the-box doesn't have support for developing Lambda functions for NodeJS runtime in TypeScript (while Serverless framework does). Moreover, adding TypeScript to existing project is complicated because SAM CLI doesn't allow to add custom steps to default build process.

There are some manuals on how to add TypeScript support, add shared layers, and so on, but usually they tend to bring Webpack and replace sam build with some custom scripts that tries to mimic SAM CLI behavior. I feel that such approach is just isn't right.

In my opinion, this is how proper TypeScript support should look like:

• Keeping the local development experience mostly unchanged: no moving package.json to other places or otherwise changing the directory structure before deployment.
• No running sam build on every change in function handler code.
• Keeping generated JS code as close to TS source as possible, preserving the file layout (don't bundle everything into a single file as webpack does).
• Keeping dependencies in a separate layer shared between related Lambdas. It makes deploys faster as you only need to update function code and not its dependencies. Also, Lambda functions have a size limit which can be easily surpassed with heavy dependencies; shared layers allow us to keep coloring between the lines.
• Keeping deploys unchanged: sam build and sam deploy, with no extra CLI magic.

In short, a Lambda with TypeScript and shared layers must behave the same way as a freshly generated Lambda on pure Node.js.

After all, I succeeded to set it up in a way that is not ideal yet, but that I like pretty much using Makefile builder as described in Building layers doc for details.

Basically it is:

build-ExampleFunction:
	npm install
	tsc
	cp -r dist "$(ARTIFACTS_DIR)/"

Where TypeScript source code is located in src/ directory, while both local and deployed lambda is instructed to search for handlers in dist/ directory that contains transpiled JavaScript:

# template.yml
Resources:
  ExampleFunction:
    Type: AWS::Serverless::Function
    Metadata:
      BuildMethod: makefile
    Properties:
      Handler: dist/handlers/example.exampleHandler

To better document my approach, I've done following things:

• Blog post in my company's blog: Serverless TypeScript: A complete setup for AWS SAM Lambdas – Martian Chronicles.
• Example project: github.com/Envek/aws-sam-typescript-layers-example
• Cookiecutter template: github.com/Envek/cookiecutter-aws-sam-typescript-layers

However, there are some inconveniences left:

• It is hard to debug Makefile-based builds: New Makefile Output & Debugging #2006
• It is annoying to remove .aws-sam directory after every deploy to make sam local invoke and sam local start-api use local code instead of packaged one.

I hope that my research results and these artifacts will be useful to both SAM CLI users and its developers.

---

Is there any plans to add built-in support for TypeScript?

[sriram-mv]

This is a great POC to showcase how to build and deploy Typescript based lambdas!! Looks pretty neat!

Usually, the aws-lambda-builders has the builders required for the building of artifacts per Lambda runtime. Makefile based builders was added to give back full control to developers on how they want builds to happen for them irrespective of their lambda runtime, or even re-implement how they wanted native runtime builds to behave.

I'm going to mark this as a feature request for now.

[sukruavcuoglu]

@Envek approach for building lambdas written in typescript is quite neat indeed. We are currently using the same approach in order to build our lambdas. There is a big downside comes with the numbers of lambdas begin to increase. For each lambda function, makefile script has to install all the dependencies and build the ts code from beginning. In time time to build the whole application will increase significantly. That's why built-in support is quite mandatory and urgent since many people are using typescript with their projects.

[Willis0826]

Also, the sam build --cached doesn't support makefile is a pain point to use typescript with SAM.

[mndeveci]

We've launched esbuild support for SAM CLI which should help you to build TypeScript functions. It is still under beta, please take a look and let us know if you have any issues or feedback regarding to that .

https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-build-typescript.html