{"id":13483827,"url":"https://github.com/CodeGenieApp/serverless-express","last_synced_at":"2025-03-27T15:30:33.716Z","repository":{"id":37931301,"uuid":"68155722","full_name":"CodeGenieApp/serverless-express","owner":"CodeGenieApp","description":"Run Express and other Node.js frameworks on AWS Serverless technologies such as Lambda, API Gateway, Lambda@Edge, and more.","archived":false,"fork":false,"pushed_at":"2024-08-14T11:01:02.000Z","size":26038,"stargazers_count":5136,"open_issues_count":92,"forks_count":668,"subscribers_count":101,"default_branch":"mainline","last_synced_at":"2024-10-05T11:01:56.987Z","etag":null,"topics":["alb","api-gateway","aws","aws-lambda","aws-serverless","dynamodb","express","express-js","expressjs","hacktoberfest","lambda","node","node-js","nodejs","sam","serverless","serverless-applications","serverless-express","serverless-framework","vendia"],"latest_commit_sha":null,"homepage":"https://codegenie.codes","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CodeGenieApp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2016-09-13T23:29:07.000Z","updated_at":"2024-10-01T21:35:19.000Z","dependencies_parsed_at":"2023-02-13T18:46:52.213Z","dependency_job_id":"3d612b83-1d60-45ea-abbe-3b9d1c921e39","html_url":"https://github.com/CodeGenieApp/serverless-express","commit_stats":{"total_commits":489,"total_committers":61,"mean_commits":8.01639344262295,"dds":0.5950920245398773,"last_synced_commit":"f05b3ab6dd572862b926fe13bf82741dca65ca0d"},"previous_names":["awslabs/aws-serverless-express","vendia/serverless-express","codegenieapp/serverless-express","brettstack/serverless-express"],"tags_count":93,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeGenieApp%2Fserverless-express","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeGenieApp%2Fserverless-express/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeGenieApp%2Fserverless-express/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeGenieApp%2Fserverless-express/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CodeGenieApp","download_url":"https://codeload.github.com/CodeGenieApp/serverless-express/tar.gz/refs/heads/mainline","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245175395,"owners_count":20572783,"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":["alb","api-gateway","aws","aws-lambda","aws-serverless","dynamodb","express","express-js","expressjs","hacktoberfest","lambda","node","node-js","nodejs","sam","serverless","serverless-applications","serverless-express","serverless-framework","vendia"],"created_at":"2024-07-31T17:01:15.687Z","updated_at":"2025-03-27T15:30:33.675Z","avatar_url":"https://github.com/CodeGenieApp.png","language":"JavaScript","readme":"\n\u003ch2 align=\"center\"\u003eServerless Express by\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://codegenie.codes\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/CodeGenieApp/serverless-express/mainline/code-genie-logo-gh.jpg\" alt=\"Code Genie Logo\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp width=200\u003e\n\nStarting a new software project? Check out Code Genie - a \u003ca href=\"https://codegenie.codes\"\u003eFull Stack App Generator\u003c/a\u003e that delivers a complete AWS Serverless project with source code, based on your data model. Including:\n\n1. A React Next.js Web App hosted on Amplify Hosting\n1. Serverless Express REST API running on API Gateway and Lambda\n1. Cognito User Pools for Identity/Authentication\n1. DynamoDB Database\n1. Cloud Development Kit (CDK) for Infrastructure as Code (IAC)\n1. Continuous Integration/Delivery (CI/CD) with GitHub Actions\n\u003c/p\u003e\n\n# Serverless Express\n\n\u003cp align=\"center\"\u003e\n  \u003ca aria-label=\"NPM version\" href=\"https://www.npmjs.com/package/@codegenie/serverless-express\"\u003e\n    \u003cimg alt=\"\" src=\"https://img.shields.io/npm/v/@codegenie/serverless-express.svg?style=for-the-badge\u0026labelColor=000000\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"License\" href=\"https://github.com/CodeGenieApp/serverless-express/blob/mainline/LICENSE\"\u003e\n    \u003cimg alt=\"\" src=\"https://img.shields.io/npm/l/@codegenie/serverless-express.svg?style=for-the-badge\u0026labelColor=000000\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"Number of Downloads\" href=\"https://www.npmjs.com/package/@codegenie/serverless-express\"\u003e\n    \u003cimg alt=\"\" src=\"https://img.shields.io/npm/dm/@vendia/serverless-express.svg?style=for-the-badge\u0026labelColor=000000\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"Contributor Covenant\" href=\"CODE_OF_CONDUCT.md\"\u003e\n    \u003cimg alt=\"\" src=\"https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg?style=for-the-badge\u0026labelColor=000000\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"Made by Code Genie\" href=\"https://codegenie.codes\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/MADE%20BY%20Code%20Genie-000000.svg?style=for-the-badge\u0026logo=Code%20Genie\u0026labelColor=000\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nRun REST APIs and other web applications using your existing [Node.js](https://nodejs.org/) application framework (Express, Koa, Hapi, Sails, etc.), on top of [AWS Lambda](https://aws.amazon.com/lambda/) and [Amazon API Gateway](https://aws.amazon.com/api-gateway/) or [Azure Function](https://docs.microsoft.com/en-us/azure/azure-functions/).\n\n```bash\nnpm install @codegenie/serverless-express\n```\n\n## Quick Start/Example\n\nWant to get up and running quickly? [Check out our basic starter example](examples/basic-starter-api-gateway-v1) that includes:\n\n- Lambda function\n- Express application\n- [Serverless Application Model (SAM)](https://github.com/awslabs/serverless-application-model)/[CloudFormation](https://aws.amazon.com/cloudformation/aws-cloudformation-templates/) template\n- Helper scripts to configure, deploy, and manage your application\n\nIf you want to migrate an existing application to AWS Lambda, it's advised to get the minimal example up and running first, and then copy your application source in.\n\n## AWS\n\n### Minimal Lambda handler wrapper\n\nThe only AWS Lambda specific code you need to write is a simple handler like below. All other code you can write as you normally do.\n\n```js\n// lambda.js\nconst serverlessExpress = require('@codegenie/serverless-express')\nconst app = require('./app')\nexports.handler = serverlessExpress({ app })\n```\n\n### Async setup Lambda handler\n\nIf your application needs to perform some common bootstrap tasks such as connecting to a database before the request is forward to the API, you can use the following pattern (also available in [this example](https://github.com/CodeGenieApp/serverless-express/blob/mainline/examples/basic-starter-api-gateway-v2/src/lambda-async-setup.js)):\n\n```js\n// lambda.js\nrequire('source-map-support/register')\nconst serverlessExpress = require('@codegenie/serverless-express')\nconst app = require('./app')\n\nlet serverlessExpressInstance\n\nfunction asyncTask () {\n  return new Promise((resolve) =\u003e {\n    setTimeout(() =\u003e resolve('connected to database'), 1000)\n  })\n}\n\nasync function setup (event, context) {\n  const asyncValue = await asyncTask()\n  console.log(asyncValue)\n  serverlessExpressInstance = serverlessExpress({ app })\n  return serverlessExpressInstance(event, context)\n}\n\nfunction handler (event, context) {\n  if (serverlessExpressInstance) return serverlessExpressInstance(event, context)\n\n  return setup(event, context)\n}\n\nexports.handler = handler\n```\n\n## Azure\n\n### Async Azure Function v3/v4 handler wrapper\n\nThe only Azure Function specific code you need to write is a simple `index.js` and a `function.json` like below.\n\n```js\n// index.js\nconst serverlessExpress = require('@codegenie/serverless-express')\nconst app = require('./app')\nconst cachedServerlessExpress = serverlessExpress({ app })\n\nmodule.exports = async function (context, req) {\n  return cachedServerlessExpress(context, req)\n}\n```\n\nThe _out-binding_ parameter `\"name\": \"$return\"` is important for Serverless Express to work.\n\n```json\n// function.json\n{\n  \"bindings\": [\n    {\n      \"authLevel\": \"anonymous\",\n      \"type\": \"httpTrigger\",\n      \"direction\": \"in\",\n      \"name\": \"req\",\n      \"route\": \"{*segments}\"\n    },\n    {\n      \"type\": \"http\",\n      \"direction\": \"out\",\n      \"name\": \"$return\"\n    }\n  ]\n}\n```\n\n## 4.x\n\n1. Improved API - Simpler for end-user to use and configure.\n1. Promise resolution mode by default. Can specify `resolutionMode` to use `\"CONTEXT\"` or `\"CALLBACK\"`\n1. Additional event sources - API Gateway V1 (REST API), API Gateway V2 (HTTP API), ALB, Lambda@Edge\n1. Custom event source - If you have another event source you'd like to use that we don't natively support, check out the [DynamoDB Example](examples/custom-mapper-dynamodb)\n1. Implementation uses mock Request/Response objects instead of running a server listening on a local socket. Thanks to @dougmoscrop from https://github.com/dougmoscrop/serverless-http\n1. Automatic `isBase64Encoded` without specifying `binaryMimeTypes`. Use `binarySettings` to customize. Thanks to @dougmoscrop from https://github.com/dougmoscrop/serverless-http\n1. `respondWithErrors` makes it easier to debug during development\n1. Node.js 12+\n1. Improved support for custom domain names\n\nSee [UPGRADE.md](UPGRADE.md) to upgrade from aws-serverless-express and @codegenie/serverless-express 3.x\n\n## API\n\n### binarySettings\n\nDetermine if the response should be base64 encoded before being returned to the event source, for example, when returning images or compressed files. This is necessary due to API Gateway and other event sources not being capable of handling binary responses directly. The event source is then responsible for turning this back into a binary format before being returned to the client.\n\nBy default, this is determined based on the `content-encoding` and `content-type` headers returned by your application. If you need additional control over this, you can specify `binarySettings`.\n\n```js\n{\n  binarySettings: {\n    isBinary: ({ headers }) =\u003e true,\n    contentTypes: ['image/*'],\n    contentEncodings: []\n  }\n}\n```\n\nAny value you provide here should also be specified on API Gateway API. In SAM, this looks like:\n\n```yaml\nExpressApi:\n  Type: AWS::Serverless::Api\n  Properties:\n    StageName: prod\n    BinaryMediaTypes: ['image/*']\n```\n\n### resolutionMode (default: `'PROMISE'`)\n\nLambda supports three methods to end the execution and return a result: context, callback, and promise. By default, serverless-express uses promise resolution, but you can specify 'CONTEXT' or 'CALLBACK' if you need to change this. If you specify 'CALLBACK', then `context.callbackWaitsForEmptyEventLoop = false` is also set for you.\n\n```js\nserverlessExpress({\n  app,\n  resolutionMode: 'CALLBACK'\n})\n```\n\n### respondWithErrors (default: `process.env.NODE_ENV === 'development'`)\n\nSet this to true to have serverless-express include the error stack trace in the event of an unhandled exception. This is especially useful during development. By default, this is enabled when `NODE_ENV === 'development'` so that the stack trace isn't returned in production.\n\n## Advanced API\n\n### eventSource\n\nserverless-express natively supports API Gateway, ALB, and Lambda@Edge. If you want to use Express with other AWS Services integrated with Lambda you can provide your own custom request/response mappings via `eventSource`. See the [custom-mapper-dynamodb example](examples/custom-mapper-dynamodb).\n\n```js\nfunction requestMapper ({ event }) {\n  // Your logic here...\n\n  return {\n    method,\n    path,\n    headers\n  }\n}\n\nfunction responseMapper ({\n  statusCode,\n  body,\n  headers,\n  isBase64Encoded\n}) {\n  // Your logic here...\n\n  return {\n    statusCode,\n    body,\n    headers,\n    isBase64Encoded\n  }\n}\n\nserverlessExpress({\n  app,\n  eventSource: {\n    getRequest: requestMapper,\n    getResponse: responseMapper\n  }\n})\n```\n\n#### eventSourceRoutes\n\nA single function can be configured to handle additional kinds of AWS events:\n- SNS\n- DynamoDB Streams\n- SQS\n - EventBridge Events (formerlly CloudWatch Events)\n\nAssuming the following function configuration in `serverless.yml`:\n\n```yaml\nfunctions:\n  lambda-handler:\n    handler: src/lambda.handler\n    events:\n      - http:\n          path: /\n          method: get\n      - sns:\n          topicName: my-topic\n      - stream:\n          type: dynamodb\n          arn: arn:aws:dynamodb:us-east-1:012345678990:table/my-table/stream/2021-07-15T15:05:51.683\n      - sqs:\n          arn: arn:aws:sqs:us-east-1:012345678990:myQueue\n      - eventBridge:\n          pattern:\n            source:\n              - aws.cloudformation\n```\n\nAnd the following configuration:\n\n```js\nserverlessExpress({\n  app,\n  eventSourceRoutes: {\n    'AWS_SNS': '/sns',\n    'AWS_DYNAMODB': '/dynamodb',\n    'AWS_SQS': '/sqs'\n    'AWS_EVENTBRIDGE': '/eventbridge',\n    'AWS_KINESIS_DATA_STREAM': '/kinesis',\n    'AWS_S3': '/s3',\n    'AWS_STEP_FUNCTIONS': '/step-functions',\n    'AWS_SELF_MANAGED_KAFKA': '/self-managed-kafka',\n  }\n})\n```\n\nAlternatively, to handle only SNS events (the keys in the map are **optional**)\n\n```js\nserverlessExpress({\n  app,\n  eventSourceRoutes: {\n    'AWS_SNS': '/sns',\n  }\n})\n```\n\nEvents will `POST` to the routes configured.\n\nAlso, to ensure the events propagated from an internal event and not externally, it is **highly recommended** to \nensure the `Host` header matches:\n\n\n- SNS: `sns.amazonaws.com`\n- DynamoDB: `dynamodb.amazonaws.com`\n- SQS: `sqs.amazonaws.com`\n- EventBridge: `events.amazonaws.com`\n- KinesisDataStream: `kinesis.amazonaws.com`\n\n### logSettings\n\nSpecify log settings that are passed to the default logger. Currently, you can only set the log `level`.\n\n```js\n{\n  logSettings: {\n    level: 'debug' // default: 'error'\n  }\n}\n```\n\n### log\n\nProvide a custom `log` object with `info`, `debug` and `error` methods. For example, you could override the default with a [Winston log](https://www.npmjs.com/package/winston) instance.\n\n```js\n{\n  log: {\n    info (message, additional) {\n      console.info(message, additional)\n    },\n    debug (message, additional) {\n      console.debug(message, additional)\n    },\n    error (message, additional) {\n      console.error(message, additional)\n    }\n  }\n}\n```\n\n## Accessing the event and context objects\n\nThis package exposes a function to easily get the `event` and `context` objects Lambda receives from the event source.\n\n```js\nconst { getCurrentInvoke } = require('@codegenie/serverless-express')\napp.get('/', (req, res) =\u003e {\n  const { event, context } = getCurrentInvoke()\n\n  res.json(event)\n})\n```\n\n## Why run Express in a Serverless environment\n\n- Only pay for what you use\n- No infrastructure to manage\n- Auto-scaling with zero configuration\n- [Usage Plans](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html)\n- [Caching](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html)\n- [Authorization](http://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-control-access-to-api.html)\n- [Staging](http://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-deploy-api.html)\n- [SDK Generation](http://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-generate-sdk.html)\n- [API Monitoring](http://docs.aws.amazon.com/apigateway/latest/developerguide/monitoring-cloudwatch.html)\n- [Request Validation](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-request-validation.html)\n- [Documentation](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-documenting-api.html)\n\n## Loadtesting\n\n`npx loadtest --rps 100 -k -n 1500 -c 50 https://xxxx.execute-api.us-east-1.amazonaws.com/prod/users`\n\n# AWS Serverless Express is now under the stewardship of Vendia\n\nOn 11/30, the AWS Serverless Express library moved from AWS to [Vendia](https://github.com/CodeGenieApp/serverless-express) and will be rebranded to `@codegenie/serverless-express`. Similarly, the [`aws-serverless-express` NPM package](https://www.npmjs.com/package/aws-serverless-express) will be deprecated in favor of [@codegenie/serverless-express](https://www.npmjs.com/package/@codegenie/serverless-express). \n\n[Brett Andrews](https://github.com/brettstack), the original creator of the Serverless Express library, will continue maintaining the repository and give it the attention and care it deserves. At the same time, we will be looking for additional contributors to participate in the development and stewardship of the Serverless Express library. AWS and the [SAM team](https://github.com/aws/aws-sam-cli) will remain involved in an administrative role alongside Vendia, Brett, and the new maintainers that will join the project.\n\nWe believe this is the best course of action to ensure that customers using this library get the best possible support in the future. To learn more about this move or become a maintainer of the new Serverless Express library, reach out to us through a GitHub issue on this repository. \n\nBest,\n  The AWS Serverless team, Brett \u0026 the Vendia team\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCodeGenieApp%2Fserverless-express","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCodeGenieApp%2Fserverless-express","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCodeGenieApp%2Fserverless-express/lists"}