serverless-esbuild-layers

Plugin for the Serverless framework that allows you to leverage Lambda layers to separate your node modules into layers attached to relevant functions.

This helps to keep the overall function size down.

This library is designed to be used in conjuction with serverless-esbuild to build your code.

If you are using serverless-webpack, you can try serverless-webpack-layers to achieve this functionality.

Installation

yarn add --dev serverless-esbuild-layers serverless-esbuild esbuild-node-externals
npm install --save-dev serverless-esbuild-layers serverless-esbuild esbuild-node-externals
pnpm install --dev serverless-esbuild-layers serverless-esbuild esbuild-node-externals

Setup

Once installed, you need to add this to your serverless plugins:

plugins:
  - serverless-esbuild
  - serverless-esbuild-layers

You also need to configure serverless-esbuild to externalise all node modules:

custom:
  esbuild:
    plugins: esbuild-plugins.js
    packages: 'external'  

the serverless-esbuild library supports custom plugins to configure esbuild. In order to leverage this library, you need to use esbuild-node-externals to externalise all node modules

// esbuild-plugins.js
const { nodeExternalsPlugin } = require('esbuild-node-externals');

module.exports = [nodeExternalsPlugin()];

For more complex configurations, you may also use a full javascript configuration file:

• serverless.yml:

  esbuild:
    config: './esbuild.config.cjs'

• esbuild.config.cjs:

const { nodeExternalsPlugin } = require('esbuild-node-externals')

module.exports = (serverless) => {
  return {
    package: 'external'
    platform: 'node',
    bundle: true,
    minify: false,
    sourcemap: false,
    treeShaking: true,
    plugins: [
      nodeExternalsPlugin({
        "allowWorkspaces": true
      }),
    ]
  }
}

Adding layers

Once the plugin is configured in your serverless file, you need to add Layer definitions to your serverless file:

layers:
  lib:
    path: '.serverless/layer'
    name: my-modules
    description: node_modules
    compatibleRuntimes:
      - nodejs20.x

Then you can reference the relevant layers in each function (the ref should match NameLambdaLayer where name is the key of your layer with the first character uppercase)

functions:
  test:
    handler: handler.default
    layers:
      - { Ref: LibLambdaLayer }

If you have multiple functions, it's recommended to add different layers depending on node module overlap. This library will identify which modules are needed by all the functions attached to each layer.

Config

This library can be configured by adding options into your serverless file:

custom:
  esbuild-layers:
    packager: 'auto' # can be specified as 'npm' | 'yarn' | 'pnpm';
    forceExclude:
      - some-library
    forceInclude:
      - some-other-library

Package.json pathing

If using a monorepo, you may need to specify a different package.json file. You can do so by using the packageJsonPath config variable like so:

custom:
  esbuild-layers:
    packageJsonPath: ../