serverless-offline

What is serverless-offline?

The serverless-offline npm package allows you to run a local development environment that simulates AWS Lambda and API Gateway. This enables you to develop and test your serverless applications locally without deploying them to the cloud.

What are serverless-offline's main functionalities?

Simulate AWS Lambda

This feature allows you to simulate AWS Lambda functions locally. The code sample shows how to configure the serverless-offline plugin in your serverless.yml file to run on port 3000.

const serverless = require('serverless-offline');

module.exports = {
  plugins: [serverless],
  custom: {
    'serverless-offline': {
      port: 3000
    }
  }
};

Simulate API Gateway

This feature allows you to simulate API Gateway endpoints locally. The code sample shows how to define a simple HTTP GET endpoint that triggers the 'hello' function.

const serverless = require('serverless-offline');

module.exports = {
  plugins: [serverless],
  functions: {
    hello: {
      handler: 'handler.hello',
      events: [
        {
          http: {
            path: 'hello',
            method: 'get'
          }
        }
      ]
    }
  }
};

Custom Lambda Environment Variables

This feature allows you to set custom environment variables for your Lambda functions. The code sample shows how to define an environment variable 'MY_ENV_VAR' with a value of 'value'.

const serverless = require('serverless-offline');

module.exports = {
  plugins: [serverless],
  provider: {
    environment: {
      MY_ENV_VAR: 'value'
    }
  }
};

Other packages similar to serverless-offline

localstack

LocalStack provides a fully functional local AWS cloud stack. It allows you to run AWS services like Lambda, S3, DynamoDB, and more on your local machine. Compared to serverless-offline, LocalStack offers a broader range of AWS services but can be more complex to set up.

README

Serverless Offline Plugin

When developing with Serverless deploying functions to AWS after each change might be annoying. This plugin allows you to simulate API Gateway locally, so all function calls can be done on localhost.

Differences with Serverless-serve-plugin

See Credits and inspiration.

TLDR: Better error handling, the event object passed to your λ is Hapijs's request object, open-source licence.

Installation

Requires Node v4 and over and Serverless v0.4.x. In your Serverless project:

npm install serverless-offline

Then in s-project.json add following entry to the plugins array: serverless-offline

Like this:

  "plugins": ["serverless-offline"]

And in your project root do:

sls offline start

Command line options

--prefix -p: Add prefix to the URLs, so your clients will not use http://localhost:3000/ but http://localhost:3000/prefix/ instead. Default: empty

--port -P: Port to listen on. Default: 3000

Usage

Just send your requests to http://localhost:3000/ as it would be API Gateway.

Using this plugin with Nodemon or a similar tool is advised to reload your local code after every change.

Usage with Babel

Optionaly, your handlers can be required with babel-register. To do so, in your s-project.json file, set options to be passed to babel-register like this:

{
  /* ... */
  "custom": {
    "serverless-offline": {
      "babelOptions": {
        /* Your own options, example: */
        "presets": ["es2015", "stage-2"]
      }
    }
  },
  "plugins": ["serverless-offline", /* ... */]
}

Here is the full list of babel-register options

Simulation quality

This plugin simulates API Gateway for many practical purposes, good enough for development - but is not a perfect simulator. Specifically, Lambda currently runs on Node v0.10.13, whereas Offline runs on your own runtime where no timeout or memory limits are enforced. Mapping templates are not simulated, so are security checks. You will probably find other differences.

Credits and inspiration

This plugin is a fork of Nopik's Serverless-serve, the differences are:

• Under the hood, Serve uses Express, Offline uses Hapi.
• Offline puts a stronger focus on error handling by displaying stack traces.
• Serve's event object (passed to your handlers) is undocumented and often empty. Offline's event object is defined by: Object.assign({ isServerlessOffline: true }, request); where request is Hapi's request object. This allows you to quickly access properties like the request's params or payload in your lambda handler:

module.exports.handler = function(event, context) {
  var params;
  
  if (event.isServerlessOffline) { // Locally
    /* Hapijs request object */
    params = event.params;
  } else { // On AWS Lambda
    /* Define your event object using a template in your s-function.json file */
    params = event.customKeyDefinedInTemplate;
  }
};

• Offline dropped support for Serve's optional init script for now.
• Offline displays your routes on start.
• Offline has an open-source license.

Roadmap

Once Serverless 0.6 is out, support for velocity templates to define the event object and modify your functions' output.

Contributing

PRs are welcome :)

Licence

MIT