serverless-esbuild-layers

0.1.9 verified Fri May 01 auth: no javascript

A Serverless Framework plugin that automatically externalizes Node.js dependencies into Lambda Layers using esbuild. Version 0.1.9 (current stable) supports npm, yarn, and pnpm as package managers, with forceInclude/forceExclude options and monorepo support via custom package.json paths. Unlike serverless-webpack-layers, this plugin integrates with serverless-esbuild and esbuild-node-externals to keep function sizes small by separating node_modules into shared layers, reducing deployment artifacts and cold starts.

Common errors

error Error: ENOENT: no such file or directory, open '/path/to/serverless.yml' ↓

cause serverless-esbuild-layers cannot find the serverless.yml file if the working directory is incorrect or file is missing.

fix

Run serverless commands from the directory containing serverless.yml, or specify --config path.

error Error: The 'plugins' section must be an array of strings ↓

cause Plugins listed in serverless.yml are not valid string names (e.g., missing quotes or using object syntax).

fix

Ensure plugins are listed as strings: plugins: - serverless-esbuild - serverless-esbuild-layers

error TypeError: nodeExternalsPlugin is not a function ↓

cause Incorrect import style; esbuild-node-externals exports a named function, not a default export.

fix

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

error Error: Layer 'lib' not found in the CloudFormation template ↓

cause Layer definitions are missing or the reference name in the function does not match the auto-generated ref name.

fix

Add a layer definition under 'layers' and ensure function layer references use { Ref: LibLambdaLayer } with correct capitalization.

Warnings

gotcha Plugin order in serverless.yml matters: serverless-esbuild must be listed BEFORE serverless-esbuild-layers. ↓

fix List serverless-esbuild first in the plugins array.

gotcha All node_modules must be externalized via esbuild-plugin-externals (or esbuild-node-externals) for the layer separation to work. If any module is bundled in-line, it won't be available in layers. ↓

fix Configure serverless-esbuild to exclude '*' and use esbuild-node-externals plugin.

gotcha Auto-detection of packager may fail in monorepos or when lockfiles are missing. Set packager explicitly (npm, yarn, pnpm) to avoid errors. ↓

fix Set custom.esbuild-layers.packager to the correct package manager.

breaking Layers must have a name that matches the convention: for a layer key 'lib', the CloudFormation reference is 'LibLambdaLayer' (first letter uppercase). Incorrect references cause deployment failures. ↓

fix Ensure function layer references match the pattern: { Ref: <LayerKey>LambdaLayer } with first letter uppercase.

Install

npm install serverless-esbuild-layers

yarn add serverless-esbuild-layers

pnpm add serverless-esbuild-layers

Imports

default (plugin)

wrong

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

correct

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

Order matters: serverless-esbuild must come before serverless-esbuild-layers in the plugins list

esbuild-node-externals plugin

wrong

const nodeExternalsPlugin = require('esbuild-node-externals');
module.exports = [nodeExternalsPlugin()];

correct

const { nodeExternalsPlugin } = require('esbuild-node-externals');
module.exports = [nodeExternalsPlugin()];

esbuild-node-externals exports a named function, not a default export

Custom esbuild-layers config
wrong
```
custom:
  esbuild-layers:
    packager: yarn
```
correct
```
custom:
  esbuild-layers:
    packager: 'yarn'
    forceInclude:
      - lodash
```
packager must be a string literal in YAML (enclosed in quotes), not a bare word, to avoid being interpreted as a boolean

Quickstart

Complete setup for Serverless Framework with esbuild layers: plugin configuration, externalisation via esbuild-node-externals, layer definition, and function attachment.

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

// serverless.yml
plugins:
  - serverless-esbuild
  - serverless-esbuild-layers

custom:
  esbuild:
    plugins: esbuild-plugins.js
    exclude:
      - '*'
  esbuild-layers:
    packager: 'npm'
    forceExclude:
      - aws-sdk
    forceInclude:
      - my-common-lib

layers:
  lib:
    path: '.serverless'
    name: my-modules
    description: node_modules
    compatibleRuntimes:
      - nodejs14.x

functions:
  hello:
    handler: handler.hello
    layers:
      - { Ref: LibLambdaLayer }