0
# Plugin Configuration
1

2
Plugin configuration system for customizing webpack behavior, module packaging, and build options through the `custom.webpack` section in serverless.yml.
3

4
## Capabilities
5

6
### Basic Configuration
7

8
Configure the plugin through the `custom.webpack` section in your serverless.yml file.
9

10
```yaml { .api }
11
custom:
12
  webpack:
13
    webpackConfig: string              # Path to webpack configuration file (default: 'webpack.config.js')
14
    includeModules: boolean | object   # External module inclusion settings (default: false)
15
    packager: 'npm' | 'yarn'          # Package manager selection (default: 'npm')
16
    packagerOptions: object           # Package manager specific options (default: {})
17
    excludeFiles: string              # Glob pattern for file exclusion
18
    excludeRegex: string              # Regex pattern for file exclusion  
19
    keepOutputDirectory: boolean      # Preserve webpack output directory (default: false)
20
    concurrency: number               # Compilation concurrency level (default: os.cpus().length)
21
    config: object                    # Custom configuration object
22
```
23

24
**Usage Examples:**
25

26
```yaml
27
# Basic configuration
28
custom:
29
  webpack:
30
    webpackConfig: './config/webpack.config.js'
31
    includeModules: true
32
    packager: 'yarn'
33

34
# Advanced configuration
35
custom:
36
  webpack:
37
    webpackConfig: './build/webpack.prod.js'
38
    includeModules:
39
      packagePath: '../package.json'
40
      nodeModulesRelativeDir: '../../'
41
      forceExclude:
42
        - 'aws-sdk'
43
      forceInclude:
44
        - 'pg'
45
    packager: 'npm'
46
    packagerOptions:
47
      scripts:
48
        - 'build:custom'
49
    excludeFiles: 'src/**/*.test.js'
50
    concurrency: 4
51
    keepOutputDirectory: true
52
```
53

54
### Webpack Configuration File
55

56
Specify the path to your webpack configuration file.
57

58
```yaml { .api }
59
# String format (legacy support)
60
custom:
61
  webpack: './my-webpack.config.js'
62

63
# Object format (recommended)  
64
custom:
65
  webpack:
66
    webpackConfig: './my-webpack.config.js'
67
```
68

69
The webpack configuration file can export:
70
- Synchronous configuration object
71
- Asynchronous function returning configuration
72
- Promise resolving to configuration
73

74
**Usage Examples:**
75

76
```javascript
77
// Basic webpack config
78
module.exports = {
79
  entry: './handler.js',
80
  target: 'node',
81
  module: {
82
    rules: [
83
      {
84
        test: /\.js$/,
85
        exclude: /node_modules/,
86
        use: 'babel-loader'
87
      }
88
    ]
89
  }
90
};
91

92
// Async webpack config with serverless-webpack lib
93
const slsw = require('serverless-webpack');
94

95
module.exports = async () => {
96
  const accountId = await slsw.lib.serverless.providers.aws.getAccountId();
97
  return {
98
    entry: slsw.lib.entries,
99
    target: 'node',
100
    plugins: [
101
      new webpack.DefinePlugin({
102
        AWS_ACCOUNT_ID: JSON.stringify(accountId)
103
      })
104
    ]
105
  };
106
};
107
```
108

109
### Module Inclusion Configuration
110

111
Configure how external modules are included in the deployment package.
112

113
```yaml { .api }
114
# Boolean format
115
includeModules: boolean
116

117
# Object format for advanced configuration
118
includeModules:
119
  packagePath: string                  # Relative path to package.json (default: './package.json')
120
  nodeModulesRelativeDir: string      # Relative path to node_modules directory
121
  packageLockPath: string             # Path to package-lock.json for NPM 8+ support
122
  forceExclude: string[]              # Modules to force exclude from packaging
123
  forceInclude: string[]              # Modules to force include in packaging
124
```
125

126
**Usage Examples:**
127

128
```yaml
129
# Simple inclusion
130
custom:
131
  webpack:
132
    includeModules: true
133

134
# Monorepo configuration
135
custom:
136
  webpack:
137
    includeModules:
138
      packagePath: '../package.json'
139
      nodeModulesRelativeDir: '../../'
140
      packageLockPath: '../../package-lock.json'
141

142
# Selective module inclusion
143
custom:
144
  webpack:
145
    includeModules:
146
      forceExclude:
147
        - 'aws-sdk'      # Already available in Lambda runtime
148
        - 'dev-only-pkg'
149
      forceInclude:
150
        - 'optional-dep'  # Include optional dependency
151
```
152

153
### Packager Configuration
154

155
Configure the package manager used for installing and managing dependencies.
156

