serverless-esbuild

What is serverless-esbuild?

The serverless-esbuild npm package is a Serverless Framework plugin that allows you to use esbuild to bundle your JavaScript and TypeScript code. It is designed to optimize the deployment of serverless functions by providing fast and efficient builds.

What are serverless-esbuild's main functionalities?

Bundling JavaScript

This configuration demonstrates how to bundle a simple JavaScript function using esbuild. The 'bundle' option is set to true to enable bundling, and other options like 'minify', 'sourcemap', and 'target' are configured to optimize the build.

module.exports = {
  service: 'my-service',
  frameworkVersion: '2',
  plugins: ['serverless-esbuild'],
  provider: {
    name: 'aws',
    runtime: 'nodejs14.x'
  },
  functions: {
    hello: {
      handler: 'handler.hello'
    }
  },
  custom: {
    esbuild: {
      bundle: true,
      minify: false,
      sourcemap: true,
      target: 'node14',
      platform: 'node',
      external: ['aws-sdk']
    }
  }
};

Transpiling TypeScript

This configuration shows how to use esbuild to transpile TypeScript code. The 'tsconfig' option points to the TypeScript configuration file, enabling TypeScript support in the build process.

module.exports = {
  service: 'my-service',
  frameworkVersion: '2',
  plugins: ['serverless-esbuild'],
  provider: {
    name: 'aws',
    runtime: 'nodejs14.x'
  },
  functions: {
    hello: {
      handler: 'handler.hello'
    }
  },
  custom: {
    esbuild: {
      bundle: true,
      minify: false,
      sourcemap: true,
      target: 'node14',
      platform: 'node',
      external: ['aws-sdk'],
      tsconfig: 'tsconfig.json'
    }
  }
};

Including External Dependencies

This configuration demonstrates how to include external dependencies in the build process. The 'external' option specifies dependencies that should not be bundled, and the 'packager' option specifies the package manager to use.

module.exports = {
  service: 'my-service',
  frameworkVersion: '2',
  plugins: ['serverless-esbuild'],
  provider: {
    name: 'aws',
    runtime: 'nodejs14.x'
  },
  functions: {
    hello: {
      handler: 'handler.hello'
    }
  },
  custom: {
    esbuild: {
      bundle: true,
      minify: false,
      sourcemap: true,
      target: 'node14',
      platform: 'node',
      external: ['aws-sdk'],
      packager: 'yarn'
    }
  }
};

Other packages similar to serverless-esbuild

serverless-webpack

The serverless-webpack plugin integrates Webpack into the Serverless Framework. It allows for bundling, minification, and transpilation of JavaScript and TypeScript code. Compared to serverless-esbuild, serverless-webpack offers more extensive configuration options but may have slower build times.

serverless-bundle

The serverless-bundle plugin is a zero-config plugin that uses Webpack and Babel to bundle your Serverless functions. It simplifies the setup process by providing sensible defaults. While it is easier to use, it may not offer the same level of customization as serverless-esbuild.

serverless-plugin-typescript

The serverless-plugin-typescript plugin adds TypeScript support to the Serverless Framework. It compiles TypeScript to JavaScript before deployment. Unlike serverless-esbuild, it does not bundle the code, which may result in larger deployment packages.

README

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 ES2015 syntax + features (export, import, async, await, Promise, ...)
• Supports sls package, sls deploy and sls deploy function
• Supports sls invoke local
• Integrates nicely with serverless-offline

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 required, but you can change esbuild behavior in custom esbuild section in serverless.yaml config:

custom:
  esbuild:
    bundle: true
    minify: false

The aws-sdk module is exluded from bundle by default, and you can exclude additional dependencies using external option. Check esbuild documentation for the full list of available options. Note that some options like entryPoints or outdir cannot be overwritten.

See example folder for a minimal example.

Including extra files

All files from package/include will be included in the final build file. See Exclude/Include

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)

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

Inspired by serverless-plugin-typescript