{"id":13596905,"url":"https://github.com/postlight/serverless-typescript-starter","last_synced_at":"2025-10-02T23:35:39.179Z","repository":{"id":38764453,"uuid":"79604857","full_name":"postlight/serverless-typescript-starter","owner":"postlight","description":"🗄🙅‍♀️ Deploy your next serverless JavaScript function in seconds","archived":true,"fork":false,"pushed_at":"2023-01-09T23:36:23.000Z","size":5409,"stargazers_count":711,"open_issues_count":28,"forks_count":62,"subscribers_count":47,"default_branch":"master","last_synced_at":"2024-09-29T06:21:37.356Z","etag":null,"topics":["aws","babel","eslint","jest","labs","lambda-functions","prettier","serverless","starter-kit","webpack"],"latest_commit_sha":null,"homepage":"https://postlight.com/labs/modern-serverless-starter-kit","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/postlight.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}},"created_at":"2017-01-20T22:09:47.000Z","updated_at":"2024-08-01T02:34:13.000Z","dependencies_parsed_at":"2023-02-08T16:01:51.726Z","dependency_job_id":null,"html_url":"https://github.com/postlight/serverless-typescript-starter","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/postlight%2Fserverless-typescript-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fserverless-typescript-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fserverless-typescript-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fserverless-typescript-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/postlight","download_url":"https://codeload.github.com/postlight/serverless-typescript-starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235051561,"owners_count":18928185,"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","babel","eslint","jest","labs","lambda-functions","prettier","serverless","starter-kit","webpack"],"created_at":"2024-08-01T16:02:56.327Z","updated_at":"2025-10-02T23:35:38.768Z","avatar_url":"https://github.com/postlight.png","language":"TypeScript","readme":"![logo](./logo.png)\n[![Greenkeeper badge](https://badges.greenkeeper.io/postlight/serverless-typescript-starter.svg)](https://greenkeeper.io/)\n[![CircleCI](https://circleci.com/gh/postlight/serverless-typescript-starter/tree/master.svg?style=svg)](https://circleci.com/gh/postlight/serverless-typescript-starter/tree/master)\n\n[Postlight](https://postlight.com)'s Modern Serverless Starter Kit adds a light layer on top of the Serverless framework, giving you the latest in modern JavaScript (ES6 via Webpack, TypeScript if you want it, testing with Jest, linting with ESLint, and formatting with Prettier), the ease and power of Serverless, and a few handy helpers (like functions for handling warm functions and response helpers).\n\nOnce installed, you can create and deploy functions with the latest ES6 features in minutes, with linting and formatting baked in.\n\nRead more about it in [this handy introduction](https://postlight.com/trackchanges/introducing-postlights-modern-serverless-starter-kit).\n\nNote: Currently, this starter kit specifically targets AWS.\n\n## Install\n\n```bash\n# If you don't already have the serverless cli installed, do that\nyarn global add serverless\n\n# Use the serverless cli to install this repo\nserverless install --url https://github.com/postlight/serverless-typescript-starter --name \u003cyour-service-name\u003e\n\n# cd into project and set it up\ncd \u003cyour-service-name\u003e\n\n# Install dependencies\nyarn install\n```\n\n## Development\n\nCreating and deploying a new function takes two steps, which you can see in action with this repo's default Hello World function (if you're already familiar with Serverless, you're probably familiar with these steps).\n\n#### 1. Add your function to `serverless.yml`\n\nIn the functions section of [`./serverless.yml`](./serverless.yml), you have to add your new function like so:\n\n```yaml\nfunctions:\n  hello:\n    handler: src/hello.default\n    events:\n      - http:\n          path: hello\n          method: get\n```\n\nIgnoring the scheduling event, you can see here that we're setting up a function named `hello` with a handler at `src/hello.ts` (the `.default` piece is just indicating that the function to run will be the default export from that file). The `http` event says that this function will run when an http event is triggered (on AWS, this happens via API Gateway).\n\n#### 2. Create your function\n\nThis starter kit's Hello World function (which you will of course get rid of) can be found at [`./src/hello.ts`](./src/hello.ts). There you can see a basic function that's intended to work in conjunction with API Gateway (i.e., it is web-accessible). Like most Serverless functions, the `hello` function is asynchronous and accepts an event \u0026 context. (This is all basic Serverless; if you've never used it, be sure to read through [their docs](https://serverless.com/framework/docs/).\n\n---\n\nYou can develop and test your lambda functions locally in a few different ways.\n\n### Live-reloading functions\n\nTo run the hello function with the event data defined in [`fixtures/event.json`](fixtures/event.json) (with live reloading), run:\n\n```bash\nyarn watch:hello\n```\n\n### API Gateway-like local dev server\n\nTo spin up a local dev server that will more closely match the API Gateway endpoint/experience:\n\n```bash\nyarn serve\n```\n\n### Test your functions with Jest\n\nJest is installed as the testrunner. To create a test, co-locate your test with the file it's testing\nas `\u003cfilename\u003e.test.ts` and then run/watch tests with:\n\n```bash\nyarn test\n```\n\n### Adding new functions/files to Webpack\n\nWhen you add a new function to your serverless config, you don't need to also add it as a new entry\nfor Webpack. The `serverless-webpack` plugin allows us to follow a simple convention in our `serverless.yml`\nfile which is uses to automatically resolve your function handlers to the appropriate file:\n\n```yaml\nfunctions:\n  hello:\n    handler: src/hello.default\n```\n\nAs you can see, the path to the file with the function has to explicitly say where the handler\nfile is. (If your function weren't the default export of that file, you'd do something like:\n`src/hello.namedExport` instead.)\n\n### Keep your lambda functions warm\n\nLambda functions will go \"cold\" if they haven't been invoked for a certain period of time (estimates vary, and AWS doesn't offer a clear answer). From the [Serverless blog](https://serverless.com/blog/keep-your-lambdas-warm/):\n\n\u003e Cold start happens when you execute an inactive (cold) function for the first time. It occurs while your cloud provider provisions your selected runtime container and then runs your function. This process, referred to as cold start, will increase your execution time considerably.\n\nA frequently running function won't have this problem, but you can keep your function running hot by scheduling a regular ping to your lambda function. Here's what that looks like in your `serverless.yml`:\n\n```yaml\ncustom:\n  warmup:\n    enabled: true\n    events:\n      - schedule: rate(5 minutes)\n    prewarm: true\n    concurrency: 2\n```\n\nThe above config would keep all of your deployed lambda functions running warm. The `prewarm` flag will ensure your function is warmed immediately after deploys (so you don't have to wait five minutes for the first scheduled event). And by setting the `concurrency` to `2`, we're keeping two instances warm for each deployed function.\n\nUnder `custom.warmup`, you can set project-wide warmup behaviors. On the other hand, if you want to set function-specific behaviours, you should use the `warmup` key under the select functions. You can browse all the options [here](https://www.npmjs.com/package/serverless-plugin-warmup#configuration).\n\nYour handler function can then handle this event like so:\n\n```javascript\nconst myFunc = (event, context, callback) =\u003e {\n  // Detect the keep-alive ping from CloudWatch and exit early. This keeps our\n  // lambda function running hot.\n  if (event.source === 'serverless-plugin-warmup') {\n    // serverless-plugin-warmup is the source for Scheduled events\n    return callback(null, 'pinged');\n  }\n\n  // ... the rest of your function\n};\n\nexport default myFunc;\n```\n\nCopying and pasting the above can be tedious, so we've added a higher order function to wrap your run-warm functions. You still need to config the ping in your `serverless.yml` file; then your function should look like this:\n\n```javascript\nimport runWarm from './utils';\n\nconst myFunc = (event, context, callback) =\u003e {\n  // Your function logic\n};\n\nexport default runWarm(myFunc);\n```\n\n### Pruning old versions of deployed functions\n\nThe Serverless framework doesn't purge previous versions of functions from AWS, so the number of previous versions can grow out of hand and eventually filling up your code storage. This starter kit includes [serverless-prune-plugin](https://github.com/claygregory/serverless-prune-plugin) which automatically prunes old versions from AWS. The config for this plugin can be found in `serverless.yml` file. The defaults are:\n\n```yaml\ncustom:\n  prune:\n    automatic: true\n    number: 5 # Number of versions to keep\n```\n\nThe above config removes all but the last five stale versions automatically after each deployment.\n\nGo [here](https://medium.com/fluidity/the-dark-side-of-aws-lambda-5c9f620b7dd2) for more on why pruning is useful.\n\n## Environment Variables\n\nIf you have environment variables stored in a `.env` file, you can reference them inside your `serverless.yml` and inside your functions. Considering you have a `NAME` variable:\n\nIn a function:\n\n```node\nprocess.env.NAME\n```\n\nIn `serverless.yml`:\n\n```yaml\nprovider:\n  name: ${env:NAME}\n  runtime: nodejs12.x\n```\n\nYou can check the documentation [here](https://www.npmjs.com/package/serverless-dotenv-plugin).\n\n## Deploy\n\nAssuming you've already set up your default AWS credentials (or have set a different AWS profile via [the profile field](serverless.yml#L25)):\n\n```bash\nyarn deploy\n```\n\n`yarn deploy` will deploy to \"dev\" environment. You can deploy to `stage` or `production`\nwith:\n\n```bash\nyarn deploy:stage\n\n# -- or --\n\nyarn deploy:production\n```\n\nAfter you've deployed, the output of the deploy script will give you the API endpoint\nfor your deployed function(s), so you should be able to test the deployed API via that URL.\n\n---\n\n🔬 A Labs project from your friends at [Postlight](https://postlight.com). Happy coding!\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostlight%2Fserverless-typescript-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpostlight%2Fserverless-typescript-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostlight%2Fserverless-typescript-starter/lists"}