{"id":26380,"library":"serverless-esbuild-layers","title":"serverless-esbuild-layers","description":"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.","status":"active","version":"0.1.9","language":"javascript","source_language":"en","source_url":"https://github.com/beforeyoubid/serverless-esbuild-layers","tags":["javascript","serverless","aws","lambda","layers","esbuild","typescript"],"install":[{"cmd":"npm install serverless-esbuild-layers","lang":"bash","label":"npm"},{"cmd":"yarn add serverless-esbuild-layers","lang":"bash","label":"yarn"},{"cmd":"pnpm add serverless-esbuild-layers","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: plugin requires the Serverless Framework to hook into build lifecycle events","package":"serverless","optional":false},{"reason":"Peer dependency: this plugin is designed to work alongside serverless-esbuild for bundling","package":"serverless-esbuild","optional":false},{"reason":"Required to externalize all node_modules during esbuild bundling so layers can pick them up","package":"esbuild-node-externals","optional":false}],"imports":[{"note":"Order matters: serverless-esbuild must come before serverless-esbuild-layers in the plugins list","wrong":"plugins:\n  - serverless-esbuild-layers\n  - serverless-esbuild","symbol":"default (plugin)","correct":"plugins:\n  - serverless-esbuild\n  - serverless-esbuild-layers"},{"note":"esbuild-node-externals exports a named function, not a default export","wrong":"const nodeExternalsPlugin = require('esbuild-node-externals');\nmodule.exports = [nodeExternalsPlugin()];","symbol":"esbuild-node-externals plugin","correct":"const { nodeExternalsPlugin } = require('esbuild-node-externals');\nmodule.exports = [nodeExternalsPlugin()];"},{"note":"packager must be a string literal in YAML (enclosed in quotes), not a bare word, to avoid being interpreted as a boolean","wrong":"custom:\n  esbuild-layers:\n    packager: yarn","symbol":"Custom esbuild-layers config","correct":"custom:\n  esbuild-layers:\n    packager: 'yarn'\n    forceInclude:\n      - lodash"}],"quickstart":{"code":"// esbuild-plugins.js\nconst { nodeExternalsPlugin } = require('esbuild-node-externals');\nmodule.exports = [nodeExternalsPlugin()];\n\n// serverless.yml\nplugins:\n  - serverless-esbuild\n  - serverless-esbuild-layers\n\ncustom:\n  esbuild:\n    plugins: esbuild-plugins.js\n    exclude:\n      - '*'\n  esbuild-layers:\n    packager: 'npm'\n    forceExclude:\n      - aws-sdk\n    forceInclude:\n      - my-common-lib\n\nlayers:\n  lib:\n    path: '.serverless'\n    name: my-modules\n    description: node_modules\n    compatibleRuntimes:\n      - nodejs14.x\n\nfunctions:\n  hello:\n    handler: handler.hello\n    layers:\n      - { Ref: LibLambdaLayer }","lang":"typescript","description":"Complete setup for Serverless Framework with esbuild layers: plugin configuration, externalisation via esbuild-node-externals, layer definition, and function attachment."},"warnings":[{"fix":"List serverless-esbuild first in the plugins array.","message":"Plugin order in serverless.yml matters: serverless-esbuild must be listed BEFORE serverless-esbuild-layers.","severity":"gotcha","affected_versions":"<0.1.0"},{"fix":"Configure serverless-esbuild to exclude '*' and use esbuild-node-externals plugin.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Set custom.esbuild-layers.packager to the correct package manager.","message":"Auto-detection of packager may fail in monorepos or when lockfiles are missing. Set packager explicitly (npm, yarn, pnpm) to avoid errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure function layer references match the pattern: { Ref: <LayerKey>LambdaLayer } with first letter uppercase.","message":"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.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run serverless commands from the directory containing serverless.yml, or specify --config path.","cause":"serverless-esbuild-layers cannot find the serverless.yml file if the working directory is incorrect or file is missing.","error":"Error: ENOENT: no such file or directory, open '/path/to/serverless.yml'"},{"fix":"Ensure plugins are listed as strings: plugins:\n  - serverless-esbuild\n  - serverless-esbuild-layers","cause":"Plugins listed in serverless.yml are not valid string names (e.g., missing quotes or using object syntax).","error":"Error: The 'plugins' section must be an array of strings"},{"fix":"Use const { nodeExternalsPlugin } = require('esbuild-node-externals');","cause":"Incorrect import style; esbuild-node-externals exports a named function, not a default export.","error":"TypeError: nodeExternalsPlugin is not a function"},{"fix":"Add a layer definition under 'layers' and ensure function layer references use { Ref: LibLambdaLayer } with correct capitalization.","cause":"Layer definitions are missing or the reference name in the function does not match the auto-generated ref name.","error":"Error: Layer 'lib' not found in the CloudFormation template"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}