0
# Serverless Webpack
1

2
Serverless Webpack is a Serverless Framework plugin that bundles Lambda functions with Webpack, enabling modern JavaScript development workflows. It supports configuration ranging from zero-config to fully customizable setups, integrates with Babel for latest JavaScript features, provides custom resource loader support, and optimizes packaged functions individually for smaller deployment packages.
3

4
## Package Information
5

6
- **Package Name**: serverless-webpack
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install serverless-webpack --save-dev`
10

11
## Core Setup
12

13
Add the plugin to your `serverless.yml`:
14

15
```yaml
16
plugins:
17
  - serverless-webpack
18
```
19

20
For Serverless v4, disable the default ESBuild support:
21

22
```yaml
23
build:
24
  esbuild: false
25
```
26

27
## Basic Usage
28

29
```yaml
30
# serverless.yml
31
plugins:
32
  - serverless-webpack
33

34
custom:
35
  webpack:
36
    webpackConfig: 'webpack.config.js'
37
    includeModules: true
38
    packager: 'npm'
39

40
functions:
41
  hello:
42
    handler: handler.hello
43
```
44

45
```javascript
46
// webpack.config.js
47
const slsw = require('serverless-webpack');
48

49
module.exports = {
50
  entry: slsw.lib.entries,
51
  target: 'node',
52
  mode: slsw.lib.webpack.isLocal ? 'development' : 'production',
53
  module: {
54
    rules: [
55
      {
56
        test: /\.js$/,
57
        exclude: /node_modules/,
58
        use: 'babel-loader'
59
      }
60
    ]
61
  }
62
};
63
```
64

65
## Architecture
66

67
Serverless Webpack is built around several key components:
68

69
- **Plugin System**: Serverless Framework plugin implementing build lifecycle hooks
70
- **Webpack Integration**: Provides `lib` export for accessing Serverless context in webpack configs
71
- **Configuration Management**: Flexible configuration system supporting zero-config to full customization
72
- **Module Packaging**: External module detection and packaging system supporting npm and yarn
73
- **Development Integration**: Local development support with watch mode and serverless-offline integration
74

75
## Capabilities
76

77
### Plugin Configuration
78

79
Configuration system for customizing webpack behavior, module packaging, and build options through serverless.yml.
80

81
```javascript { .api }
82
// Plugin configuration schema in serverless.yml
83
custom:
84
  webpack:
85
    webpackConfig: string;              // Path to webpack config file
86
    includeModules: boolean | object;   // External module inclusion settings  
87
    packager: 'npm' | 'yarn';          // Package manager selection
88
    packagerOptions: object;           // Package manager specific options
89
    excludeFiles: string;              // Glob pattern for file exclusion
90
    excludeRegex: string;              // Regex pattern for file exclusion
91
    keepOutputDirectory: boolean;      // Preserve webpack output directory
92
    concurrency: number;               // Compilation concurrency level
93
```
94

95
[Plugin Configuration](./configuration.md)
96

97
### Webpack Integration
98

99
Provides `lib` export for webpack configurations to access Serverless context, auto-generated entries, and build state.
100

101
```javascript { .api }
102
const slsw = require('serverless-webpack');
103

104
// Available properties
105
slsw.lib.entries: { [functionName: string]: string };    // Auto-generated webpack entries
106
slsw.lib.webpack.isLocal: boolean;                       // Local development flag
107
slsw.lib.serverless: ServerlessInstance;               // Full Serverless framework access
108
slsw.lib.options: { [key: string]: any };              // Command-line options
109
```
110

111
[Webpack Integration](./webpack-integration.md)
112

113
### Build and Compilation
114

115
Core webpack compilation functionality with support for multiple webpack versions, watch mode, and optimization.
116

117
```javascript { .api }
118
// Serverless commands enhanced by plugin
119
sls webpack                    // Run full webpack build
120
sls webpack validate          // Validate configuration 
121
sls webpack compile           // Compile functions
122
sls webpack compile watch     // Compile with watch mode
123
sls webpack package          // Package external modules
124

125
// Command options
126
--out <path>                 // Output directory path
127
--skip-build                // Skip webpack compilation
128
--watch                     // Enable watch mode
129
--webpack-use-polling <ms>  // Polling interval for changes
130
--webpack-no-watch         // Disable automatic watch mode
131
```
132

133
[Build and Compilation](./build-compilation.md)
134

135
### Module Packaging
136

137
External module detection, dependency resolution, and packaging system supporting npm and yarn with workspace support.
138

139
```javascript { .api }
140
// Module inclusion configuration
141
includeModules: boolean | {
142
  packagePath?: string;           // Path to package.json
143
  nodeModulesRelativeDir?: string; // Relative path to node_modules
144
  packageLockPath?: string;       // Path to package-lock.json
145
  forceExclude?: string[];       // Modules to force exclude
146
  forceInclude?: string[];       // Modules to force include
147
}
148

149
// Packager options
150
packagerOptions: {
151
  [key: string]: any;  // Packager-specific options
152
}
153
```
154

155
[Module Packaging](./module-packaging.md)
156

157
### Development Integration
158

159
Local development support with serverless invoke local, serverless-offline integration, and watch capabilities.
160

161
```javascript { .api }
162
// Enhanced local commands
163
sls invoke local                          // Local function invocation with webpack
164
sls invoke local --watch                 // Local invocation with watch mode
165
sls invoke local --skip-build           // Skip webpack compilation
166
sls invoke local --webpack-use-polling  // Set polling interval
167

