{"id":23078847,"url":"https://github.com/hernandosebastian/localstack-ts-api-gateway-lambda-dynamodb-crud-example","last_synced_at":"2026-04-14T14:32:11.211Z","repository":{"id":258864325,"uuid":"868518852","full_name":"hernandosebastian/localstack-ts-api-gateway-lambda-dynamodb-crud-example","owner":"hernandosebastian","description":"A serverless CRUD API example built with TypeScript, using API Gateway, Lambda, and DynamoDB, all simulated locally with LocalStack for efficient development and testing.","archived":false,"fork":false,"pushed_at":"2024-10-21T00:03:33.000Z","size":174,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-15T20:54:55.217Z","etag":null,"topics":["api-gateway","bash","cicd","crud","database-seeding","docker","docker-compose","dynamodb","dynamoose","example","jest","lambda","localstack","script","supertest","typescript","windows"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hernandosebastian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-06T15:37:05.000Z","updated_at":"2025-03-30T06:30:30.000Z","dependencies_parsed_at":"2024-10-21T02:53:47.558Z","dependency_job_id":null,"html_url":"https://github.com/hernandosebastian/localstack-ts-api-gateway-lambda-dynamodb-crud-example","commit_stats":null,"previous_names":["mipmipp/localstack-ts-api-gateway-lambda-dynamodb-crud-example","hernandosebastian/localstack-ts-api-gateway-lambda-dynamodb-crud-example"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hernandosebastian/localstack-ts-api-gateway-lambda-dynamodb-crud-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hernandosebastian%2Flocalstack-ts-api-gateway-lambda-dynamodb-crud-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hernandosebastian%2Flocalstack-ts-api-gateway-lambda-dynamodb-crud-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hernandosebastian%2Flocalstack-ts-api-gateway-lambda-dynamodb-crud-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hernandosebastian%2Flocalstack-ts-api-gateway-lambda-dynamodb-crud-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hernandosebastian","download_url":"https://codeload.github.com/hernandosebastian/localstack-ts-api-gateway-lambda-dynamodb-crud-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hernandosebastian%2Flocalstack-ts-api-gateway-lambda-dynamodb-crud-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31801285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T11:13:53.975Z","status":"ssl_error","status_checked_at":"2026-04-14T11:13:53.299Z","response_time":153,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","bash","cicd","crud","database-seeding","docker","docker-compose","dynamodb","dynamoose","example","jest","lambda","localstack","script","supertest","typescript","windows"],"created_at":"2024-12-16T11:06:06.124Z","updated_at":"2026-04-14T14:32:11.194Z","avatar_url":"https://github.com/hernandosebastian.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![LocalStack Pods Launchpad](https://localstack.cloud/gh/launch-pod-badge.svg)](https://app.localstack.cloud/launchpad?url=https://raw.githubusercontent.com/localstack/cloud-pod-badge/main/MyOwnPod) ![ts](https://badgen.net/badge/Built%20With/TypeScript/blue) ![Coverage](https://img.shields.io/badge/coverage-84.25%25-brightgreen)\n\n# Introduction\nThis repository is an example of a basic CRUD application, designed to test and work locally with [API Gateway](https://aws.amazon.com/api-gateway/) and [Lambda](https://aws.amazon.com/lambda/). It utilizes [TypeScript](https://www.typescriptlang.org/) and [DynamoDB](https://aws.amazon.com/dynamodb/) as the database ([Dynamoose](https://dynamoosejs.com/getting_started/Introduction) as an optional ORM library).\n\nAll AWS services are run locally using [LocalStack](https://www.localstack.cloud/) within [Docker](https://www.docker.com/), allowing for a seamless development experience. Everything is containerized, enabling end-to-end local testing using [Jest](https://jestjs.io/) and [Supertest](https://www.npmjs.com/package/supertest) while seeding the database. All operations are run via scripts to simplify the process of packaging code for Lambda, along with its [dependencies as a layer](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html).\n\n## LocalStack Services\n\nThis project utilizes the following LocalStack services:\n\n- **API Gateway**: [LocalStack API Gateway Documentation](https://docs.localstack.cloud/user-guide/aws/apigateway/)\n- **Lambda**: [LocalStack Lambda Documentation](https://docs.localstack.cloud/user-guide/aws/lambda/)\n- **DynamoDB**: [LocalStack DynamoDB Documentation](https://docs.localstack.cloud/user-guide/aws/dynamodb/)\n\n## Clarification\n\nEverything has been tested on Windows; it has not been tested on Ubuntu or other operating systems. However, the libraries are cross-platform, so it shouldn't be too difficult to set everything up.\n\n## Dependencies\n\n- [**Docker**](https://www.docker.com/): To run the localstack Docker image.\n- [**7zip**](https://www.7-zip.org/): Installed and added to the PATH in environment variables to zip the code.\n- [**AWS CLI**](https://docs.aws.amazon.com/streams/latest/dev/setup-awscli.html): To run various localstack commands.\n- Ensure that the scripts run in the Windows console, as they may not execute properly in environments like VSCode.\n\n## Run Locally\n\n### Clone the project\n\n```bash\ngit clone https://github.com/Mipmipp/localstack-ts-api-gateway-lambda-dynamodb-crud-example.git\n```\n\n### Go to the project directory\n\n```bash\ncd localstack-ts-api-gateway-lambda-dynamodb-crud-example\n```\n\n### Install dependencies\n\n```bash\nnpm ci\n```\n\n### Start the server\n\n```bash\nnpm run start:dev\n```\n\n## Environment Variables\n\nTo run this project, rename the `.env.dist` file to `.env` and populate it with the necessary environment variables.\n\n## Running Tests\n\nTo run tests in the console:\n\n```bash\nnpm run test:dev\n```\n\n## Package Scripts\n\n| Command                                      | Description                                                                                              |\n|----------------------------------------------|----------------------------------------------------------------------------------------------------------|\n| `test:e2e`                                   | Runs end-to-end tests.                                                                                  |\n| `test:handler`                               | Runs unit tests against the handler index.                                                              |\n| `prebuild`                                   | Deletes the `dist` folder.                                                                               |\n| `create-package`                             | Creates an empty `package.json` in `temp-dependencies-layer`.                                          |\n| `build:index`                                | Transpiles the `index.ts` code to JavaScript with a global handler banner in the output directory.       |\n| `build:src`                                  | Transpiles all TypeScript files excluding `index.ts`.                                                  |\n| `build:dependencies`                         | Edits a temp folder for non-development dependencies.                                                   |\n| `build`                                      | Runs the commands to build the project.                                                                  |\n| `postbuild`                                  | Zips the contents of the temp folders to `dist` and deletes the temp folders.                           |\n| `start:local-db`                             | Runs scripts to start the local DynamoDB instance.                                                      |\n| `seed:local-db`                              | Runs scripts to seed the local database.                                                                 |\n| `start:local-api`                            | Runs scripts to start the local API Gateway and Lambda.                                                |\n| `wait-for-docker`                            | Runs scripts to wait for Docker to be ready.                                                            |\n| `start:dev`                                  | Runs the complete setup for local development, including Docker and local database initialization.        |\n| `test:dev`                                   | Runs the complete setup for local testing, including Docker and end-to-end tests.                       |\n\n## Bash Scripts\n\n| Script Name                                   | Description                                                                                              |\n|-----------------------------------------------|----------------------------------------------------------------------------------------------------------|\n| **`seed_local_dynamodb.sh`**                  | Seeds the local database with various items (can be omitted or edited).                                 |\n| **`start_local_api_gateway_and_lambda.sh`**  | Configures everything, deploying functions with the zipped handler code, creating Lambda functions, API Gateway, connecting endpoints, and generating a `.local.env` file with the endpoint and local API ID. This can be edited for various CRUD resources. |\n| **`start_local_dynamodb.sh`**                 | Creates an empty local database (can be updated to include tables and more).                            |\n| **`wait-for-docker.sh`**                      | Pings the Docker container endpoint to check if everything is up and running.                           |\n\n## Local Endpoint\n\nOnce the scripts are executed, the `.local.env` file will contain the `LOCAL_API_ENDPOINT` variable, created by LocalStack. This changes with the `LOCAL_API_ID`, which is also stored for potential use in tests.\n\n## Files for Lambda Deployment\n\nIn the `dist` directory, you will find:\n- **`index.zip`**: Minified JavaScript code from `src` ready for AWS Lambda deployment.\n- **`dependencies-layer.zip`**: Non-development dependencies packaged for Lambda as a layer.\n\n## Database Suggestions\n\nTo manage and view your local DynamoDB database, we recommend using [**AWS NoSQL Workbench**](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.html). This tool provides a user-friendly interface for querying and visualizing data.\n\n### Quick Setup Guide\n\n1. **Install AWS NoSQL Workbench**: Download from the [AWS NoSQL Workbench website](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.settingup.html).\n\n2. **Open the Application**: Launch NoSQL Workbench after installation.\n\n3. **Add a Connection**:\n   - Navigate to the **\"Operation Builder\"** tab.\n   - Click **\"Add connection\"** and select **\"DynamoDB Local\"**.\n\n4. **Configure Connection**:\n   - Set the host to `localhost` and the port to `4566` (or your configured port).\n   - Test the connection to ensure it's working.\n\n5. **Start Managing Your Data**: Use the Operation Builder to run queries, insert items, and visualize your database.\n \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhernandosebastian%2Flocalstack-ts-api-gateway-lambda-dynamodb-crud-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhernandosebastian%2Flocalstack-ts-api-gateway-lambda-dynamodb-crud-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhernandosebastian%2Flocalstack-ts-api-gateway-lambda-dynamodb-crud-example/lists"}