{"id":14969161,"url":"https://github.com/fastify/aws-lambda-fastify","last_synced_at":"2025-05-14T07:08:12.611Z","repository":{"id":35014604,"uuid":"196577565","full_name":"fastify/aws-lambda-fastify","owner":"fastify","description":"Insipired by aws-serverless-express to work with Fastify with inject functionality","archived":false,"fork":false,"pushed_at":"2025-05-01T03:31:28.000Z","size":322,"stargazers_count":534,"open_issues_count":7,"forks_count":36,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-01T04:28:05.778Z","etag":null,"topics":["amazon","api","api-gateway","aws","cloud","fastify","fastify-library","javascript","lambda","node","nodejs","proxy","serverless","web"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/@fastify/aws-lambda","language":"JavaScript","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/fastify.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,"zenodo":null},"funding":{"github":"fastify","open_collective":"fastify"}},"created_at":"2019-07-12T12:42:50.000Z","updated_at":"2025-05-01T03:31:24.000Z","dependencies_parsed_at":"2023-02-16T03:16:01.090Z","dependency_job_id":"f582b0c3-deda-43c0-87bf-e6899d6cac49","html_url":"https://github.com/fastify/aws-lambda-fastify","commit_stats":{"total_commits":298,"total_committers":20,"mean_commits":14.9,"dds":0.5469798657718121,"last_synced_commit":"104fd8595204685c95d409c14dc88731f8661153"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Faws-lambda-fastify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Faws-lambda-fastify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Faws-lambda-fastify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Faws-lambda-fastify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastify","download_url":"https://codeload.github.com/fastify/aws-lambda-fastify/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254092656,"owners_count":22013290,"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":["amazon","api","api-gateway","aws","cloud","fastify","fastify-library","javascript","lambda","node","nodejs","proxy","serverless","web"],"created_at":"2024-09-24T13:41:15.242Z","updated_at":"2025-05-14T07:08:12.591Z","avatar_url":"https://github.com/fastify.png","language":"JavaScript","readme":"# Introduction\n\n[![CI](https://github.com/fastify/aws-lambda-fastify/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/aws-lambda-fastify/actions/workflows/ci.yml)\n[![NPM version](https://img.shields.io/npm/v/@fastify/aws-lambda.svg?style=flat)](https://www.npmjs.com/package/@fastify/aws-lambda)\n[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)\n\nInspired by the AWSLABS [aws-serverless-express](https://github.com/awslabs/aws-serverless-express) library tailor made for the [Fastify](https://fastify.dev/) web framework.\n\n**No use of internal sockets, makes use of Fastify's [inject](https://fastify.dev/docs/latest/Guides/Testing/#testing-with-http-injection) function.**\n\n**Seems [faster](https://github.com/fastify/aws-lambda-fastify#%EF%B8%8Fsome-basic-performance-metrics)** *(as the name implies)* **than [aws-serverless-express](https://github.com/awslabs/aws-serverless-express) and [aws-serverless-fastify](https://github.com/benMain/aws-serverless-fastify) 😉**\n\n## 👨🏻‍💻Installation\n\n```bash\n$ npm i @fastify/aws-lambda\n```\n\n## Options\n\n**@fastify/aws-lambda** can take options by passing them with : `awsLambdaFastify(app, options)`\n\n| property                       | description                                                                                                                                | default value                      |\n| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- |\n| binaryMimeTypes                | Array of binary MimeTypes to handle                                                                                                        | `[]`                               |\n| enforceBase64                  | Function that receives the response and returns a boolean indicating if the response content is binary or not and should be base64-encoded | `undefined`                        |\n| serializeLambdaArguments       | Activate the serialization of lambda Event and Context in http header `x-apigateway-event` `x-apigateway-context`                          | `false` *(was `true` for \u003cv2.0.0)* |\n| decorateRequest                | Decorates the fastify request with the lambda Event and Context `request.awsLambda.event` `request.awsLambda.context`                      | `true`                             |\n| decorationPropertyName         | The default property name for request decoration                                                                                           | `awsLambda`                        |\n| callbackWaitsForEmptyEventLoop | See: [Official Documentation](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-context.html#nodejs-prog-model-context-properties)       | `undefined`                        |\n| retainStage                    | Retain the stage part of the API Gateway URL                                                                                               | `false`                            |\n| pathParameterUsedAsPath        | Use a defined pathParameter as path (i.e. `'proxy'`)                                                                                               | `false`                            |\n| parseCommaSeparatedQueryParams        | Parse querystring with commas into an array of values. Affects the behavior of the querystring parser with commas while using [Payload Format Version 2.0](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html#http-api-develop-integrations-lambda.proxy-format)                                                                                               | `true`                            |\n| payloadAsStream        |  If set to true the response is a stream and can be used with `awslambda.streamifyResponse`                                                                                                | `false`                            |\n## 📖Example\n\n### lambda.js\n\n```js\nconst awsLambdaFastify = require('@fastify/aws-lambda')\nconst app = require('./app')\n\nconst proxy = awsLambdaFastify(app)\n// or\n// const proxy = awsLambdaFastify(app, { binaryMimeTypes: ['application/octet-stream'], serializeLambdaArguments: false /* default is true */ })\n\nexports.handler = proxy\n// or\n// exports.handler = (event, context, callback) =\u003e proxy(event, context, callback)\n// or\n// exports.handler = (event, context) =\u003e proxy(event, context)\n// or\n// exports.handler = async (event, context) =\u003e proxy(event, context)\n```\n\n### app.js\n\n```js\nconst fastify = require('fastify')\n\nconst app = fastify()\napp.get('/', (request, reply) =\u003e reply.send({ hello: 'world' }))\n\nif (require.main === module) {\n  // called directly i.e. \"node app\"\n  app.listen({ port: 3000 }, (err) =\u003e {\n    if (err) console.error(err)\n    console.log('server listening on 3000')\n  })\n} else {\n  // required as a module =\u003e executed on aws lambda\n  module.exports = app\n}\n```\n\nWhen executed in your lambda function we don't need to listen to a specific port,\nso we just export the `app` in this case.\nThe [`lambda.js`](https://github.com/fastify/aws-lambda-fastify#lambdajs) file will use this export.\n\nWhen you execute your Fastify application like always,\ni.e. `node app.js` *(the detection for this could be `require.main === module`)*,\nyou can normally listen to your port, so you can still run your Fastify function locally.\n\n### 📣Hint\n\n#### Lambda arguments\n\nThe original lambda event and context are passed via Fastify request and can be used like this:\n\n```js\napp.get('/', (request, reply) =\u003e {\n  const event = request.awsLambda.event\n  const context = request.awsLambda.context\n  // ...\n})\n```\n*If you do not like it, you can disable this by setting the `decorateRequest` option to `false`.*\n\n\nAlternatively the original lambda event and context are passed via headers and can be used like this, if setting the `serializeLambdaArguments` option to `true`:\n\n```js\napp.get('/', (request, reply) =\u003e {\n  const event = JSON.parse(decodeURIComponent(request.headers['x-apigateway-event']))\n  const context = JSON.parse(decodeURIComponent(request.headers['x-apigateway-context']))\n  // ...\n})\n```\n\n#### Lower cold start latency\n\nSince [AWS Lambda now enables the use of ECMAScript (ES) modules](https://aws.amazon.com/blogs/compute/using-node-js-es-modules-and-top-level-await-in-aws-lambda/) in Node.js 14 runtimes, you could lower the cold start latency when used with [Provisioned Concurrency](https://aws.amazon.com/blogs/compute/new-for-aws-lambda-predictable-start-up-times-with-provisioned-concurrency/) thanks to the top-level await functionality.\n\nWe can use this by calling the [`fastify.ready()`](https://fastify.dev/docs/latest/Reference/Server/#ready) function outside of the Lambda handler function, like this:\n\n```js\nimport awsLambdaFastify from '@fastify/aws-lambda'\nimport app from './app.js'\nexport const handler = awsLambdaFastify(app)\nawait app.ready() // needs to be placed after awsLambdaFastify call because of the decoration: https://github.com/fastify/aws-lambda-fastify/blob/main/index.js#L9\n```\n\n*[Here](https://github.com/fastify/aws-lambda-fastify/issues/89) you can find the approriate issue discussing this feature.*\n\n\n#### Support for response streaming (`payloadAsStream`)\n\n```js\nimport awsLambdaFastify from '@fastify/aws-lambda'\nimport { promisify } from 'node:util'\nimport stream from 'node:stream'\nimport app from './app.js'\n\nconst pipeline = promisify(stream.pipeline)\nconst proxy = awsLambdaFastify(app, { payloadAsStream: true })\nexport const handler = awslambda.streamifyResponse(async (event, responseStream, context) =\u003e {\n  const { meta, stream } = await proxy(event, context)\n  responseStream = awslambda.HttpResponseStream.from(responseStream, meta)\n  await pipeline(stream, responseStream)\n})\nawait app.ready() // https://github.com/fastify/aws-lambda-fastify/issues/89\n```\n\n*[Here](https://github.com/fastify/aws-lambda-fastify/issues/154) you can find the approriate issue discussing this feature.*\n\n\n## ⚡️Some basic performance metrics\n\n**@fastify/aws-lambda (decorateRequest : false)** x **56,892 ops/sec** ±3.73% (79 runs sampled)\n\n**@fastify/aws-lambda** x **56,571 ops/sec** ±3.52% (82 runs sampled)\n\n**@fastify/aws-lambda (serializeLambdaArguments : true)** x **56,499 ops/sec** ±3.56% (76 runs sampled)\n\n**[serverless-http](https://github.com/dougmoscrop/serverless-http)** x **45,867 ops/sec** ±4.42% (83 runs sampled)\n\n**[aws-serverless-fastify](https://github.com/benMain/aws-serverless-fastify)** x **17,937 ops/sec** ±1.83% (86 runs sampled)\n\n**[aws-serverless-express](https://github.com/awslabs/aws-serverless-express)** x **16,647 ops/sec** ±2.88% (87 runs sampled)\n\nFastest is **@fastify/aws-lambda (decorateRequest : false), @fastify/aws-lambda**\n\n#### ⚠️Considerations\n\n - For apps that may not see traffic for several minutes at a time, you could see [cold starts](https://aws.amazon.com/blogs/compute/container-reuse-in-lambda/)\n - Stateless only\n - API Gateway has a timeout of 29 seconds, and Lambda has a maximum execution time of 15 minutes. (Using Application Load Balancer has no timeout limit, so the lambda maximum execution time is relevant)\n - If you are using another web framework beside Fastify (i.e. Connect, Express, Koa, Restana, Sails, Hapi, Restify) or want to use a more generic serverless proxy framework, have a look at: [serverless-http](https://github.com/dougmoscrop/serverless-http) or [serverless-adapter](https://github.com/H4ad/serverless-adapter)\n\n\n#### 🎖Who is using it?\n\n\u003ca href=\"https://locize.com\" target=\"_blank\" rel=\"nofollow\"\u003e\n  \u003cimg style=\"max-height: 80px;\" src=\"https://raw.githubusercontent.com/fastify/aws-lambda-fastify/main/images/logos/locize.png\" alt=\"locize is using @fastify/aws-lambda\"/\u003e\n\u003c/a\u003e\n\n---\n\u003csmall\u003eThe logos displayed in this page are property of the respective organisations and they are\nnot distributed under the same license as @fastify/aws-lambda (MIT).\u003c/small\u003e\n","funding_links":["https://github.com/sponsors/fastify","https://opencollective.com/fastify"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Faws-lambda-fastify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastify%2Faws-lambda-fastify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Faws-lambda-fastify/lists"}