168
sls offline start                        // serverless-offline with webpack
169
sls offline start --webpack-no-watch    // Disable webpack watch
170
sls offline start --skip-build          // Skip initial build
171

172
sls run                                  // Run function locally
173
sls run --watch                         // Run with watch mode
174
```
175

176
[Development Integration](./development-integration.md)
177

178
### Utilities
179

180
Core utility functions for webpack integration, process management, and serverless framework operations.
181

182
```javascript { .api }
183
// Runtime detection utilities
184
function isNodeRuntime(runtime: string): boolean;
185
function getAllNodeFunctions(): string[];
186
function isProviderGoogle(serverless: ServerlessInstance): boolean;
187

188
// Process management utilities  
189
function spawnProcess(command: string, args: string[], options?: any): Promise<{stdout: string, stderr: string}>;
190
function guid(): string;
191

192
// Module cache management
193
function purgeCache(moduleName: string): Promise<void>;
194
function searchAndProcessCache(moduleName: string, processor: Function): Promise<void>;
195

196
// Data parsing utilities
197
function safeJsonParse(str: string): any | null;
198
function splitLines(str: string): string[];
199
```
200

201
[Utilities](./utilities.md)
202

203
### Packager System
204

205
Package manager abstraction supporting npm and yarn with workspace and monorepo capabilities.
206

207
```javascript { .api }
208
// Packager factory and interface
209
function get(packagerId: 'npm' | 'yarn'): Packager;
210

211
interface Packager {
212
  static lockfileName: string;
213
  static mustCopyModules: boolean;
214
  static getPackagerVersion(cwd: string): Promise<Object>;
215
  static getProdDependencies(cwd: string, depth?: number): Promise<Object>;
216
  static install(cwd: string, packagerOptions?: Object): Promise<void>;
217
  static prune(cwd: string, packagerOptions?: Object): Promise<void>;
218
  static runScripts(cwd: string, scriptNames: string[]): Promise<void>;
219
}
220
```
221

222
[Packager System](./packagers.md)
223

224
## Types
225

226
```javascript { .api }
227
// Main plugin class with complete API surface
228
class ServerlessWebpack {
229
  static lib: {
230
    entries: { [functionName: string]: string };
231
    webpack: { isLocal: boolean };
232
    serverless: ServerlessInstance;
233
    options: { [key: string]: string | boolean | number } & { param?: string[] };
234
  };
235
  
236
  constructor(serverless: ServerlessInstance, options: any, v3Utils?: { log: Function, progress: any });
237
  
238
  // Configuration and state properties
239
  webpackConfig: any;
240
  configuration: Configuration;
241
  webpackOutputPath: string;
242
  skipCompile: boolean;
243
  isWatching: boolean;
244
  keepOutputDirectory: boolean;
245
  entryFunctions: string[];
246
  
247
  // Lifecycle methods
248
  validate(): Promise<void>;
249
  compile(): Promise<void>;
250
  wpwatch(): Promise<void>;
251
  cleanup(): Promise<void>;
252
  watch(command?: string | Function): Promise<void>;
253
  
254
  // Module and packaging methods
255
  packExternalModules(): Promise<void>;
256
  packageModules(): Promise<void>;
257
  copyExistingArtifacts(): Promise<void>;
258
  
259
  // Local development methods
260
  prepareLocalInvoke(): Promise<void>;
261
  prepareOfflineInvoke(): Promise<void>;
262
  prepareStepOfflineInvoke(): Promise<void>;
263
  prepareRun(): Promise<void>;
264
  watchRun(): Promise<void>;
265
  
266
  // Plugin support
267
  runPluginSupport(): Promise<void>;
268
}
269

270
// Configuration class with complete API
271
class Configuration {
272
  constructor(custom: any);
273
  webpackConfig: string;
274
  includeModules: boolean | object;
275
  excludeFiles: string;
276
  excludeRegex: string;
277
  packager: string;
278
  packagerOptions: object;
279
  config: object;
280
  hasLegacyConfig: boolean;
281
  keepOutputDirectory: boolean;
282
  concurrency: number;
283
  toJSON(): object;
284
}
285

286
// Complete utility functions
287
function isNodeRuntime(runtime: string): boolean;
288
function getAllNodeFunctions(): string[];
289
function isProviderGoogle(serverless: ServerlessInstance): boolean;
290
function spawnProcess(command: string, args: string[], options?: any): Promise<{stdout: string, stderr: string}>;
291
function guid(): string;
292
function purgeCache(moduleName: string): Promise<void>;
293
function searchAndProcessCache(moduleName: string, processor: Function): Promise<void>;
294
function safeJsonParse(str: string): any | null;
295
function splitLines(str: string): string[];
296

297
// Error types with complete interface
298
class SpawnError extends Error {
299
  stdout: string;
300
  stderr: string;
301
  constructor(message: string, stdout: string, stderr: string);
302
  toString(): string;
303
}
304
```