{"id":20840066,"url":"https://github.com/ackama/serverless-aws-template","last_synced_at":"2025-03-12T10:11:50.199Z","repository":{"id":39732666,"uuid":"330484776","full_name":"ackama/serverless-aws-template","owner":"ackama","description":null,"archived":false,"fork":false,"pushed_at":"2024-03-17T18:46:13.000Z","size":564,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":16,"default_branch":"main","last_synced_at":"2024-03-17T19:31:19.340Z","etag":null,"topics":["ackama","aws","aws-lambda","lambda","serverless","template","tooling","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/ackama.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}},"created_at":"2021-01-17T20:55:02.000Z","updated_at":"2024-03-17T19:31:22.697Z","dependencies_parsed_at":"2024-02-27T19:30:35.058Z","dependency_job_id":"3dcc81c7-ff9d-46fd-9682-701f71779fc4","html_url":"https://github.com/ackama/serverless-aws-template","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ackama%2Fserverless-aws-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ackama%2Fserverless-aws-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ackama%2Fserverless-aws-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ackama%2Fserverless-aws-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ackama","download_url":"https://codeload.github.com/ackama/serverless-aws-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243196664,"owners_count":20251861,"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":["ackama","aws","aws-lambda","lambda","serverless","template","tooling","typescript"],"created_at":"2024-11-18T01:15:09.981Z","updated_at":"2025-03-12T10:11:50.177Z","avatar_url":"https://github.com/ackama.png","language":"TypeScript","readme":"# serverless-aws-template\n\nA template repo for how to structure serverless functions powered by aws lambda.\n\nFor functions powered by AWS, we typically recommend having a single serverless\napp per project with each function having its own folder in `src`, and that code\nused in more than one function be placed `src/utils` (should your project have\nmultiple functions).\n\nIncluded in this template are some templates for configuring and typing\nfunctions to be invoked by a particular\n[event](https://www.serverless.com/framework/docs/providers/aws/events/) - since\nmost projects only require one or two functions, as part of setting up your repo\nfrom this template, you should pick out the functions that fit the tasks you\nwant to perform, rename them appropriately, and delete the rest.\n\nYou can also copy these functions along with their configurations into existing\nprojects if you wish.\n\n## Usage\n\nTo use this template, clone it locally and then remove the `.git` folder:\n\n```\ngit clone --depth=1 git@github.com:ackama/serverless-aws-template.git my-project-dir\ncd my-project-dir # change into the freshly cloned repos directory\nrm -rf .git    # remove the existing git repo\ngit init       # initalise a new git repo\n```\n\nThen you should:\n\n1. Replace all references to the template name (`serverless-aws-template`) with\n   the name of the project\n1. Remove any lambda templates you don't want to use, and rename the ones you do\n1. Remove this section of the readme, between (but not including) the project\n   name and \"Project Overview\" headers\n   - The remainder of this readme is written from the perspective of the\n     project, meaning\n1. Add the AWS credentials as secrets to the repo to allow CI to deploy:\n   - `STAGING_AWS_ACCESS_KEY_ID`\n   - `STAGING_AWS_SECRET_ACCESS_KEY`\n   - `PRODUCTION_AWS_ACCESS_KEY_ID`\n   - `PRODUCTION_AWS_SECRET_ACCESS_KEY`\n\n## Project Overview\n\n### Infrastructure\n\nserverless manages everything about the lambdas except the code itself,\nincluding:\n\n- packaging code into a zip file\n- deploying to specific stages (via an S3 bucket)\n- provisioning infrastructure (e.g, api gateways, sns topics, cloudwatch timers)\n- configuring permissions on the iam role used by the lambdas\n\nalong with any infrastructure resources needed to support them (e.g, api\ngateway, iam roles, s3 buckets).\n\nAll of this configuration is stored in `serverless.yml`. You can find details on\nall possible values supported by this file\n[here](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/).\n\nYou can find a general introduction to AWS on Serverless\n[here](https://www.serverless.com/framework/docs/providers/aws/guide/intro/).\n\nAdditional infrastructure is defined in `resources.yml`, which Serverless passes\nto CloudFormation to include as part of its Stack.\n\n#### Stages\n\nA \"stage\" in serverless is equivalent to what we typically refer to as an\n\"environment\" in our apps and infrastructure. Since serverless prefixed\nresources with the name of the stage they're for, we tend to favor shorthand\nnames for some environments (i.e \"prod\" for \"production\").\n\nYou can target a specific stage when running serverless commands with the\n`--stage` option; if omitted, it defaults to the `stage` property of the\n`provider` in `serverless.yml`:\n\n```shell\nsls package --stage prod\n\nsls deploy --stage staging\nsls deploy --stage prod\nsls deploy # uses the default stage\n\nsls invoke --stage uat\n```\n\n#### Environment variables\n\nYou set which environment variables are passed to your functions with the\n`environment` property, set at the `provider` level (to pass a variable to all\nlambdas), or at the `function` level (to pass a variable to only specific\nfunctions).\n\nNote that these two properties are merged when being applied to each function,\nrather than acting as an override.\n\nIf an environment variable is not found, Serverless will print a warning but\n_continue_ - this is important as it means CI won't fail when deploying if\nenvironment variables are missing.\n\nServerless supports reading `.env` and `.env.{stage}` files which can be useful\nwhen invoking functions locally; alternatively `direnv` can be used to set env\nvariables.\n\nDetails on how Serverless resolves environment variables can be found\n[here](https://www.serverless.com/framework/docs/environment-variables/).\n\n#### `IAM` policy statements\n\nBy default, the IAM role used by the lambdas only has basic permissions required\nto be deployed and invoked.\n\nYou can add more permissions to the default role using the `iamRoleStatements`\nprovider property. For example:\n\n```yaml\nprovider:\n  iam:\n    role:\n      statements:\n        - Effect: 'Allow'\n          Action:\n            - 'organizations:DescribeAccount'\n          Resource: '*'\n```\n\nYou can also create custom IAM roles for each function, detailed\n[here](https://www.serverless.com/framework/docs/providers/aws/guide/iam/).\n\n### Typechecking\n\nThis project is powered by TypeScript, with the types for the event handlers\nprovided by `@types/aws-lambda`.\n\nYou can type-check your project using the `typecheck` script:\n\n    npm run typecheck\n\nCompiling is done using the `build` command:\n\n    npm run build\n\nThis command is run by serverless (via `serverless-plugin-scripts`) before\npackaging or deploying due to custom configuration that can be found in the\n`serverless.yml` file.\n\nThis plugin dependency and its configuration can be removed if deployments are\ndone via CI, which ideally should be the case for all projects.\n\n### Linting\n\nLinting is powered by `eslint` with `prettier` and our standard eslint config\nsourced from `eslint-config-ackam`.\n\nYou can perform linting on your project using the `lint` script:\n\n    npm run lint\n\nYou can have `eslint` apply fixes where possible by passing `--fix`:\n\n    npm run lint -- --fix\n\nYou can run `prettier` on files not checked by `eslint` (such as `md` and `yml`\nfiles) using the `format` script:\n\n    npm run format\n\nYou can have `prettier` just report if any files need formatting by passing\n`--check`:\n\n    npm run format --check\n\nThis can be useful for CI, to ensure docs \u0026 `serverless.yml` remain well\nformatted.\n\n### Testing\n\nTesting is powered by `jest` and can run with the `test` script:\n\n    npm run test # or just npm test\n\nYou can get coverage information by passing `--coverage`:\n\n    npm run test -- --coverage\n\nTesting related code lives in the `test` directory, with the specs for specific\nfiles living in `test/src`. Ideally this folder should mirror `src` to make it\neasy to look up tests for particular files.\n\nOther code-related tests, like setup scripts, fixtures, and functions for\nbuilding common objects, should live within the `test` directory outside of\n`test/src`.\n\n### Deploying\n\nDeployments are done using the serverless cli, like so:\n\n    sls deploy --stage \u003cstage\u003e\n\nThis will trigger packaging up the code, uploading the resulting zip to an S3\nbucket, and then deploying that zip to an aws lambda based on the targeted\n`stage`.\n\nAny changes that need to be made to the infrastructure will also be applied as\npart of the deployment process as well.\n\nDeployments are done automatically via CI whenever new commits are pushed to\nspecific branches depending on the stage (`main` for `staging` and `production`\nfor `prod`).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fackama%2Fserverless-aws-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fackama%2Fserverless-aws-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fackama%2Fserverless-aws-template/lists"}