@codegenie/serverless-express: run Express on AWS Lambda without rewriting routes

The problem: an Express app that has to become a Lambda function

Express expects a long-running process with a socket. Lambda gives you an event object and a context, and the process may freeze between invocations. Rewriting every route as a separate handler, or rebuilding the app on a framework designed for Lambda, is the usual cost of moving. This library removes that cost by keeping the framework and translating at the boundary. The README states the goal plainly: run REST APIs and other web applications using your existing Node.js application framework, on top of AWS Lambda and Amazon API Gateway or Azure Function. Express is the headline case, but the same wrapper is documented for Koa, Hapi and Sails, and the examples directory carries starters for hapi, koa, nestjs, sails and vanilla-http. The audience is a team with an Express codebase already in production that wants serverless deployment without a second implementation of its routing, middleware and error handling.

How the adapter works: mock request and response objects, no socket

The mechanism is worth understanding before adopting it, because it explains most of the behaviour you will observe. The implementation uses mock Request and Response objects instead of running a server listening on a local socket, a design the README credits to @dougmoscrop from dougmoscrop/serverless-http. In practice this means the library constructs objects that satisfy the Node HTTP interfaces Express relies on, feeds the incoming event into them, lets your app handle the request normally, then reads the response back out and converts it into the shape the event source expects. Because there is no socket, there is nothing to bind, nothing to keep alive between invocations, and no port to configure. The same design makes binary handling possible: the README says isBase64Encoded is determined automatically without specifying binaryMimeTypes, with binarySettings available to customize the decision, and it notes this is necessary because API Gateway and other event sources cannot handle binary responses directly. Supported event sources listed for the 4.x line are API Gateway V1 (REST API), API Gateway V2 (HTTP API), ALB, Lambda@Edge and VPC Lattice, plus a custom event source path for anything else, demonstrated by the DynamoDB example.

Installing @codegenie/serverless-express and a first Lambda handler

The package is published on npm under the scoped name. The README gives this install command, and package.json sets main to src/index.js with files limited to src/, so the published artifact is the adapter source only.

npm install @codegenie/serverless-express

The only AWS Lambda specific code you need to write is a handler. The README's minimal example requires the package and wraps an existing app module, which is the whole integration surface.

// lambda.js
const serverlessExpress = require('@codegenie/serverless-express')
const app = require('./app')
exports.handler = serverlessExpress({ app })

If your app needs bootstrap work such as a database connection before the first request is forwarded, the README documents an async setup pattern that caches the wrapped instance. On the first invocation it awaits the setup work, creates the instance, and forwards the event; later invocations reuse the cached instance. After deploying, the reader should see the same responses the Express app produced locally, with the framework's own routing and middleware intact. For a complete deployable project the README points to examples/basic-starter-api-gateway-v1, which includes the Lambda function, the Express application, a SAM/CloudFormation template and helper scripts to configure, deploy and manage the application.

The Node.js 24 floor and the v5.0.0 upgrade

The most concrete constraint is the runtime. package.json declares engines node >=24, and the README's v5.0.0 notice lists Node.js 24 support and the removal of deprecated APIs as the two headline changes. If your Lambda functions run on an older runtime, v5 is not an option until you move them, and that move is a separate piece of work from the library upgrade. The upgrade path itself is documented rather than implicit: the README links UPGRADE.md with a from-4x-to-5x anchor. Because v5.0.0 removed deprecated APIs, an application that relied on those APIs will fail after the version bump rather than degrade quietly, which is the better failure mode but still requires reading the upgrade guide before changing the dependency. The release history shows the transition was staged: v5.0.0-beta.1 in December 2025, v5.0.0-beta.2 in April 2026, then v5.0.0 on 2026-04-16. Treat the engine requirement as a scheduling constraint for your Lambda runtime upgrade, not as a detail to discover at deploy time.

Where serverless-express is the wrong tool

This is an adapter, not a framework, and the README does not present it as one. Two cases argue against it. First, if you are starting a new Lambda service and have no existing Express code, the wrapper adds a translation layer and a framework you did not need; the event object is already a clean interface, and the README's own examples for DynamoDB streams and custom mappers show how much of this library exists to serve applications that already assume HTTP. Second, the binary handling exists because event sources cannot pass binary responses directly, and the library compensates by base64 encoding with automatic detection plus binarySettings to customize. That is a workaround for a real constraint, and workloads dominated by large binary payloads are a poor fit for the API Gateway path regardless of which adapter you choose. The README also does not document rollback, so a failed v5 upgrade has no described reversal procedure beyond what your own version control and deployment tooling provide. Neither point makes the library bad; both define its boundary.

serverless-express compared with serverless-http

The README is unusually direct about lineage: the 4.x implementation using mock Request/Response objects instead of a local socket, and the automatic isBase64Encoded behaviour, are both credited to @dougmoscrop from dougmoscrop/serverless-http. That makes serverless-http the natural alternative, and the difference is mostly about scope rather than mechanism. Both sit between a Node framework and a serverless event source. This project goes further in event coverage: the README lists API Gateway V1, API Gateway V2, ALB, Lambda@Edge and VPC Lattice, and documents a custom event source path with a DynamoDB example for sources it does not support natively. It also ships a larger set of runnable starters, including Azure Function v3 and v4 handlers, Lambda@Edge, Lambda function URLs and a TypeScript API Gateway v2 starter. If your target is a single event source and you want the smallest possible adapter, the shared design means the choice is close to a coin flip. If you need Lambda@Edge, VPC Lattice or a custom mapper, the documented coverage here is the deciding factor.

Licence, maintenance and what an upgrade costs

The project is Apache-2.0, stated in package.json and in the LICENSE file at the repository root, and the README carries the matching badge. Apache-2.0 is a permissive licence with an explicit patent grant; it permits commercial and closed-source use, but it also carries notice and attribution obligations, and the file ships a NOTICE-style attribution surface through the licence text itself. Read LICENSE and CODE_OF_CONDUCT.md rather than treating the identifier as a summary, and get legal review for your own distribution model. On maintenance, the last push to the repository was on 2026-04-16 and the newest release, v5.0.0, carries the same date. That is a single coordinated event, not a rolling cadence, so plan upgrades around releases rather than expecting continuous churn. The upgrade cost is bounded but real: a Node.js 24 runtime move for every affected function, a read of UPGRADE.md for the 4.x to 5.x steps, and a check that any deprecated API your app touched is gone. The repository root also carries .agents/ and .claude/ directories and a skills-lock.json, which suggest agent tooling in the development workflow; the README does not describe their role, so treat them as internal.

Editorial conclusion

Adopt @codegenie/serverless-express if you already have an Express, Koa or Hapi application and want it answering API Gateway, ALB or Lambda@Edge events with a handler wrapper rather than a route rewrite. Skip it if you are starting fresh on Lambda and have no existing framework code, or if your runtime is below Node.js 24, because package.json declares engines node >=24 and v5.0.0 removed deprecated APIs. Before you commit, read UPGRADE.md for the 4.x to 5.x steps and confirm your event source appears in the supported list, since the library only maps the sources it documents.

Frequently asked questions

Official sources

1. CodeGenieApp/serverless-express on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases