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

This Serverless plugin emulates AWS API Gateway and Lambda locally to speed up your development cycles.

Features

• Call your λs on localhost the same way you would call API Gateway.
• requestTemplates and responseTemplates velocity support.
• Timeouts according to your s-function.json files (the plugin responds 503).
• Overkill error handling: reproduces API Gateway's errors, displays stack traces on terminal.
• Lazy loading of your λs: modify them, don't restart the plugin, enjoy your changes (the require cache is invalidated on each λ invocation, no need for a reloading tool like Nodemon).

Beta version

This is still a bit unstable, please submit any issue you may have, thanks you. A stable version (without velocity support) can be found on the 0.2 branch.

Installation

Requires Serverless v0.4.x. In your Serverless project root:

npm install serverless-offline@beta-3

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

Like this:

  "plugins": ["serverless-offline"]

And in your project root run:

sls offline start

Command line options

All CLI options are optionnal.

--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

--stage -s: The stage used to populate your velocity templates. Default: the first stage found in your project.

--region -r: The region used to populate your velocity templates. Default: the first region for the first stage found in your project.

--skipRequireCacheInvalidation -c: Tells the plugin to skip require cache invalidation. A script reloading tool like Nodemon might then be needed. Default: false.

Usage

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

Usage with Babel

Optionaly, your λ handlers can be required with babel-register to support ES6/ES7 features. 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 memory limits are enforced. security checks are not simulated. You will probably find other differences.

Credits and inspiration

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

• Offline supports velocity templates.
• Offline takes into account your λ's timeouts.
• Offline puts a stronger focus on error handling by displaying stack traces and mimicking APIG's errors.
• Offline displays your routes on start.
• Offline has an open-source license.
• Offline dropped support for Serve's optional init script.
• Under the hood, Serve uses Express, Offline uses Hapi.

Roadmap

• Support for APIG models
• v1.0.0-rc1 when Serverless 0.5 is out.
• v1.0.0 when we have a test suite for velocity templates rendering

Contributing

Yes, thanks a lot!

Licence

MIT