Skip to content

Commit 611609f

Browse files
WarFoxWarFox
authored
docs(examples): add Typescript example (#453)
* chore(example): using typescript with express.js and API Gateway v2 * chore(example): don't run jest tests in typescript example * chore: new .gitignore file under examples directory
1 parent 0e316ec commit 611609f

File tree

17 files changed

+9204
-1
lines changed

17 files changed

+9204
-1
lines changed

‎examples/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
lambda-invoke-response.json
2+
.aws-sam

‎examples/basic-starter-api-gateway-v2-typescript/.mocharc.yaml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
require:
3+
- ts-node/register
4+
extensions:
5+
- ts
6+
spec:
7+
- tests/**/*.test.*
8+
watch-files:
9+
- src
10+
- tests

‎examples/basic-starter-api-gateway-v2-typescript/README.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Example
2+
3+
In addition to a basic Lambda function and Express server, the `example`
4+
directory includes a [Swagger file](http://swagger.io/specification/),
5+
[CloudFormation
6+
template](https://aws.amazon.com/cloudformation/aws-cloudformation-templates/)
7+
with [Serverless Application Model
8+
(SAM)](https://github.com/awslabs/serverless-application-model), and helper
9+
scripts to help you set up and manage your application.
10+
11+
## Steps for running the example
12+
13+
This guide assumes you have already [set up an AWS
14+
account](http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/AboutAWSAccounts.html)
15+
and have the latest version of the [AWS CLI](https://aws.amazon.com/cli/) and
16+
[AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
17+
installed.
18+
19+
1. From your preferred project directory:
20+
```sh
21+
git clone https://github.com/vendia/serverless-express.git && cd serverless-express/examples/basic-starter-api-gateway-v2-typescript
22+
```
23+
1. Update the `config` section of `package.json` with your `s3BucketName` and
24+
`region` (optionally, change the `cloudFormationStackName`). If the bucket
25+
you specify does not yet exist, the next step will create it for you.
26+
1. (optional: domain) If you want to use a custom domain name for your
27+
application/API, specify it in the `config.domain` section of `package.json`.
28+
This example assumes the domain is registered in Route53 in the same account
29+
you're deploying the example to.
30+
1. Run `npm run setup` - this installs the node dependencies, creates an S3
31+
bucket (if it does not already exist), packages and deploys your serverless
32+
Express application to AWS Lambda, and creates an API Gateway proxy API.
33+
1. (optional: domain) If you specify a domain, the example will create an SSL
34+
Certificate via Amazon Certificate Manager; create an API Gateway Domain Name
35+
record which maps the domain to the API and Stage; and create a Route53
36+
HostedZone and RecordSet with an A record pointing at the API Gateway Domain
37+
Name's CloudFront Distribution.
38+
1. During deployment you should receive an email at one of the registered
39+
email addresses for the domain. Approve the SSL Certificate by clicking
40+
the link in the email. The stack creation will pause while waiting for
41+
this approval.
42+
1. Wait for stack creation to complete and update Route53 Domain Name to use
43+
the Name Servers from the created Hosted Zone NS Record (don't include the
44+
trailing '.') via the AWS console.
45+
1. It may take several hours before the DNS records propagate.
46+
1. After the setup command completes, open the AWS CloudFormation console
47+
https://console.aws.amazon.com/cloudformation/home and switch to the region
48+
you specified. Select the `ServerlessExpressStack` stack (or the stack name
49+
you specified for `cloudFormationStackName`), then click the `ApiUrl` value
50+
under the __Outputs__ section - this will open a new page with your running
51+
API. The API index lists the resources available in the example Express
52+
server (`app.js`), along with example `curl` commands.
53+
1. (optional) To enable the `invoke-lambda` `package.json` `script`: copy the
54+
`LambdaFunctionName` from the CloudFormation Outputs and paste it into the
55+
`package.json` `config`'s `functionName` property.
56+
Run `npm run invoke-lambda` to invoke the Lambda Function with the payload
57+
specified in `api-gateway-event.json`.
58+
59+
See the sections below for details on how to migrate an existing (or create a
60+
new) Node.js project based on this example. If you would prefer to delete AWS
61+
assets that were just created, simply run `npm run delete-stack` to delete the
62+
CloudFormation Stack, including the API and Lambda Function. If you specified a
63+
new bucket in the `config` command for step 1 and want to delete that bucket,
64+
run `npm run delete-bucket`.
65+
66+
## Creating or migrating a Node.js project based on the example
67+
68+
To use this example as a base for a new Node.js project:
69+
70+
1. Copy the files in the `examples/basic-starter-api-gateway-v2-typescript`
71+
directory into a new project directory (`cp -r
72+
./examples/basic-starter-api-gateway-v2-typescript
73+
~/projects/my-new-node-project`). If you have not already done so, follow the
74+
[steps for running the example](#steps-for-running-the-example) (you may want
75+
to first modify some of the resource names to something more
76+
project-specific, eg. the CloudFormation stack, Lambda function, and API
77+
Gateway API).
78+
1. After making updates to `app.js`, simply run `npm run package-deploy`.
79+
80+
To migrate an existing Node server:
81+
82+
1. Copy the following files from this directory: `api-gateway-event.json`,
83+
`sam-template.yaml`, and `lambda.js`. Additionally, copy the `scripts` and
84+
`config` sections of `example/package.json` into your existing
85+
`package.json` - this includes many helpful commands to manage your AWS
86+
serverless assets and perform _basic_ local simulation of API Gateway and
87+
Lambda. If you have not already done so, follow the [steps for running the
88+
example](#steps-for-running-the-example).
89+
1. From your existing project directory, run
90+
```sh
91+
npm install --save @vendia/serverless-express
92+
```
93+
1. Modify `lambda.ts` to import your own server configuration (eg. change
94+
`require('./app')` to `require('./server')`). You will need to ensure you
95+
export your app configuration from the necessary file (eg. `module.exports =
96+
app`). This library takes your app configuration and listens on a Unix Domain
97+
Socket for you, so you can remove your call to `app.listen()`.
98+
1. Modify the `CodeUri` property of the Lambda function resource in
99+
`sam-template.yaml` to point to your application directory (e.g. `CodeUri:
100+
./src`). If you are using a build tool (e.g. Gulp, Grunt, Webpack, Rollup,
101+
etc.), you will instead want to point to your build output directory.
102+
1. Run `npm run package-deploy`.
103+
104+
To perform a basic, local simulation of API Gateway and Lambda with your Node
105+
server, update `api-gateway-event.json` with some values that are valid for your
106+
server (`httpMethod`, `path`, `body` etc.) and run `npm run local`.
107+
108+
If you need to make modifications to your API Gateway API or other AWS
109+
resources, modify `sam-template.yaml` and run `npm run package-deploy`.
110+
111+
## Node.js version
112+
113+
This example was written against Node.js 12
114+
115+
## Development
116+
117+
To update this example against the latest local changes to
118+
@vendia/serverless-express:
119+
120+
```bash
121+
npm i ../..
122+
npm run build
123+
npm run local
124+
```

‎examples/basic-starter-api-gateway-v2-typescript/api-gateway-event.json‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
{
2+
"version": "2.0",
3+
"routeKey": "$default",
4+
"rawPath": "/users",
5+
"rawQueryString": "",
6+
"headers": {
7+
"accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
8+
"accept-encoding": "gzip, deflate, br",
9+
"accept-language": "en-US,en;q=0.9",
10+
"cache-control": "max-age=0",
11+
"content-length": "0",
12+
"host": "6bwvllq3t2.execute-api.us-east-1.amazonaws.com",
13+
"sec-fetch-dest": "document",
14+
"sec-fetch-mode": "navigate",
15+
"sec-fetch-site": "none",
16+
"sec-fetch-user": "?1",
17+
"upgrade-insecure-requests": "1",
18+
"user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
19+
"x-amzn-trace-id": "Root=1-5ff59707-4914805430277a6209549a59",
20+
"x-forwarded-for": "203.123.103.37",
21+
"x-forwarded-port": "443",
22+
"x-forwarded-proto": "https"
23+
},
24+
"requestContext": {
25+
"accountId": "347971939225",
26+
"apiId": "6bwvllq3t2",
27+
"domainName": "6bwvllq3t2.execute-api.us-east-1.amazonaws.com",
28+
"domainPrefix": "6bwvllq3t2",
29+
"http": {
30+
"method": "GET",
31+
"path": "/users",
32+
"protocol": "HTTP/1.1",
33+
"sourceIp": "203.123.103.37",
34+
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36"
35+
},
36+
"requestId": "YuSJQjZfoAMESbg=",
37+
"routeKey": "$default",
38+
"stage": "$default",
39+
"time": "06/Jan/2021:10:55:03 +0000",
40+
"timeEpoch": 1609930503973
41+
},
42+
"isBase64Encoded": false
43+
}

‎examples/basic-starter-api-gateway-v2-typescript/nodemon.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"watch": ["src"],
3+
"ext": "ts",
4+
"ignore": ["src/public"],
5+
"exec": "set DEBUG=http & set NODE_ENV=dev && ts-node src/app.local.ts"
6+
}

0 commit comments

Comments
 (0)