serverless-webpack: Webpack Builds for Serverless Lambda Packages

Why serverless-webpack Changes Lambda Packaging

serverless-webpack addresses a specific gap in Serverless deployments: getting modern JavaScript transformations and dependency organization into Lambda packages without manually rewriting packaged artifacts. It is aimed at engineers using the Serverless Framework who need Babel, custom Webpack resource loaders, optimized functions, or separate bundles for separate Lambda handlers. The plugin also supports packaging, full deployment, single-function deployment, local invocation, and watch-based local or run workflows.

The central packaging choice is per-function compilation. The README states that functions are packaged and compiled individually when this behavior is enabled, so each resulting package can contain only the code and dependencies needed by that function. That makes Webpack tree shaking more useful because unused modules do not have to be retained in a shared bundle. This benefit depends on correct entries and dependency configuration. A badly mapped handler can produce a small but unusable archive.

The project supports Webpack 3, 4, and 5. Its package metadata narrows the current peer dependency to `>= 3.0.0 < 6`, while development is configured against Webpack 5. The documented Node.js requirement is `>= 20`, and the package metadata also requires npm `>= 11` when npm is the package manager. Older runtime environments are therefore outside the documented installation boundary.

Automatic Entries, Async Configuration, and Build Data Flow

The plugin can derive Webpack entries from each function's `handler` value. A Webpack configuration uses `slsw.lib.entries` as its entry value, which avoids maintaining a second list whenever Serverless functions are added or removed. This is more than a convenience. It creates a direct link between the service definition and the bundler's input graph, which is important when several functions have different handler modules.

The configuration can also be asynchronous. The README shows a configuration that awaits `slsw.lib.serverless.providers.aws.getAccountId()` and then returns a Webpack object containing `webpack.DefinePlugin`. This supports configurations whose inputs are not available synchronously, such as an AWS account lookup for Lambda@Edge. The plugin awaits the promise and uses the resolved configuration object.

For advanced cases, the library exposes `serverless`, `options`, and invocation state. The current stage can be read through `slsw.lib.options.stage`, while `lib.webpack` contains state variables such as `isLocal`. The README warns that exposed Serverless data should not be written to because mutation can alter the running framework and produce unpredictable behavior. Treat these properties as read-only inputs.

There is also a function-level `entrypoint` override. It is useful when the deployed handler comes from a layer and differs from the source module passed to Webpack. The example maps `handler: layer.handler` to `entrypoint: src/index.handler`. This separation is useful, but it creates another configuration surface that must be checked when handlers move.

Installing serverless-webpack and Enabling It in serverless.yml

The README gives npm and Yarn installation paths. Choose the package manager already used by the service rather than introducing a second one. After installation, register the plugin in the Serverless service configuration.

For npm, install the plugin as a development dependency:

$ npm install serverless-webpack --save-dev

For a Yarn-based service, use the documented development dependency command:

$ yarn add serverless-webpack --dev

Register the plugin under `plugins`:

plugins:
  - serverless-webpack

The plugin's default settings are documented as `webpack.config.js`, no included Node modules, npm as the packager, and `src/**/*.test.js` as the excluded file glob. The default `includeModules: false` is significant. It means the plugin does not automatically bundle or package external modules by default. If a function requires dependencies that Webpack leaves external, the service needs an explicit packaging configuration.

Serverless v4 has one additional requirement documented by the README:

build:
  esbuild: false

This disables the default built-in ESBuild support because the README identifies it as conflicting with serverless-webpack.

A First Webpack Configuration for Serverless Handlers

A minimal configuration can use the plugin's generated entries and the Node target. The README presents `target: 'node'` and shows `slsw.lib.entries` as the way to resolve handlers at build time. The following configuration keeps the example focused on the integration rather than selecting loaders or optimization plugins:

// webpack.config.js
const slsw = require('serverless-webpack');

module.exports = {
  entry: slsw.lib.entries,
  target: 'node'
};

