1.3.4 • Public • Published


    Provides a simple routing interface for AWS Lambda functions using the Serverless Framework.

    Getting Started

    To get started with serverless-routing, install the package from NPM.

    $ npm install @ewarren/serverless-routing

    Next, add the following configuration to your project serverless.yaml and replace hello with the name of your function.

        handler: src/handler.router
          - http:
              path: /api
              method: any
              cors: true
          - http:
              path: /api/{proxy+}
              method: any
              cors: true

    Lastly, setup your endpoints.

    /* src/handler.js */
    const { framework, router } = require('@ewarren/serverless-routing');
    const app = framework();
    module.exports.router = router(app);
    /* src/routes/users.js */
    module.exports = (app) => {
      app.get('/user/:id', ({ success }) => {
        return success({ ok: true });
      app.put('/user/:id', ({ success }) => {
        return success({ ok: true });

    API Reference


    When constructing a new application you can pass in options to override the default router configuration.

    options.basePath: The path prefix which prepends all API routes in this service (not the API Gateway stage name). Defaults to /api.

    app.{get|put|post|delete}('/*', callback)

    Create an endpoint for the given endpoint and path. Paths can include custom parameters, eg: app.get('/user/:id', ...).


    The route handler should accept a single object argument that can be deconstructed to obtain the following properties. The route handler most return its response data.

    Route handlers can be asynchronous functions, and their execution is encapsulated in an error handler within the router in the event of failure.

    event: The original AWS API Gateway event data about the request. Read more.

    context: The original AWS Lambda context object. Read more.

    callback: The original AWS Lambda callback function.

    success(data: Object, statusCode: Number = 200, type: String = 'json'): A helper function to generate a successful http response. Defaults to an empty json object with status code 200.

    failed(error: Error, code: Number): A helper function to generate a JSON response representing an error. Any error that is an instance of HttpError will have their message dropped into the error response. Otherwise all error messages are replaced with a safe default. The default status code is 500.

    path: The full path of the endpoint that was requested.

    params: An array of strings that represent any path parameters which were matched in the route. For example, if the route was /test/:one/:two, and the following path was requested, /test/foo/bar, the params array would contain ['foo', 'bar'].

    json: If the request method is PUT or POST and contains a JSON content type header, the router will attempt to safely parse the request body. Defaults to null otherwise.


    Use this to deliver an error message to the response without leaking anything sensitive.

    const { HttpError } = require('@ewarren/serverless-routing');
    module.exports = (app) => {
      app.get('/user/:id', ({ success }) => {
        throw new HttpError('This message will be in the API response.');

    In addition to a message you can also pass in a numeric codeHint to the constructor to inform your route handler response code.

    Local Development

    To run tests locally, ensure you have Docker installed.

    $ make tests

    Publishing new versions

    (Coming soon) This repo is outfitted with Github Actions that automatically publish the package if tests pass and the version number has been bumped.




    npm i @ewarren/serverless-routing

    DownloadsWeekly Downloads






    Unpacked Size

    11.2 kB

    Total Files


    Last publish


    • itsjoekent
    • jschultz21
    • jjandoc