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.


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

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



["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)



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:

      - is-object


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


npm test

See also

Inspired by Serverless Plugin Include Dependencies and Webpack Node Externals