{"id":15663759,"url":"https://github.com/matthewkeil/convert-lambda-to-express","last_synced_at":"2025-08-19T08:32:26.033Z","repository":{"id":46245757,"uuid":"422568082","full_name":"matthewkeil/convert-lambda-to-express","owner":"matthewkeil","description":"Wrapper to run lambda on express.  Works great for running lambdas as an express server during development but is production ready. Developed to work in conjunction with matthewkeil/full-stack-pattern cdk construct.  ","archived":false,"fork":false,"pushed_at":"2024-06-19T14:41:41.000Z","size":2140,"stargazers_count":17,"open_issues_count":2,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-09T14:50:26.504Z","etag":null,"topics":["aws","aws-lambda","converter","developer-tools","development","express","prevent-lock-in","production-ready"],"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/matthewkeil.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":"2021-10-29T12:31:43.000Z","updated_at":"2024-07-25T18:12:41.000Z","dependencies_parsed_at":"2024-10-23T08:40:37.252Z","dependency_job_id":"af402246-be74-47cc-857e-1d3e612f11d0","html_url":"https://github.com/matthewkeil/convert-lambda-to-express","commit_stats":{"total_commits":296,"total_committers":37,"mean_commits":8.0,"dds":0.6689189189189189,"last_synced_commit":"b9564d69cdd8a21d506263dd689c1c48d89d4a69"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewkeil%2Fconvert-lambda-to-express","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewkeil%2Fconvert-lambda-to-express/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewkeil%2Fconvert-lambda-to-express/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewkeil%2Fconvert-lambda-to-express/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matthewkeil","download_url":"https://codeload.github.com/matthewkeil/convert-lambda-to-express/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230340130,"owners_count":18211162,"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","aws-lambda","converter","developer-tools","development","express","prevent-lock-in","production-ready"],"created_at":"2024-10-03T13:39:46.210Z","updated_at":"2024-12-18T21:08:37.306Z","avatar_url":"https://github.com/matthewkeil.png","language":"TypeScript","funding_links":["https://www.paypal.com/donate?hosted_button_id=HCF76TA62TXJW"],"categories":[],"sub_categories":[],"readme":"# convert-lambda-to-express\n\nProduction-ready package to run your lambda workloads as an express server. Built with both developers and enterprise in mind.\n\n`convert-lambda-to-express` provides fully features `event` and `context` objects to your handlers and there should be no need to modify your existing code. If you rely on the `ENVIRONMENT` variables that lambda provides, those are accounted for as well.\n\nRunning apiGateway/lambda locally during development can be a challenge (to say the least). The other options out there are either too slow or too complicated. This package aims to solve this problem by providing a simple way to run your api locally. It allows you to wrap your handlers and serve them from an express server.\n\nMakes development of lambda api's a breeze. This package was developed because the other options available for running lambdas, like [sam local](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-local-start-api.html), [serverless-offline](https://github.com/dherault/serverless-offline) or [docker-lambda](https://github.com/lambci/docker-lambda), require docker containers. They are all VERY slow hot-reloading or do not provide that feature at all (how does one dev without hot reload these days?!?!).\n\nThere are even some great use cases for migrating workloads away from Lambda and this is the project for you.\n\nHate your, now baked-in, vendor lock and the non-portable lambda function signature? Have you found that concurrency limits for very choppy traffic and extremely high workloads hard to reserve concurrency for? Just want to use an auto-scaling group or kubernetes cluster now that you've grown? Do you have long running, but very low resource tasks that end up costing an arm and leg on Lambda. Depending on your specifics it can end up being much more effective/cost-efficient to run you system on EC2 or a kubernetes cluster. Rest assured this is a production-ready package that is built for a bulletproof base with express.\n\nIf you love this package and want to [thank me](https://www.paypal.com/donate?hosted_button_id=HCF76TA62TXJW), or contract with me, you can find me at [Matthew Keil](https://www.linkedin.com/in/matthew-keil/). I specialize in Crypto/Solidity, DevOps and Security(SecOps) development. Open-source for the win!\n\n## Install\n\n```bash\nnpm install -S convert-lambda-to-express\n```\n\n## Basic usage\n\n```typescript\nimport { wrapLambda } from 'convert-lambda-to-express';\nimport express from 'express';\nimport { handler } from './someLambdaHandler';\n\nconst app = express();\n\napp.get('/', wrapLambda(handler));\n\napp.listen(3000, () =\u003e {\n  console.log('Listening on port 3000');\n});\n```\n\n## Advanced usage\n\n```typescript\nimport express from 'express';\nimport { wrapLambda, WrapperOptions } from 'convert-lambda-to-express';\nimport { handler } from './someLambdaHandler';\n\nconst app = express();\n\nconst options: WrapperOptions = {\n  functionName: 'my-function',\n  resourcePath: '/api/v1/my-function',\n  profile: 'my-aws-credentials-profile', // from ~/.aws/credentials\n  region: 'us-east-1', // sets AWS_REGION for sdk calls in handler\n  timeoutInSeconds: 10, // sets actual timeout for handler\n  finalize: () =\u003e {\n    // do some cleanup here after function runs but before\n    // response is sent to client\n  }\n};\n\napp.get(config.resourcePath, wrapLambda(handler, options));\n\napp.listen(3000, () =\u003e {\n  console.log('Listening on port 3000');\n});\n```\n\n## Hot-Reloading DevServer (useful with cdk)\n\nYou can import the `addToDevServer` into your cdk constructs and add the handlers during run time.  This was the designed use case.  See [`matthewkeil/full-stack-pattern`](https://github.com/matthewkeil/full-stack-pattern) for an example. Also works well with sam templates or any other method for programmatically building the handlers array in the example below.  In the cdk instance, instead of calling app.synth() call startDevServer() and it will give you a hot reloading api.   \n\n```typescript\nimport { addToDevServer, startDevServer, HandlerConfig } from 'convert-lambda-to-express';\nimport { middlewareHandler } from './someCorporateMiddleware';\n\n// HandlerConfig extends WrapperOptions\nconst handlers: HandlerConfig[] = [\n  {\n    profile: 'my-aws-credentials-profile', // from ~/.aws/credentials\n    region: 'us-east-1', // sets AWS_REGION for sdk calls in handler\n    method: 'GET',\n    path: '/path/{param1}/{param2}',\n    handler: 'doSomethingFancy/index.handler',\n    codeDirectory: './path/to/code/directory', // where `doSomething` fancy folder is located\n    environment: {\n      ENV_VAR: 'value'\n    }\n  }\n];\n\nfor (const handler of handlers) {\n  addToDevServer(handler);\n}\n\nconst port = 3002;\n\nstartDevServer({\n  port,\n  prod: true,\n  hotReload: true, // will watch all `handler.codeDirectory` paths for changes and restart server\n  corsOptions: {\n    // cors package options\n    origin: `http://localhost:${port}`,\n    methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',\n    preflightContinue: false,\n    optionsSuccessStatus: 204\n  },\n  helmetOptions: {\n    // helmet package options, pick better options than this example please...\n    noSniff: true,\n    xssFilter: true\n  }\n});\n```\n\n## WrapperOptions, HandlerConfig and DevServerConfig\n\nConfigure your lambdas and devServer with these `options` objects:\n\n```typescript\nexport interface WrapperOptions {\n  handler?: string;\n  functionName?: string;\n  functionVersion?: string;\n  memorySize?: number;\n  logGroupName?: string;\n  logStreamName?: string;\n  timeoutInSeconds?: number;\n  identity?: CognitoIdentity;\n  clientContext?: ClientContext;\n  nodeModulesPath?: string;\n  resourcePath?: string;\n  stage?: string;\n  isBase64Encoded?: boolean;\n  finalize?: () =\u003e void;\n  accountId?: string;\n  region?: string;\n  profile?: string;\n  credentialsFilename?: string;\n  logger?: Logger; // winston logger\n  defaultResponseHeaders?: { [header: string]: string | number | boolean };\n}\n\nexport interface HandlerConfig extends WrapperOptions {\n  method: HttpMethod;\n  resourcePath: string;\n  handler: string;\n  codeDirectory?: string;\n  environment?: HandlerEnvironment;\n}\n\nexport interface DevServerConfig {\n  port?: number;\n  hotReload?: boolean;\n  prod?: boolean;\n  morganSetting?: MorganOption;\n  corsOptions?: CorsOptions;\n  helmetOptions?: Parameters\u003ctypeof helmet\u003e[0];\n  middleware?: Handler[];\n  verbose?: boolean;\n  codeDirectory?: string;\n}\n```\n\n| Key name | Description |\n| --- | --- |\n| `method` | HTTP method to use for the handler|\n| `resourcePath`|defaults to `/{proxy+}` Placed in ENVIRONMENT, `event` and `context`|\n| `handler`|`filename.exportName` format. Placed in ENVIRONMENT|\n| `codeDirectory`|used to import handler and for watching code changes|\n| `environment`|environment variables|\n| `functionName`|optional, defaults to `convert-lambda-to-express`. Placed in ENVIRONMENT, `event` and `context`|\n| `functionVersion`|optional, defaults to `$LATEST`. Placed in ENVIRONMENT|\n| `timeoutInSeconds`|optional, default to `3`. watchdog timer that mimics lambda's timeout|\n| `identity`|optional, CognitoIdentity object, see [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/7b62f878cc218c8e94e6efafa55cea6796b501f7/types/aws-lambda/handler.d.ts#L124). Passed in `context`|\n| `clientContext`|optional, ClientContext object, see [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/7b62f878cc218c8e94e6efafa55cea6796b501f7/types/aws-lambda/handler.d.ts#L129). Passed in `context`|\n| `nodeModulesPath`|optional, path to local node_modules folder. Placed in ENVIRONMENT|\n| `stage`|optional, defaults to `dev`. Passed in `event`|\n| `isBase64Encoded`|optional, default to `false`. Passed in to handler `event`|\n| `finalize`|optional, clean-up function that is called at the end of each request|\n| `accountId`|optional, aws account id. Placed in ENVIRONMENT|\n| `region`|optional, AWS region, default to `us-east-1`. adds AWS_REGION to ENVIRONMENT|\n| `profile`|optional, defaults to `default`. profile from `~/.aws/credential` to use. Adds tokens to AWS_TOKEN, AWS_SECRET_TOKEN, AWS_SESSION_TOKEN|\n| `credentialsFilename`|optional, defaults to `~/.aws/credential`|\n| `logger`|optional, winston Logger object. will default to the console object if not present|\n| `defaultResponseHeaders`|optional, headers that should be applied to all responses|\n\n\n## License\n\nThis library is released under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthewkeil%2Fconvert-lambda-to-express","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatthewkeil%2Fconvert-lambda-to-express","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthewkeil%2Fconvert-lambda-to-express/lists"}