feat!: v5.0.0 - Node.js 24 support and removal of deprecated APIs

BREAKING CHANGES:
- Minimum Node.js version is now 24 (though earlier versions may work)
- Handler no longer accepts callback parameter - async/Promise only
- Removed resolutionMode option (CALLBACK/CONTEXT modes removed)
- Removed binaryMimeTypes option (use binarySettings instead)
- Removed deprecated createServer() and proxy() exports
- Removed deprecated handler.handler() and handler.proxy() methods

Features:
- Full support for AWS Lambda Node.js 24 runtime
- Fixed nested routes and custom domains path handling
- Configured semantic-release for v5 beta releases

Author: brettstack

.github/workflows/release-on-push-to-mainline.yml

@@ -1,7 +1,7 @@
 name: CICD
 on:
   push:
-    branches: [mainline]
+    branches: [mainline, v5]
   pull_request:
 env:
   HUSKY: 0
@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [18.x, 20.x, 22.x]
+        node-version: [22.x, 24.x]
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -27,18 +27,18 @@ jobs:
         run: npm test
 
       - name: Lint
-        if: matrix.node-version == '20.x'
+        if: matrix.node-version == '24.x'
         run: npm run lint
 
       - name: Verify Typescript Types
-        if: matrix.node-version == '20.x'
+        if: matrix.node-version == '24.x'
         run: npm run verify-typescript-types
 
       - name: Audit
-        if: matrix.node-version == '20.x'
+        if: matrix.node-version == '24.x'
         run: npm audit --audit-level critical
   release:
-    if: github.event_name == 'push' && github.ref == 'refs/heads/mainline'
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/mainline' || github.ref == 'refs/heads/v5')
     needs: test-lint-audit
     permissions:
       contents: write

UPGRADE.md

@@ -1,3 +1,60 @@
+## From 4.x to 5.x
+
+### Minimum Node.js Version
+
+v5.x officially supports Node.js 24 and later, though it will likely work for earlier versions.
+
+### Handler Changes
+
+The handler no longer accepts a `callback` parameter. It must be used with async/Promise patterns only.
+
+```javascript
+// 4.x (still works but callback-based patterns no longer supported)
+exports.handler = serverlessExpress({ app })
+
+// 5.x (same, but MUST be async/Promise-based)
+export default serverlessExpress({ app })
+```
+
+### Removed Options
+
+The following configuration options have been removed:
+
+- `resolutionMode` - Only Promise-based resolution is supported now
+- `binaryMimeTypes` - Use `binarySettings` instead
+
+```javascript
+// 4.x (deprecated)
+serverlessExpress({
+  app,
+  resolutionMode: 'CALLBACK',  // ❌ Removed
+  binaryMimeTypes: ['image/*'] // ❌ Removed
+})
+
+// 5.x
+serverlessExpress({
+  app,
+  binarySettings: {
+    contentTypes: ['image/*']
+  }
+})
+```
+
+### Removed Methods
+
+The following deprecated methods have been removed:
+
+- `serverlessExpress.createServer()` - Use `serverlessExpress({ app })` instead
+- `serverlessExpress.proxy()` - Use `serverlessExpress({ app })` instead
+- `handler.handler()` - Use `handler()` directly
+- `handler.proxy()` - Use `handler()` directly
+
+### Proxy Path Fix
+
+v5.x includes a fix for nested routes and custom domains. If you use API Gateway with a custom domain and base path mapping, routes should now work correctly.
+
+---
+
 ## From 3.x to 4.x
 
 ### Lambda Handler

__tests__/integration.js

@@ -138,60 +138,6 @@ describe.each(EACH_MATRIX)('%s:%s: integration tests', (eventSourceName, framewo
     expect(response).toMatchObject(expectedResponse)
   })
 
