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

• Zero-config: Works out of the box without the need to install any additional plugins
• Works with Typescript and Javascript projects
• Guaranteed to work in Node.js v18 and higher environments
• Supports sls package, sls deploy, sls deploy function
• Integrates with Serverless Invoke Local & serverless-offline

• Install
• Configuration
  • Examples
  • Options
    • Default Esbuild Options
    • Packager Options
    • Watch Options
• Supported Runtimes
• Advanced Configuration
  • Including Extra Files
  • External Dependencies
  • Esbuild Plugins
• Usage
  • Automatic Compilation
  • Serverless Offline
    • Serverless Dynamodb Local
  • Invoke Local
• External Tools
• Contributors

# 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

By default, no configuration is required, but you can override the default behavior via the custom.esbuild section in the serverless.yml file.

custom:
  esbuild:
    bundle: true
    minify: false

See example folder for some example configurations.

The following esbuild options are automatically set.

This plugin will automatically set the esbuild target for the following supported Serverless runtimes:

This plugin is compatible with the serverless-google-cloudfunctions plugin, and will set the runtimes accordingly.

This plugin is compatible with the serverless-azure-functions plugin, and will set the runtimes accordingly.

Please Note When using this package in conjunction with the serverless-azure-functions plugin, the following additional configuration is required to ensure function apps are built correctly:

package:
	patterns: ["host.json", "**/function.json"],

If you wish to use this plugin alongside non Node functions like Python or functions with images, this plugin will automatically ignore any function which does not contain a handler or use a supported Node.js runtime.

Note: If you are using Python functions with Serverless Offline you will need to change the outputWorkFolder and outputBuildFolder to folder names without fullstops.

Esbuild configuration can be defined by a config file.

custom:
  esbuild:
    config: './esbuild.config.js'

// esbuild.config.js
module.exports = (serverless) => ({
  external: ['lodash'],
  plugins: [],
});

Serverless Package Configuration will behave in the same way as native packaging. You can use patterns, include and exclude to include extra files into your bundles.

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 customize this with a number of options.

custom:
  esbuild:
    external:
      - lodash
    packager: yarn
    packagePath: absolute/path/to/package.json
    packagerOptions:
      scripts:
        - echo 'Hello World!'
        - rm -rf node_modules
    installExtraArgs:
      - '--legacy-peer-deps'

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'

Note: The Esbuild plugins API is still experimental

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];
};

As long as the plugin is properly installed, all regular Serverless operations sls package, sls deploy, sls deploy function, sls invoke local, sls offline will automatically compile using serverless-esbuild.

You can specify a custom entrypoint for ESBuild by specifying the esbuildEntrypoint field in your function definition.

export const myLambdaFunction = {
  handler: '/opt/nodejs/node_modules/my_custom_extension/handler.handler',
  esbuildEntrypoint: './handler.main',
};

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.

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

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

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.

This plugin supports the Serverless Invoke Local functionality and will automatically compile the selected function.

• serverless-analyze-bundle-plugin: a plugin that allow users to analyze the bundle of a lambda

Victor Korzunin 💬 💻 📖 💡 🤔 🚇 🚧 🔌 📆 👀 ⚠️ 🔧	Loup Topalian 💬 💻 📖 🚇 🚧 🔌	Sam Chung 💬 💻 📖 💡 🚇 🚧 🔌 👀 🔧	Vamsi Dharmavarapu 💻 📖 💡 🚇 🚧	Eric 💻 🤔 🚧 🚇 👀	Chris 💻 🤔	Martín Acosta 💻
Tony Tyrrell 💻	Matt Jennings 💻	Misha Bruml 💻	François Farge 💻	Sam Hulick 📖	Troy Ready 💻	subash adhikari 💻
Dan Ionescu 💻	gurushida 💻	nickygb 💻	Jiri Spac 💻	gavynriebau 📖	Adrien Cacciaguerra 📖	lulzneko 💻
AOKI Yuuto 💻	Thomas Aribart 🤔	Kory Hutchison 💻 🤔	Chris Hutchinson 💻	Fredrik Möllerstrand 💻	Sander Kooger 💻	Adam Swift 💻
Florian Mayer 💻	Zach Levi 💻

Inspired by serverless-plugin-typescript and serverless-webpack