Skip to content

Commit ecf4b38

Browse files
joe4devjoe4dev
committed
Add TypeScript sample (WIP)
1 parent 06bef27 commit ecf4b38

File tree

18 files changed

+6366
-0
lines changed

18 files changed

+6366
-0
lines changed

‎lambda-debugging-sam-typescript/.gitignore‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Lambda function response
2+
response.json
3+
4+
# Lambda function package
5+
# TODO
6+
7+
# Created by https://www.toptal.com/developers/gitignore/api/node,sam
8+
# Edit at https://www.toptal.com/developers/gitignore?templates=node,sam
9+
10+
### Node ###
11+
# Logs
12+
logs
13+
*.log
14+
npm-debug.log*
15+
yarn-debug.log*
16+
yarn-error.log*
17+
lerna-debug.log*
18+
.pnpm-debug.log*
19+
20+
# Diagnostic reports (https://nodejs.org/api/report.html)
21+
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
22+
23+
# Runtime data
24+
pids
25+
*.pid
26+
*.seed
27+
*.pid.lock
28+
29+
# Directory for instrumented libs generated by jscoverage/JSCover
30+
lib-cov
31+
32+
# Coverage directory used by tools like istanbul
33+
coverage
34+
*.lcov
35+
36+
# nyc test coverage
37+
.nyc_output
38+
39+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
40+
.grunt
41+
42+
# Bower dependency directory (https://bower.io/)
43+
bower_components
44+
45+
# node-waf configuration
46+
.lock-wscript
47+
48+
# Compiled binary addons (https://nodejs.org/api/addons.html)
49+
build/Release
50+
51+
# Dependency directories
52+
node_modules/
53+
jspm_packages/
54+
55+
# Snowpack dependency directory (https://snowpack.dev/)
56+
web_modules/
57+
58+
# TypeScript cache
59+
*.tsbuildinfo
60+
61+
# Optional npm cache directory
62+
.npm
63+
64+
# Optional eslint cache
65+
.eslintcache
66+
67+
# Optional stylelint cache
68+
.stylelintcache
69+
70+
# Microbundle cache
71+
.rpt2_cache/
72+
.rts2_cache_cjs/
73+
.rts2_cache_es/
74+
.rts2_cache_umd/
75+
76+
# Optional REPL history
77+
.node_repl_history
78+
79+
# Output of 'npm pack'
80+
*.tgz
81+
82+
# Yarn Integrity file
83+
.yarn-integrity
84+
85+
# dotenv environment variable files
86+
.env
87+
.env.development.local
88+
.env.test.local
89+
.env.production.local
90+
.env.local
91+
92+
# parcel-bundler cache (https://parceljs.org/)
93+
.cache
94+
.parcel-cache
95+
96+
# Next.js build output
97+
.next
98+
out
99+
100+
# Nuxt.js build / generate output
101+
.nuxt
102+
dist
103+
104+
# Gatsby files
105+
.cache/
106+
# Comment in the public line in if your project uses Gatsby and not Next.js
107+
# https://nextjs.org/blog/next-9-1#public-directory-support
108+
# public
109+
110+
# vuepress build output
111+
.vuepress/dist
112+
113+
# vuepress v2.x temp and cache directory
114+
.temp
115+
116+
# Docusaurus cache and generated files
117+
.docusaurus
118+
119+
# Serverless directories
120+
.serverless/
121+
122+
# FuseBox cache
123+
.fusebox/
124+
125+
# DynamoDB Local files
126+
.dynamodb/
127+
128+
# TernJS port file
129+
.tern-port
130+
131+
# Stores VSCode versions used for testing VSCode extensions
132+
.vscode-test
133+
134+
# yarn v2
135+
.yarn/cache
136+
.yarn/unplugged
137+
.yarn/build-state.yml
138+
.yarn/install-state.gz
139+
.pnp.*
140+
141+
### Node Patch ###
142+
# Serverless Webpack directories
143+
.webpack/
144+
145+
# Optional stylelint cache
146+
147+
# SvelteKit build / generate output
148+
.svelte-kit
149+
150+
### SAM ###
151+
# Ignore build directories for the AWS Serverless Application Model (SAM)
152+
# Info: https://aws.amazon.com/serverless/sam/
153+
# Docs: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-reference.html
154+
155+
**/.aws-sam
156+
157+
# End of https://www.toptal.com/developers/gitignore/api/node,sam
158+

