Serverless Externals Plugin

Only include listed node modules and their dependencies in Serverless, with support for Rollup and Webpack

Serverless Externals Plugin

Build Status

This plugin was made for Serverless builds that use Rollup or Webpack. It does two things:

  • It generates a list of external modules for Rollup/Webpack (should be kept as require() in bundle)
  • It includes those modules and their dependencies in the package which is uploaded with Serverless.

This list of external modules is kept in a file called node-externals.json.

If there's a global module available (like aws-sdk), you can exclude it from the package. See below.

See test/example-project for a typical project.

Motivation

I wanted to include Cheerio/JSDom and AWS SDK in a Typescript project, but neither could be bundled because of obscure errors, so they needed to be external. To reduce package size, I didn't want to make every module external. Manually looking up a module and adding its dependencies to rollup.config.js and serverless.yml is simply too much work. This plugin makes this much easier.

Typical configuration

serverless.yml:

...

plugins:
  - serverless-externals-plugin

custom:
  externals:
    exclude:
      - aws-sdk
    # file: node-externals.json
    # modules: [is-string, is-array]

...

node-externals.json:

["is-string", "is-array", "aws-sdk"]

rollup.config.js (if you're using Rollup):

const externals = require('serverless-externals-plugin').externalsRollup;

module.exports = async function() {
  return {
    input: 'src/main.js',
    ...
    external: await externals(__dirname)
  }
};

webpack.config.js (if you're using Webpack):

const externals = require('serverless-externals-plugin').externalsWebpack;

module.exports = {
  entry: 'src/main.js',
  ...
  externals: externals(__dirname)
};

Advanced

node-externals.json

If you don't like adding a node-externals.json file, you can pass a list of module names to the externals function:

externals(__dirname, ['is-object'])

And declare a list of modules in serverless.yml:

custom:
  externals:
    modules:
      - is-object

Config

The externals function takes a third argument object, config.

Key Default Description
externalsFilePath path.join(root, 'node-externals.json') Path to node-externals.json
packagePath path.join(root, 'package-lock.json') Path to your package-lock.json or package.json
exclude [] Filters values from node-externals.json (perfect for globally installed modules, like aws-sdk)
ls {development: false, optional: false, peer: false} Passed to npm-remote-ls

Testing

npm test

See also

Inspired by Serverless Plugin Include Dependencies and Webpack Node Externals

view on Github

Latest commit b2f54ec on Sep 24, 2017

New to serverless?

To get started, pop open your terminal & run:

npm install serverless -g