IOpipe Serverless Framework Plugin

A serverless plugin to automatically wrap your functions with iopipe.

Requirements

• Node >= 4.3.2
• NPM >= 2.14.12
• Serverless >= 1.13.0
• Yarn >= 0.22.0 (optional)
• A valid package.json file
• A valid serverless.yml file

Install

With yarn (recommended) in project directory:

yarn add @iopipe/iopipe
yarn add serverless-plugin-iopipe --dev

OR with npm in project directory:

npm install @iopipe/iopipe
npm install serverless-plugin-iopipe --save-dev

Add the plugin to your serverless.yml file:

plugins:
  - serverless-plugin-iopipe

You'll need to make sure your lambda functions have access to your IOpipe project token. The recommended strategy is to use an environment variable. Just setup the variable in serverless.yml like any other.

environment:
  IOPIPE_TOKEN: ${env:IOPIPE_TOKEN}

Alternatively, you can add an iopipe configuration to your package.json.

You're set! The plugin will run during an sls deploy or during sls invoke local.

Check out an example here.

How Does it Work?

serverless-plugin-iopipe outputs files that import and wrap the function handlers defined in serverless.yml with IOpipe so you don't have to. It allows you to deploy and upgrade multiple functions simultaneously.

Commands

• sls iopipe clean This command cleans up your project folder of extraneous *-iopipe.js files if needed. This can be useful when using the serverless-offline plugin.

Options

Beyond the required $IOPIPE_TOKEN environment variable, some options can be set in the "custom" config in serverless.yml. See Example

iopipeToken (optional)

If not using the environment variable of $IOPIPE_TOKEN, the token of the project you would like to wrap your functions with.

iopipeNoVerify (optional)

Skip a check that ensures iopipe is installed via npm/yarn and present in package.json

iopipeNoUpgrade (optional)

The plugin automatically upgrades the IOpipe library to the latest available version that satisfies the semver range specified in package.json. Use this option to disable that feature.

iopipeNoYarn (optional)

When auto-upgrading, Yarn will be used in place of NPM if a yarn.lock file is found. Use this flag disable yarn and use NPM to upgrade the iopipe library.

iopipeExclude (optional)

Exclude certain lambda functions from being wrapped by the plugin. Comma separated string.

iopipeNoStats (optional)

By default, the plugin sends anonymized, non-identifying usage statistics to Google Analytics. IOpipe will use this info to prioritize updates and enhancements to the plugin. If you'd like to opt out of this, just set this option.

iopipeHandlerDir (optional)

Change the directory that the IOpipe handler files will be generated in. Defaults to iopipe_handlers. Note, watch out using directories beginning with a . character due to current bugs within Serverless framework and serverless-offline:

• serverless/issues/4633
• serverless-offline/pull/346

FAQ

• Does this work with webpack?
  • Yes, you can use this plugin with webpack or serverless plugins utilizing webpack. For best results, make sure this plugin is specified before the webpack plugins in serverless.yml, i.e.

  plugins:
    - serverless-plugin-iopipe
    - serverless-webpack

• Does this work with serverless-offline?
  • Yes, list serverless-plugin-iopipe first before any other plugins in serverless.yml.
  • You will likely need to use the iopipeHandlerDir option to change where the IOpipe handler files are generated until this PR is merged.
• Can I use IOpipe plugins?
  • Yes, you can specify iopipe plugins through your package.json file, or an iopipe.rc file. Ensure those plugins are installed into your node_modules folder (yarn or npm).

Known Issues

• If you have lambda functions that are already wrapped by iopipe via code, you may experience unexpected results. Remove the iopipe wrapping code from those handlers.
• If your package.json is located in a non-standard place, auto-upgrading may not work.
• If attempting to use es6 modules natively i.e. export function handler..., may not work.

Support

File an issue here, hit us up on Slack, or send us a note at [email protected]

Contributing

• This project uses Prettier. Please execute npm run eslintFix to auto-format the code before submitting pull requests.