-  test('resolutionMode = CALLBACK', (done) => {
-    const jsonResponse = { data: { name: 'Brett' } }
-    router.get('/users', (req, res) => {
-      res.json(jsonResponse)
-    })
-    const callback = (e, response) => {
-      const expectedResponse = makeResponse({
-        eventSourceName,
-        body: JSON.stringify(jsonResponse),
-        multiValueHeaders: {
-          'content-length': ['25'],
-          etag: ['W/"19-dkLV0OMoaMM+tzXUD50EB/AHHoI"']
-        }
-      })
-      expect(response).toEqual(expectedResponse)
-      done()
-    }
-
-    const event = makeEvent({
-      eventSourceName,
-      path: '/users',
-      httpMethod: 'GET'
-    })
-    const serverlessExpressInstanceWithCallbackResolutionMode = serverlessExpress({ app, resolutionMode: 'CALLBACK' })
-    serverlessExpressInstanceWithCallbackResolutionMode(event, {}, callback)
-  })
-
-  test('resolutionMode = CONTEXT', (done) => {
-    const jsonResponse = { data: { name: 'Brett' } }
-    router.get('/users', (req, res) => {
-      res.json(jsonResponse)
-    })
-    const context = {}
-    context.succeed = (response) => {
-      const expectedResponse = makeResponse({
-        eventSourceName,
-        body: JSON.stringify(jsonResponse),
-        multiValueHeaders: {
-          'content-length': ['25'],
-          etag: ['W/"19-dkLV0OMoaMM+tzXUD50EB/AHHoI"']
-        }
-      })
-      expect(response).toEqual(expectedResponse)
-      done()
-    }
-    const event = makeEvent({
-      eventSourceName,
-      path: '/users',
-      httpMethod: 'GET'
-    })
-    const serverlessExpressInstanceWithContextResolutionMode = serverlessExpress({ app, resolutionMode: 'CONTEXT' })
-    serverlessExpressInstanceWithContextResolutionMode(event, context)
-  })
-
   test('GET missing route', async () => {
     const event = makeEvent({
       eventSourceName,
@@ -728,93 +674,4 @@ describe.each(EACH_MATRIX)('%s:%s: integration tests', (eventSourceName, framewo
       )
     })
   })
-
-  test('legacy/deprecated createServer', async () => {
-    const serverlessExpressMiddleware = require('../src/middleware')
-    app = express()
-    router = express.Router()
-    app.use('/', router)
-    router.use(serverlessExpressMiddleware.eventContext())
-    router.get('/users', (req, res) => {
-      const { event } = req.apiGateway
-      const eventPath = event.path || event.rawPath || event.Records[0].cf.request.uri
-      res.json({
-        path: eventPath
-      })
-    })
-    const event = makeEvent({
-      eventSourceName,
-      path: '/users',
-      httpMethod: 'GET'
-    })
-    const binaryMimeTypes = []
-    const server = serverlessExpress.createServer(app, null, binaryMimeTypes)
-    const response = await serverlessExpress.proxy(server, event)
-    const expectedResponse = makeResponse({
-      eventSourceName,
-      body: JSON.stringify({ path: '/users' }),
-      multiValueHeaders: {
-        'content-length': ['17'],
-        etag: ['W/"11-eM8YArY+qNwdvTL2ppeAaFc4Oq8"']
-      },
-      statusCode: 200
-    })
-    expect(response).toEqual(expectedResponse)
-  })
-
-  test('legacy/deprecated handler', async () => {
-    const serverlessExpressMiddleware = require('../src/middleware')
-    router.use(serverlessExpressMiddleware.eventContext())
-    router.get('/users', (req, res) => {
-      const { event } = req.apiGateway
-      const eventPath = event.path || event.rawPath || event.Records[0].cf.request.uri
-      res.json({
-        path: eventPath
-      })
-    })
-    const event = makeEvent({
-      eventSourceName,
-      path: '/users',
-      httpMethod: 'GET'
-    })
-    const response = await serverlessExpressInstance.handler(event)
-    const expectedResponse = makeResponse({
-      eventSourceName,
-      body: JSON.stringify({ path: '/users' }),
-      multiValueHeaders: {
-        'content-length': ['17'],
-        etag: ['W/"11-eM8YArY+qNwdvTL2ppeAaFc4Oq8"']
-      },
-      statusCode: 200
-    })
-    expect(response).toEqual(expectedResponse)
-  })
-
-  test('legacy/deprecated proxy', async () => {
-    const serverlessExpressMiddleware = require('../src/middleware')
-    router.use(serverlessExpressMiddleware.eventContext())
-    router.get('/users', (req, res) => {
-      const { event } = req.apiGateway
-      const eventPath = event.path || event.rawPath || event.Records[0].cf.request.uri
-      res.json({
-        path: eventPath
-      })
-    })
-    const event = makeEvent({
-      eventSourceName,
-      path: '/users',
-      httpMethod: 'GET'
-    })
-    const response = await serverlessExpressInstance.proxy({ event })
-    const expectedResponse = makeResponse({
-      eventSourceName,
-      body: JSON.stringify({ path: '/users' }),
-      multiValueHeaders: {
-        'content-length': ['17'],
-        etag: ['W/"11-eM8YArY+qNwdvTL2ppeAaFc4Oq8"']
-      },
-      statusCode: 200
-    })
-    expect(response).toEqual(expectedResponse)
-  })
 })

