💨 serverless-esbuild

Serverless plugin for zero-config JavaScript and TypeScript code bundling using promising fast & furious esbuild bundler and minifier

Features

Zero-config: Works out of the box without the need to install any other compiler or plugins
Supports ESNext syntax with transforming limitations (See Note)
Supports sls package, sls deploy and sls deploy function
Supports sls invoke local
Integrates nicely with serverless-offline

Note: The default JavaScript syntax target is determined from serverless provider configuration otherwise set to [node10], so the final bundle will be supported by all AWS Lambda Node.js runtimes. If you still using an old lambda runtime and have to respect it you can play with esbuild target option, see JavaScript syntax support for more details about syntax transform limitations.

Install

# install `serverless-esbuild` and `esbuild`
yarn add --dev serverless-esbuild esbuild
# or
npm install -D serverless-esbuild esbuild
# or
pnpm install -D serverless-esbuild esbuild

Add the following plugin to your serverless.yml:

plugins:
  - serverless-esbuild

Configure

By default, no configuration is required, but you can change esbuild behavior in custom esbuild section in serverless.yaml config:

custom:
  esbuild:
    bundle: true
    minify: false

Check esbuild documentation for the full list of available options. Note that some options like entryPoints or outdir cannot be overwritten. The package specified in the exclude option is passed to esbuild as external, but it is not included in the function bundle either. The default value for this option is ['aws-sdk']. You can set exclude to * to disable packaging node_modules.

See example folder for a minimal example.

Including extra files

All files from package/patterns will be included in the final build file. See Patterns.

Include/exclude is deprecated, but still supported.

External Dependencies

Packages that are marked as external and exist in the package.json's dependencies will be installed and included with your build under node_modules. You can configure how these are installed:

custom:
  esbuild:
    packager: yarn # optional - npm, pnpm or yarn, default is npm
    packagePath: absolute/path/to/package.json # optional - by default it looks for a package.json in the working directory
    packagerOptions: # optional - packager related options, currently supports only 'scripts' for both npm, pnpm and yarn
      scripts: # scripts to be executed, can be a string or array of strings
        - echo 'Hello World!'
        - rm -rf node_modules

To easily mark all the dependencies in package.json as external, you can utilize esbuild-node-externals plugin.

To mark one or more individual packages as external, use the following configuration:

custom:
  esbuild:
    external:
      - 'my-package-name'
      - 'another-package-name'

Passing Extra Arguments to Packager

This might be required to resolve some issues on package installation. One example is to pass --legacy-peer-deps to npm v7+, to use legacy peerDependency resolution behavior.

custom:
  esbuild:
    installExtraArgs: # optional. Default is empty (no arguments)
      - '--legacy-peer-deps'

Using esbuild plugins

Note that the plugins API is still experimental : see the documentation page

You can configure esbuild plugins by passing a plugins' configuration file:

custom:
  esbuild:
    plugins: plugins.js

The plugins' configuration file must be a javascript file exporting an array of plugins (see examples/individually/plugins.js for a dummy plugin example):

let myPlugin = {
  name: 'my-plugin',
  setup(build) {
    // plugin implementation
  },
};

// default export should be an array of plugins
module.exports = [myPlugin];

or a function that accepts serverless instance and returns an array of plugins (see issue #168 for an example):

module.exports = (serverless) => {
  const myPlugin = {
    name: 'my-plugin',
    setup(build) {
      // plugin implementation with `serverless` instance access
      console.log('sls custom options', serverless.service.custom);
    },
  };

  // an array of plugins must be returned
  return [myPlugin];
};

Native Zip

If you wish to use your system's zip executable to create archives (can be significantly faster when working with many large archives), set the nativeZip option:

custom:
  esbuild:
    nativeZip: true

NOTE: This will produce non-deterministic archives which causes a Serverless deployment update on every deploy.

Concurrency

If you wish to limit the concurrency of the bundling process (can be very expensive on memory), set the concurrency option:

custom:
  esbuild:
    concurrency: 10

NOTE: This will produce slower builds.

Usage

Automatic compilation

The normal Serverless deploy procedure will automatically compile with esbuild:

Create the Serverless project with serverless create -t aws-nodejs
Install Serverless esbuild plugin as above
Deploy with serverless deploy

Usage with serverless-offline

The plugin integrates very well with serverless-offline to simulate AWS Lambda and AWS API Gateway locally.

Add the plugins to your serverless.yml file and make sure that serverless-esbuild precedes serverless-offline as the order is important:

plugins: ...
  - serverless-esbuild
  ...
  - serverless-offline
  ...

Run serverless offline or serverless offline start to start the Lambda/API simulation.

In comparison to serverless offline, the start command will fire an init and a end lifecycle hook which is needed for serverless-offline and e.g. serverless-dynamodb-local to switch off resources (see below)

Automatic compilation is available while using the plugin with serverless-offline. Following are the default configuration:

pattern: './**/*.(js|ts)' # watches all javascript or typescripts files in the project
ignore: [.build, 'dist', 'node_modules', '.serverless']

You can override the defaults by using watch option in serverless esbuild config. Both options take [anymatch-compatible definition] (https://github.com/es128/anymatch)

custom:
  esbuild:
    watch:
      pattern: ['src/**/*.ts'] # match only typescript files in src directory
      ignore: ['temp/**/*']

Note: When overriding ignore pattern, remember to ignore .build directory to avoid endless compilation.

serverless-dynamodb-local

Configure your service the same as mentioned above, but additionally add the serverless-dynamodb-local plugin as follows:

plugins:
  - serverless-esbuild
  - serverless-dynamodb-local
  - serverless-offline

Run serverless offline start.

Run a function locally

To run your compiled functions locally you can:

$ serverless invoke local --function <function-name>

Options are:

--function or -f (required) is the name of the function to run
--path or -p (optional) path to JSON or YAML file holding input data
--data or -d (optional) input data

Plugin-Specific Options in Serverless Config

These options belong under custom.esbuild in your serverless.yml or serverless.ts file, and are specific to this plugin (these are not esbuild API options):

packager: Package to use (npm, pnpm or yarn - npm is default)
packagePath: Path to the package.json file (./package.json is default)
packagerOptions:
- scripts: A string or array of scripts to be executed, currently only supports 'scripts' for npm, pnpm and yarn
exclude: An array of dependencies to exclude (declares it as an external as well as excludes it from Lambda ZIP file)
installExtraArgs: Optional arguments passed to npm or yarn (empty is default)