‎lambda-debugging-sam-typescript/.vscode/launch.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"name": "Node: Remote Attach",
6+
"type": "node",
7+
"request": "attach",
8+
"address": "127.0.0.1",
9+
"port": 7050,
10+
"localRoot": "${workspaceFolder}/hello-world",
11+
"remoteRoot": "/var/task/",
12+
"outFiles":[
13+
"TODO(fix-these)",
14+
".aws-sam/build/HelloWorldFunction/**",
15+
"${workspaceFolder}/**/*.(m|c|)js",
16+
"!**/node_modules/**"
17+
]
18+
}
19+
]
20+
}

‎lambda-debugging-sam-typescript/Makefile‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
.PHONY: usage install build build-docker build-local build-sam wait deploy deploy-aws deploy-sam invoke clean start stop ready test-ci
2+
3+
AWS_ENDPOINT_URL ?= http://localhost.localstack.cloud:4566
4+
AWS ?= AWS_ENDPOINT_URL=$(AWS_ENDPOINT_URL) \
5+
AWS_ACCESS_KEY_ID=test \
6+
AWS_SECRET_ACCESS_KEY=test \
7+
AWS_DEFAULT_REGION=us-east-1 \
8+
aws
9+
SAM ?= AWS_ENDPOINT_URL=$(AWS_ENDPOINT_URL) \
10+
AWS_ACCESS_KEY_ID=test \
11+
AWS_SECRET_ACCESS_KEY=test \
12+
AWS_DEFAULT_REGION=us-east-1 \
13+
sam
14+
FUNCTION_NAME ?= HelloWorldFunctionTypeScript
15+
LAMBDA_RUNTIME ?= nodejs22.x
16+
17+
ARCH ?= x86_64
18+
DOCKER_PLATFORM ?= linux/$(ARCH)
19+
IMAGE ?= public.ecr.aws/sam/build-$(LAMBDA_RUNTIME):latest-$(ARCH)
20+
21+
all: usage
22+
23+
usage: ## Show this help
24+
@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
25+
26+
# TODO: figure out how to install the AWS CLI v2 in CI
27+
install: ## Install CLI dependencies
28+
@which aws || pip install awscli
29+
30+
build: build-local ## Build the Lambda function (default local)
31+
32+
# TODO: FIX TypeScript deployment
33+
# TODO: package runtime dependencies from package.json/node_modules
34+
# TODO: run tests before build
35+
build-docker: ## Build the Lambda function zip in Docker
36+
docker run --platform $(DOCKER_PLATFORM) --rm -v "$$(pwd)/hello-world:/app" $(IMAGE) bash -c "cd /app && zip -r hello-world-javascript.zip ."
37+
38+
# TODO: FIX TypeScript deployment
39+
# TODO: package runtime dependencies from package.json/node_modules
40+
# TODO: run tests before build
41+
build-local: ## Build the Lambda function zip locally (Node.js requires)
42+
cd hello-world && zip -r hello-world-javascript.zip .
43+
44+
build-sam: ## Build the Lambda function via AWS SAM
45+
$(SAM) build --use-container
46+
47+
wait: ## Wait until the Lambda function becomes ready to invoke
48+
$(AWS) lambda wait function-active-v2 --function-name $(FUNCTION_NAME)
49+
50+
deploy: deploy-aws ## Deploy the Lambda function (default AWS CLI)
51+
52+
# TODO: FIX TypeScript deployment
53+
deploy-aws: ## Deploy the Lambda function via AWS CLI
54+
$(AWS) lambda create-function \
55+
--function-name $(FUNCTION_NAME) \
56+
--runtime $(LAMBDA_RUNTIME) \
57+
--role arn:aws:iam::000000000000:role/lambda-role \
58+
--handler app.lambdaHandler \
59+
--zip-file fileb://hello-world/hello-world-javascript.zip \
60+
--timeout 2
61+
62+
deploy-sam: ## Deploy the Lambda function via AWS SAM CLI
63+
$(SAM) deploy
64+
65+
invoke: ## Invoke the Lambda function and show logs
66+
AWS_MAX_ATTEMPTS=1 $(AWS) lambda invoke --function-name $(FUNCTION_NAME) \
67+
--payload file://events/event.json \
68+
--cli-connect-timeout 3600 \
69+
--cli-read-timeout 3600 \
70+
--log-type Tail \
71+
response.json | jq .LogResult -r | base64 -d && cat response.json | jq -r .result
72+
73+
# TODO: avoid having the built zip file in the source directory
74+
clean: ## Clean the build directory
75+
rm -rf hello-world/hello-world-javascript.zip
76+
77+
start: ## Start LocalStack
78+
IMAGE_NAME=localstack/localstack-pro \
79+
LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} \
80+
LOCALSTACK_LAMBDA_DEBUG_MODE=1 \
81+
LOCALSTACK_LAMBDA_DEBUG_MODE_CONFIG_PATH=/tmp/lambda_debug_mode_config.yaml \
82+
localstack start --detached --volume ${PWD}/lambda_debug_mode_config.yaml:/tmp/lambda_debug_mode_config.yaml
83+
84+
stop: ## Stop LocalStack
85+
localstack stop
86+
87+
ready: ## Wait until LocalStack is running
88+
@echo Waiting on the LocalStack container...
89+
@localstack wait -t 30 && echo LocalStack is ready to use! || (echo Gave up waiting on LocalStack, exiting. && exit 1)
90+
91+
test-ci:
92+
make start install ready deploy wait invoke; return_code=`echo $$?`;\
93+
echo "Interactive debugging not tested in CI"; exit $$return_code;

