This repo is part of this blog: https://blog.cloudglance.dev/trpc-separate-backend-frontend-with-openapi-aws-lambda-cdk/index.html
This project consists of a single API Lambda function deployed to AWS that can be accessed using the Function URL(FURL). The AWS CDK has been used to define the IaC and the Lambda is written in TS.
It features the following:
- Showcases tRPC + trpc-openapi
- Generates an OpenAPI spec file from the tRPC code and then from that a JS API SDK, TS types and sourcemaps
- The API SDK is pushed to GitHub and also published to GitHub Packages (similar to NPM)
- A build system that consists of npm scripts, wireit and a custom TS file used to execute commands
- Tests setup for both unit and e2e
- Local development by creating an express server from the tRPC lambda code
- Other:
- Uses esbuild and the
esbuild-runner
package instead oftsc
orts-node
- Vitest is being used for tests
- Has ESLint + Prettier setup
- It has API endpoints to get all pets, a single pet and to create a pet. It also has an endpoint to show the OpenAPI spec nicely formatted in HTML.
- Uses esbuild and the
The configuration is done in the config/index.ts
file. The file has been committed with actual values for the purpose
of this blog. Replace the values with your own, see description of the types in the file.
OPTIONALLY, if you intend to publish the package to GH Packages, you will need to:
- Create a Personal Access Token(PAT) on GitHub so that we can write the SDK API NPM package. You need to assign the flowing permissions:
-
write:packages
Upload packages to the GitHub Package Registry
- Make a copy of the
.npmrc.example
file and replace: -<YOUR PERSONAL ACCESS TOKEN HERE>
with your GitHub Personal Access Token (PAT) that you obtained above -<YOUR GITHUB PROFILE OR ORGANIZATION NAME>
with your GutHub username of where the package is installed
Useful commands:
-
npm run build-src
- Builds this project source, transpiling the TS to JS for the Lambda function and storing the JS in thedist
folder which is then used by the Lambda. -
npm run cdk-diff
- Runsbuild-src
and then thecdk diff
command. -
npm run cdk-deploy
- Runsbuild-src
and then thecdk deploy
command. This deploys the Lambda + Function URL(FURL) and will produce a URL in the CloudFormation (CFN) output section that you must copy to the frontend production environment file. -
npm run cdk-hotswap
- Runsbuild-src
and then thecdk deploy --hotswap
command. The hotswap command is used for quick iteration of the deployed Lambda code.
-
npm run start-local-api-watch
- Starts an express server that serves the Lambda function for local development. -
npm run build-api-package
- Generates the OpenAPI Spec and the API SDK to theapi-packages
folder. -
npm run publish-api-package
- Runs thebuild-api-package
again and publishes the API SDK to GitHub Packages.
-
npm run lint-fix
- Runs eslint and prettier on the project and fixes all linting and formatting issues (also runs in the hsuky git pre commit hook). -
npm run test-unit
- Runs the tests defined in the/tests
folder. -
npm run test-e2e
- Runs the tests defined in the/tests
folder, make sure theTEST_VARIABLES
in theconfig/index.ts
file are set correctly. The only important property for e2e tests is theapi_url
which is the Function URL of the deployed Lambda.
See the frontend docs here: https://github.com/rehanvdm/pets-frontend-v2