After saving that file, run the normal Serverless packaging command. The README lists `serverless package` as a supported command:

$ serverless package

The expected result is a Webpack build performed through the plugin during the Serverless packaging operation.

For a deployment, the same integration is used by the documented `serverless deploy` command. A single function can be handled with the documented `serverless deploy function` command. The README also lists `serverless invoke local` and `serverless invoke local --watch`, plus `serverless run` and `serverless run --watch`. These commands are useful because they place Webpack processing in the local development path rather than limiting it to deployment.

A custom Webpack file can be selected under `custom.webpack.webpackConfig`. The documented default is `webpack.config.js`, and the example points to `./folder/my-webpack.config.js`. Keeping the file at the default location is the least ambiguous starting point.

Dependencies, Exclusions, and Packaging Boundaries

Dependency handling is configurable rather than automatic. The plugin supports npm and Yarn for packaging external modules, and the service can select the packager with `custom.webpack.packager`. This matters for services using native modules, workspace layouts, or a package manager lockfile. The repository includes examples for external npm packages, lock files, Yarn workspaces, Babel, TypeScript, and Serverless v4, which indicates that dependency packaging is a recurring integration concern.

The exclusion setting is a glob. The documented default is `src/**/*.test.js`, and the key is `excludeFiles`. A project should review this pattern when its test files live elsewhere. Excluding tests can keep them out of generated artifacts, but changing the default pattern without checking the service tree can leave unwanted files in a package or remove a file that the deployment expects.

Webpack loaders can add Babel or other transformations, while `DefinePlugin` can inject configuration values into the bundle. The README's asynchronous example uses an AWS account ID in `DefinePlugin`, but that does not mean every configuration should perform network or AWS API calls. Account lookup adds runtime preparation, permission requirements, and a potential failure point before compilation begins. The example is most appropriate when the value is genuinely needed and the build environment already has the relevant Serverless provider access.

The plugin also documents integration with `serverless-offline` for local API Gateway endpoint simulation. That is an integration surface, not proof that every offline behavior is identical to deployed Lambda behavior. Local invocation support should still be checked against the plugin's `isLocal` state when configuration differs between local and remote builds.

Compatibility, Maintenance, and Upgrade Work

The repository is not archived, and the last push was on 2026-10-12. The listed releases include v5.16.0, v5.16.1, and v5.16.2 in July 2026. That indicates recent release activity, but it does not remove the normal upgrade work created by a plugin that sits between Serverless, Webpack, Node.js, and a package manager.

The package is MIT licensed. That identifies the project's declared licensing model, but it does not by itself settle questions about application code, dependencies, lockfiles, or deployment ownership. An organization should review the repository license and dependency licenses as part of its normal release process rather than treating the plugin's license field as a complete compliance answer.

The peer dependencies explicitly permit Serverless 1 through 4, Webpack versions from 3 up to but not including 6, and optional `ts-node` support with `>= 8.3.0`. The package's development configuration uses `serverless` aliased to `osls` and Webpack 5, but that does not mean every supported combination is equally covered by the repository's examples. A service should verify its actual Serverless major version, Webpack major version, Node.js version, and package manager before upgrading.

The largest operational boundary is the interaction with Serverless v4's built-in ESBuild support. The project explicitly requires disabling it. A team that wants both serverless-webpack and Serverless v4 default ESBuild behavior should treat the conflict as a design choice to resolve before adoption, rather than expecting both bundlers to manage the same package automatically.

Editorial conclusion

Adopt serverless-webpack when your Serverless service needs Webpack transformations or per-function packages and you can maintain Node.js, Webpack, and Serverless compatibility. Do not choose it merely to add another bundler to a service already using Serverless v4 default ESBuild support. Before adoption, verify that your Webpack configuration resolves every declared Lambda entry, that Serverless v4 has `build.esbuild` set to `false`, and that local packaging produces the handler paths expected by the service.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. serverless-heaven/serverless-webpack on GitHub