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 λ and API Gateway on your local machine to speed up your development cycles.

Features

• Nodejs λ handlers only (more runtimes support is on the roadmap, PRs are welcome).
• Velocity support: requestTemplates and responseTemplates.
• Timeouts according to your configuration files.
• Lazy loading of your files with require cache invalidation: no need for a reloading tool like Nodemon.
• And more: responseParameters, HTTPS, CoffeeScript, Babel runtime, etc...

Installation

Serverless version	Command
0.5	npm install serverless-offline
0.4	npm install serverless-offline@1.3.1

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

Like this: "plugins": ["serverless-offline"]

Usage and command line options

In your project root run:

sls offline start

All CLI options are optionnal:

Option, shortcut	Description
--prefix -p	Adds a prefix to every path, to send your requests to http://localhost:3000/prefix/[your_path] instead. E.g. -p dev
--port -P	Port to listen on. Default: 3000.
--stage -s	The stage used to populate your templates. Default: the first stage found in your project.
--region -r	The region used to populate your templates. Default: the first region for the first stage found.
--httpsProtocol -H	To enable HTTPS, specify directory (relative to your cwd, typically your project dir) for both cert.pem and key.pem files. E.g. -H ./certs.
--skipCacheInvalidation -c	Tells the plugin to skip require cache invalidation. A script reloading tool like Nodemon might then be needed.
--debugOffline	Prints debug messages. Can be useful to see how your templates are processed.

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

• You'll need to restart the plugin if you modify your s-function.json or s-templates.json files.
• The event object passed to your λs has one extra key: { isOffline: true }. Also, process.env.IS_OFFLINE is true.
• When no Content-Type header is set on a request, API Gateway defaults to application/json, and so does the plugin. But if you send a application/x-www-form-urlencoded or a multipart/form-data body with a application/json (or no) Content-Type, API Gateway won't parse your data (you'll get the ugly raw as input) whereas the plugin will answer 400 (malformed JSON). Please consider explicitly setting your requests' Content-Type and using separates templates.

Usage with Babel

You can use Offline with Serverless-runtime-babel. To do so you need to install (at least) the es2015 preset in your project folder (npm i babel-preset-es2015).

~ Or ~

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

Usage with CoffeeScript

You can have handler.coffee instead of handler.js. No additional configuration is needed.

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, etc...

Response parameters

You can set your response's headers using ResponseParameters. See the APIG docs.

Example:

"responseParameters": {
  "method.response.header.X-Powered-By": "Serverless", // a string
  "method.response.header.Warning": "integration.response.body", // the whole response
  "method.response.header.Location": "integration.response.body.some.key" // a pseudo JSON-path
},

Velocity nuances

Consider this requestTemplate for a POST endpoint:

"application/json": {
  "payload": "$input.json('$')",
  "id_json": "$input.json('$.id')",
  "id_path": "$input.path('$').id"
}

Now let's make a request with this body: { "id": 1 }

AWS parses the event as such:

{
  "payload": {
    "id": 1
  },
  "id_json": 1,
  "id_path": "1" // Notice the string
}

Whereas Offline parses:

{
  "payload": {
    "id": 1
  },
  "id_json": 1,
  "id_path": 1, // Notice the number
  "isOffline": true
}

Accessing an attribute after using $input.path will return a string on AWS (expect strings like "1" or "true") but not with Offline (1 or true). You may find other differences.

Credits and inspiration

This plugin was initially a fork of Nopik's Serverless-serve.

Roadmap

Feel free to discuss or submit any improvement you can think of, listed or not.

• Support for other runtimes
• Test suite

Contributing

Yes, thanks a lot! There is no test suite or linting for this project. I try to follow Airbnb's JavaScript Style Guide.

License

MIT