💨 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

yarn add --dev serverless-esbuild
# or
npm install -D serverless-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'].

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 or yarn, default is npm
    packagePath: absolute/path/to/package.json # optional - by default it looks for a package.json in the working directory

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

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)

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

Author

Victor Korzunin

Contributors

Loup Topalian

Inspired by serverless-plugin-typescript and serverless-webpack