157
```yaml { .api }
158
packager: 'npm' | 'yarn'               # Package manager selection
159

160
packagerOptions:                       # Packager-specific options
161
  scripts: string[]                    # Additional scripts to run after install
162
  noInstall: boolean                   # Skip install step
163
  ignoreLockfile: boolean             # Ignore lock file during install
164
  [customOption: string]: any         # Additional packager-specific options
165
```
166

167
**Usage Examples:**
168

169
```yaml
170
# NPM configuration
171
custom:
172
  webpack:
173
    packager: 'npm'
174
    packagerOptions:
175
      scripts:
176
        - 'rebuild'
177
        - 'prepare:prod'
178

179
# Yarn configuration  
180
custom:
181
  webpack:
182
    packager: 'yarn'
183
    packagerOptions:
184
      ignoreLockfile: false
185
      scripts:
186
        - 'postinstall'
187
```
188

189
### File Exclusion Configuration
190

191
Configure which files should be excluded from the webpack compilation process.
192

193
```yaml { .api }
194
excludeFiles: string                   # Glob pattern for file exclusion
195
excludeRegex: string                  # Regular expression pattern for file exclusion
196
```
197

198
**Usage Examples:**
199

200
```yaml
201
custom:
202
  webpack:
203
    excludeFiles: 'src/**/*.test.js'   # Exclude test files
204
    
205
# Multiple patterns
206
custom:
207
  webpack:
208
    excludeFiles: '{src/**/*.test.js,src/**/*.spec.js,**/*.stories.js}'
209

210
# Regex pattern
211
custom:
212
  webpack:
213
    excludeRegex: '\\.(test|spec)\\.(js|ts)$'
214
```
215

216
### Build Output Configuration
217

218
Configure webpack output behavior and directory management.
219

220
```yaml { .api }
221
keepOutputDirectory: boolean          # Preserve .webpack directory after build (default: false)
222
concurrency: number                   # Number of concurrent webpack compilations (default: os.cpus().length)
223
```
224

225
**Usage Examples:**
226

227
```yaml
228
custom:
229
  webpack:
230
    keepOutputDirectory: true         # Keep .webpack directory for debugging
231
    concurrency: 2                    # Limit concurrent compilations
232
    
233
# Dynamic concurrency via CLI
234
custom:
235
  webpack:
236
    concurrency: ${opt:compile-concurrency, 4}
237
```
238

239
### Legacy Configuration Support
240

241
The plugin maintains backward compatibility with legacy configuration formats.
242

243
```yaml { .api }
244
# Legacy format (still supported)
245
custom:
246
  webpack: 'path/to/webpack.config.js'
247
  webpackIncludeModules: boolean
248
```
249

250
**Migration Example:**
251

252
```yaml
253
# Legacy format
254
custom:
255
  webpack: './webpack.config.js'
256
  webpackIncludeModules: true
257

258
# Modern equivalent
259
custom:
260
  webpack:
261
    webpackConfig: './webpack.config.js'
262
    includeModules: true
263
```
264

265
## Configuration Class
266

267
The plugin uses an internal Configuration class to manage settings.
268

269
```javascript { .api }
270
/**
271
 * Plugin configuration management class
272
 */
273
class Configuration {
274
  /**
275
   * Create configuration from serverless.yml custom.webpack section
276
   * @param custom - The custom.webpack configuration object
277
   */
278
  constructor(custom: any);
279
  
280
  /** Path to webpack configuration file getter */
281
  webpackConfig: string;
282
  
283
  /** Module inclusion configuration getter */
284
  includeModules: boolean | object;
285
  
286
  /** File exclusion glob pattern getter */
287
  excludeFiles: string;
288
  
289
  /** File exclusion regex pattern getter */
290
  excludeRegex: string;
291
  
292
  /** Package manager selection getter */
293
  packager: string;
294
  
295
  /** Package manager options getter */
296
  packagerOptions: object;
297
  
298
  /** Custom configuration object getter */
299
  config: object;
300
  
301
  /** Legacy configuration detection getter */
302
  hasLegacyConfig: boolean;
303
  
304
  /** Output directory preservation flag getter */
305
  keepOutputDirectory: boolean;
306
  
307
  /** Compilation concurrency setting getter */
308
  concurrency: number;
309
  
310
  /** Serialize configuration to JSON */
311
  toJSON(): object;
312
}
313
```
314

315
## Default Configuration Values
316

317
```javascript { .api }
318
// Default configuration applied when values are not specified
319
const DefaultConfig = {
320
  webpackConfig: 'webpack.config.js',
321
  includeModules: false,
322
  packager: 'npm',
323
  packagerOptions: {},
324
  keepOutputDirectory: false,
325
  config: null,
326
  concurrency: require('os').cpus().length
327
};
328
```