{"id":21753715,"url":"https://github.com/tschoffelen/serverless-starter","last_synced_at":"2025-06-22T05:05:19.750Z","repository":{"id":40562760,"uuid":"378393481","full_name":"tschoffelen/serverless-starter","owner":"tschoffelen","description":"Starter boilerplate for a serverless API.","archived":false,"fork":false,"pushed_at":"2025-02-07T21:07:26.000Z","size":2173,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T19:24:11.560Z","etag":null,"topics":["aws-lambda","nodejs","serverless"],"latest_commit_sha":null,"homepage":"https://includable.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tschoffelen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2021-06-19T11:15:52.000Z","updated_at":"2025-03-24T17:01:02.000Z","dependencies_parsed_at":"2024-05-03T20:00:56.711Z","dependency_job_id":"8cacb86a-749a-47a2-836a-23b9635c09e0","html_url":"https://github.com/tschoffelen/serverless-starter","commit_stats":null,"previous_names":["tschoffelen/serverless-starter"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tschoffelen/serverless-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tschoffelen%2Fserverless-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tschoffelen%2Fserverless-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tschoffelen%2Fserverless-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tschoffelen%2Fserverless-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tschoffelen","download_url":"https://codeload.github.com/tschoffelen/serverless-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tschoffelen%2Fserverless-starter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261238895,"owners_count":23128879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["aws-lambda","nodejs","serverless"],"created_at":"2024-11-26T09:11:02.280Z","updated_at":"2025-06-22T05:05:14.714Z","avatar_url":"https://github.com/tschoffelen.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Boilerplate for Serverless APIs\n\nA quick way to get started building a serverless API.\n\n## Tech stack\n\n- [Serverless](https://www.serverless.com/framework/docs/providers/aws/guide/intro/) framework\n- [AWS API Gateway HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html)\n- [JWT authorizer](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html)\n  using [AWS Cognito](https://aws.amazon.com/cognito/)\n- [AWS DynamoDB](https://www.youtube.com/watch?v=6yqfmXiZTlM) database\n- [Jest](https://jestjs.io) for testing\n- [Github Actions](https://github.com/actions) for CI/CD\n\n## Getting started\n\n### 1. Name your service\n\nRename package name and service names:\n\n- [`serverless.yml` line 1](serverless.yml)\n- [`package.json` line 2](package.json)\n\n### 2. Dependencies\n\nInstall dependencies:\n\n```shell\nyarn\n```\n\n### 3. Custom domain (optional)\n\nUncomment the `serverless-domain-manager` plugin line and `custom.customDomain` lines in `serverless.yml`,\nand set the correct `custom.baseDomain` to set up a custom domain for your API.\n\n---\n\n## Running locally\n\nStart serverless-offline:\n\n```shell\nyarn start\n```\n\nThis will start a local HTTP server on [localhost:3000](http://localhost:3000/).\n\n### Authentication\n\nWhen using `yarn start`, we're using serverless-offline with the `--noAuth` flag, which means that API endpoints that\nhave an Authorizer set up will not check the JWT token in the `Authorization` header to authorize users as usual.\n\nInstead, it will read from the file [`tests/local-auth.txt`](tests/local-auth.txt) to\n[simulate an authentication context](https://github.com/dherault/serverless-offline#remote-authorizers). This will\nsimulate a user with user ID `c2dddd0e-fcb1-47ea-b232-cd24d05d8442`.\n\n### Database access\n\nThere are packages available to set up DynamoDB testing environments locally\n(see [`serverless-dynalite`](https://github.com/nearst/serverless-dynalite)\nfor example).\n\nWhat often seems easier, however, is to run a separate DynamoDB table in the cloud to test with during development. This\nprovides an environment that is the closest to production.\n\n**That's also the default mode for this service:**\n\n- When you run `yarn start`, serverless-offline is started, using the serverless stage 'local' by default. That means\n  that it will attempt to connect to a DDB table called `{service}-local` for any database interactions\n  (this happens by setting the `TABLE_NAME` env var in `serverless.yml`).\n- That does mean that you need AWS access. The AWS SDK will automatically try to use the credentials set up via the AWS\n  CLI (and stored in `~/.aws/credentails`).\n\n**A few tips:**\n\n- Default [stage](https://serverless-stack.com/chapters/stages-in-serverless-framework.html)\n  is `local` for both the `yarn start` and `yarn deploy` commands. You can supply a `--stage`\n  parameter to customize this (other values we use: `staging`, `production`).\n- Like everywhere with the AWS CLI, if you have\n  multiple [AWS profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html), you can use the\n  env var AWS_PROFILE to set the credentials set to be used:\n  `AWS_PROFILE=myprofile yarn start`\n\n### Invoke serverless function locally\n\nTo run a serverless function locally you can run the command `serverless invoke local -f users-get -p data.json`\nwhere `data.json` is the file containing the data for that request.\n\nYou can also use `serverless invoke local -f users-get --data '{ \"pathParameters\":{\"userId\":\"my-user-id\"} }'` to pass\nthe data inline.\n\nHave a look at the blog\npost [\"Local development with Serverless\"](https://tschoffelen.medium.com/local-development-with-serverless-46a219876a67#6bd7)\nfor more information.\n\n## Testing\n\nWe use Jest to do simple unit tests per function.\n\nWriting a test involves creating a file named `test.js`, calling the app function in your handler, and seeing if the\noutput and called features is what we expect given a certain input object.\n\nYou can run the tests using `yarn test`.\n\n## Deployment\n\nYou can deploy manually using the `yarn deploy` command. By default, this will deploy to the `local` stage, but it is\npossible to override this to manually deploy to production:\n\n```shell\nyarn deploy --stage production\n```\n\n\u003c!-- End of readme template --\u003e\n\n\u003cbr /\u003e\u003cbr /\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\t\u003cb\u003e\n\t\t\u003ca href=\"https://schof.co/consulting/?utm_source=includable/serverless-starter\"\u003eGet professional support for this package →\u003c/a\u003e\n\t\u003c/b\u003e\n\t\u003cbr\u003e\n\t\u003csub\u003e\n\t\tCustom consulting sessions availabe for implementation support and feature development.\n\t\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftschoffelen%2Fserverless-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftschoffelen%2Fserverless-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftschoffelen%2Fserverless-starter/lists"}