__tests__/unit.js

@@ -289,7 +289,7 @@ describe.skip('forwardResponse: content-type encoding', () => {
       }
     ).then(successResponse => expect(successResponse).toEqual({
       statusCode: 200,
-      body: body,
+      body,
       multiValueHeaders,
       isBase64Encoded: false
     }))
@@ -345,44 +345,14 @@ describe.skip('forwardResponse: content-type encoding', () => {
 })
 
 describe('makeResolver', () => {
-  test('CONTEXT (specified)', () => {
-    return new Promise(
-      (resolve, reject) => {
-        const context = new MockContext(resolve, reject)
-        const contextResolver = makeResolver({
-          context,
-          resolutionMode: 'CONTEXT'
-        })
-
-        return contextResolver.succeed({
-          response: 'success'
-        })
-      }).then(successResponse => expect(successResponse).toEqual('success'))
-  })
-
-  test('CALLBACK', () => {
-    const callback = (e, response) => response
-    const callbackResolver = makeResolver({
-      callback,
-      resolutionMode: 'CALLBACK',
-      context: {}
-    })
-    const successResponse = callbackResolver.succeed({
-      response: 'success'
-    })
-
-    expect(successResponse).toEqual('success')
-  })
-
-  test('PROMISE', () => {
+  test('succeed resolves promise', () => {
     return new Promise((resolve, reject) => {
       const promise = {
         resolve,
         reject
       }
       const promiseResolver = makeResolver({
-        promise,
-        resolutionMode: 'PROMISE'
+        promise
       })
 
       return promiseResolver.succeed({
@@ -392,4 +362,22 @@ describe('makeResolver', () => {
       expect(successResponse).toEqual('success')
     })
   })
+
+  test('fail rejects promise', () => {
+    return new Promise((resolve, reject) => {
+      const promise = {
+        resolve: reject,
+        reject: resolve
+      }
+      const promiseResolver = makeResolver({
+        promise
+      })
+
+      return promiseResolver.fail({
+        error: new Error('test error')
+      })
+    }).then(error => {
+      expect(error.message).toEqual('test error')
+    })
+  })
 })

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codegenie/serverless-express",
-  "version": "4.17.1",
+  "version": "5.0.0",
   "description": "This library enables you to utilize AWS Lambda and Amazon API Gateway to respond to web and API requests using your existing Node.js application framework.",
   "keywords": [
     "aws",
@@ -28,7 +28,7 @@
     "url": "https://github.com/CodeGenieApp/serverless-express.git"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=24"
   },
   "publishConfig": {
     "access": "public"
@@ -99,4 +99,4 @@
       "path": "./node_modules/@ryansonshine/cz-conventional-changelog"
     }
   }
-}
+}

release.config.js

@@ -1,6 +1,7 @@
 module.exports = {
   branches: [
-    'mainline'
+    'mainline',
+    { name: 'v5', prerelease: 'beta' }
   ],
   plugins: [
     [