serverless-esbuild is a Serverless Framework plugin that provides zero-config bundling and minification for JavaScript and TypeScript projects using esbuild.

Key features include:

• Zero-config: Works out of the box.
• Language Support: Works with both TypeScript and JavaScript.
• Runtime Compatibility: Guaranteed to work in Node.js v18 and higher environments.
• Command Support: Supports sls package, sls deploy, and sls deploy function.
• Tool Integration: Integrates with Serverless Invoke Local and serverless-offline.

When using serverless-esbuild, you can control how dependencies are treated using two different mechanisms:

1. Bundling as a dependency: Any package listed in custom.esbuild.external will not be bundled into the output file. Instead, it will be treated as a node_modules dependency and packed into the deployment artifact.
2. Excluding from both bundling and packing: If a package is already available in your environment (for example, if it is provided via an AWS Lambda Layer), you can use the exclude option. This ensures the package is neither bundled into the code nor included in the node_modules package.

Note: aws-sdk is excluded by default.

# Example conceptual configuration
custom:
  esbuild:
    external: ['some-package-to-be-packed']
    exclude: ['some-package-in-a-layer']

The plugin automatically ignores functions that do not contain a handler or use a supported Node.js runtime (e.g., Python or container images).

Note for Python users: If you are using Python functions with Serverless Offline, you must change outputWorkFolder and outputBuildFolder to names that do not contain full stops (e.g., avoid .esbuild).

After installing the dependencies, add serverless-esbuild to the plugins section of your serverless.yml file to enable automatic bundling.

plugins:
  - serverless-esbuild

To use serverless-esbuild, you must install both the plugin and the esbuild bundler as development dependencies. You can use npm, yarn, or pnpm.

# 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

When using serverless-esbuild with the serverless-azure-functions plugin, you must manually include host.json and function.json in your package patterns to ensure function apps are built correctly.

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

The plugin integrates with serverless-offline for local simulation. Crucially, serverless-esbuild must appear before serverless-offline in your plugins list.

To enable file watching during local development, configure the watch option under custom.esbuild.

plugins:
  - serverless-esbuild
  - serverless-offline

custom:
  esbuild:
    watch:
      pattern: ['src/**/*.ts']
      ignore: ['temp/**/*']

When using serverless-dynamodb-local alongside serverless-offline, ensure the plugin order is: serverless-esbuild, then serverless-dynamodb-local, then serverless-offline. Use the start command to ensure lifecycle hooks are fired correctly.

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

Run with:

serverless offline start

By default, no configuration is required. To override default behavior, use the custom.esbuild section in your serverless.yml file. You can pass almost any Esbuild Javascript Build Option directly through this configuration.

custom:
  esbuild:
    bundle: true
    minify: false

Packages marked as external that exist in your package.json dependencies will be installed and included in your build under node_modules. You can customize the packager, the path to package.json, and additional installation arguments.

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'

You can provide an esbuild plugins configuration file via custom.esbuild.plugins. The file must export either an array of plugins or a function that accepts the serverless instance and returns an array of plugins.

custom:
  esbuild:
    plugins: plugins.js

// Option 1: Exporting an array
let myPlugin = {
  name: 'my-plugin',
  setup(build) {
    // plugin implementation
  },
};

module.exports = [myPlugin];

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

  return [myPlugin];
};

You can define your esbuild configuration in a separate JavaScript file. This file must export a function that receives the serverless instance and returns an esbuild configuration object.

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

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