‎lambda-debugging-sam-typescript/README.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Debug your TypeScript Lambda Function
2+
3+
This Hello World Lambda function written in JavaScript demonstrates how to use interactive breakpoint-debugging using LocalStack [Lambda Remote Debugging](https://docs.localstack.cloud/aws/tooling/lambda-tools/remote-debugging/).
4+
LocalStack automatically configures debugging and adjusts relevant timeouts.
5+
6+
We recommend the one-click setup using the AWS Toolkit for VS Code unless your advanced scenario requires Lambda Debug Mode (Preview).
7+
8+
> [!NOTE]
9+
> Check out our blog post [Developing with LocalStack using the AWS Toolkit for VS Code](#TODO-update-link)
10+
11+
## Prerequisites
12+
13+
* [Docker](https://www.docker.com/)
14+
* [VS Code](https://code.visualstudio.com/)
15+
* [LocalStack Toolkit for VS Code](https://marketplace.visualstudio.com/items?itemName=localstack.localstack) ≥ 1.2 installs [LocalStack](https://docs.localstack.cloud/aws/getting-started/installation/) ≥ 4.8
16+
* [AWS Toolkit for VS Code](https://marketplace.visualstudio.com/items?itemName=AmazonWebServices.aws-toolkit-vscode) ≥ 3.74
17+
* `make`
18+
* [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) or [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)
19+
20+
## Starting Up
21+
22+
1. Execute the VS Code command "LocalStack: Run Setup Wizard" using the LocalStack Toolkit
23+
2. Start LocalStack by clicking on the LocalStack Toolkit status bar
24+
25+
## Deploying
26+
27+
1. Run `make build`
28+
2. Run `make deploy`
29+
30+
## Debugging
31+
32+
1. Open the **Remote invoke configuration** in the AWS Toolkit
33+
1. Open the AWS Toolkit extension
34+
2. Expand the AWS Explorer and Lambda node
35+
3. Navigate to the function you want to debug, then choose the Invoke remotely icon ▶️ from the context menu
36+
2. Select the **Remote debugging** check box to display the remote debugging properties
37+
3. Specify the Local Root Path to your local handler file.
38+
4. Expand the `Remote debug additional configuration`, and set `Out files` to `.aws-sam/build/HelloWorldFunction`
39+
5. Set a breakpoint in your handler file by clicking in the gutter-margin
40+
6. Click the **Remote invoke** button to invoke the Lambda function
41+
42+
> [!NOTE]
43+
> **Debugging TypeScript with source maps**
44+
> Expand the `Remote debug additional configuration`, and set `Out files` to the directory containing the files `<filename>.js` and `<filename>.js.map`.
45+
> Double-check your path if you get the error "outFiles not valid or no js and map file found in outFiles, debug will continue without sourceMap support".
46+
> Notice the path is *relative to the VSCode workspace root*.
47+
> In this example:
48+
> * `.aws-sam/build/HelloWorldFunction` using workspace `code localstack-pro-samples/lambda-debugging-sam-typescript`
49+
> * `lambda-debugging-sam-typescript/.aws-sam/build/HelloWorldFunction` using workspace `code localstack-pro-samples`
50+
51+
## Lambda Debug Mode (Preview, Pro)
52+
53+
### Starting Up
54+
55+
1. Start LocalStack with the following configuration:
56+
57+
```sh
58+
LOCALSTACK_IMAGE_NAME=localstack/localstack-pro \
59+
LOCALSTACK_LAMBDA_DEBUG_MODE=1 \
60+
LOCALSTACK_LAMBDA_DEBUG_MODE_CONFIG_PATH=/tmp/lambda_debug_mode_config.yaml \
61+
localstack start --volume $PWD/lambda_debug_mode_config.yaml:/tmp/lambda_debug_mode_config.yaml
62+
```
63+
64+
* `IMAGE_NAME=localstack/localstack-pro` ensures the Pro image is started
65+
* `LOCALSTACK_LAMBDA_DEBUG_MODE=1` adjusts timeouts
66+
* `LOCALSTACK_LAMBDA_DEBUG_MODE_CONFIG_PATH=/tmp/lambda_debug_mode_config.yaml` points to the config file for Lambda debug mode allowing for advanced configuration. It maps the Lambda function `arn:aws:lambda:us-east-1:000000000000:function:HelloWorldFunctionTypeScript` to port `7050`.
67+
* `--volume $PWD/lambda_debug_mode_config.yaml:/tmp/lambda_debug_mode_config.yaml` maps the Lambda debug configuration from the host into the LocalStack Docker container for hot-reloading configuration updates.
68+
69+
### Deploying
70+
71+
1. Run `make build` to build the Lambda ZIP package
72+
2. Run `make deploy` to deploy the Lambda function
73+
74+
### Debugging
75+
76+
1. Open the sample folder in VS Code to auto-detect `.vscode/launch.json`
77+
2. Set a breakpoint in the handler file `hello-world/app.ts` by clicking in the gutter-margin
78+
3. Open the **Run and Debug** view in VS Code
79+
4. Run the **TypeScript: Remote Attach** task
80+
5. Run `make invoke` to invoke the Lambda function
81+
82+
## Troubleshooting
83+
84+
* Concurrent invokes are currently rejected with a `ResourceConflictException`.
85+
Upvote [this GitHub issue](https://github.com/localstack/localstack/issues/8522) if this affects you.
86+
87+
## License
88+
89+
The code in this sample is available under the Apache 2.0 license.

0 commit comments

Comments
 (0)