0
# Webpack CLI
1

2
Webpack CLI is the official command-line interface for webpack, providing comprehensive tooling for configuration, building, serving, and analyzing webpack projects. It offers both CLI commands and a programmatic API for custom webpack integrations.
3

4
## Package Information
5

6
- **Package Name**: webpack-cli
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install webpack-cli`
10
- **Node.js Support**: >=18.12.0
11

12
## Core Imports
13

14
```typescript
15
import CLI from "webpack-cli";
16
import { type IWebpackCLI } from "webpack-cli";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const CLI = require("webpack-cli");
23
```
24

25
## Basic Usage
26

27
### CLI Usage
28

29
```bash
30
# Build with default configuration
31
npx webpack-cli
32

33
# Build with custom config
34
npx webpack-cli --config webpack.prod.js
35

36
# Watch mode
37
npx webpack-cli --watch
38

39
# Development server
40
npx webpack-cli serve
41

42
# Get system info
43
npx webpack-cli info
44
```
45

46
### Programmatic Usage
47

48
```typescript
49
import CLI from "webpack-cli";
50

51
// Initialize CLI instance
52
const cli = CLI;
53

54
// Run CLI programmatically
55
await cli.run(["--mode", "production", "--entry", "./src/index.js"]);
56
```
57

58
## Architecture
59

60
Webpack CLI is built around several key components:
61

62
- **CLI Commands**: Built-in commands (build, serve, info, configtest) with extensive option parsing
63
- **WebpackCLI Class**: Core programmatic API implementing the IWebpackCLI interface
64
- **Plugin System**: CLIPlugin for webpack integration and progress reporting
65
- **Configuration Management**: Automatic config loading, validation, and merging
66
- **Package Integration**: Support for webpack-dev-server, bundle analyzer, and package managers
67

68
## Capabilities
69

70
### CLI Interface
71

72
Command-line interface with built-in commands and extensive webpack configuration options. Supports build, serve, info, and configuration testing commands.
73

74
```bash { .api }
75
# Core commands
76
webpack-cli [options]                    # Build (default command)
77
webpack-cli serve [options]              # Development server
78
webpack-cli info [options]               # System information
79
webpack-cli configtest [config-path]     # Test configuration
80
webpack-cli help [command]               # Help information
81
```
82

83
[CLI Interface](./cli-interface.md)
84

85
### Programmatic API
86

87
WebpackCLI class providing complete programmatic access to CLI functionality. Includes configuration loading, compilation, and webpack integration.
88

89
```typescript { .api }
90
interface IWebpackCLI {
91
  // Properties
92
  colors: WebpackCLIColors;
93
  logger: WebpackCLILogger;
94
  isColorSupportChanged: boolean | undefined;
95
  webpack: typeof webpack;
96
  builtInOptionsCache: WebpackCLIBuiltInOption[] | undefined;
97
  program: WebpackCLICommand;
98

99
  // Core execution
100
  run(args: string[], parseOptions?: ParseOptions): Promise<void>;
101
  runWebpack(options: WebpackRunOptions, isWatchCommand: boolean): Promise<void>;
102
  
103
  // Configuration management
104
  loadConfig(options: Partial<WebpackDevServerOptions>): Promise<WebpackCLIConfig>;
105
  buildConfig(config: WebpackCLIConfig, options: WebpackDevServerOptions): Promise<WebpackCLIConfig>;
106
  
107
  // Webpack integration
108
  loadWebpack(handleError?: boolean): Promise<typeof webpack>;
109
  createCompiler(
110
    options: Partial<WebpackDevServerOptions>, 
111
    callback?: Callback<[Error | undefined, Stats | MultiStats | undefined]>
112
  ): Promise<WebpackCompiler>;
113

114
  // Package management
115
  checkPackageExists(packageName: string): boolean;
116
  getAvailablePackageManagers(): PackageManager[];
117
  getDefaultPackageManager(): PackageManager | undefined;
118
  doInstall(packageName: string, options?: PackageInstallOptions): Promise<string>;
119

120
  // File and module operations
121
  loadJSONFile<T = unknown>(path: string, handleError: boolean): T;
122
  tryRequireThenImport<T = unknown>(
123
    module: string, 
124
    handleError: boolean,
125
    moduleType?: "unknown" | "commonjs" | "esm"
126
  ): Promise<T>;
127

128
  // Command and option management
129
  makeCommand(
130
    commandOptions: WebpackCLIOptions,
131
    options: WebpackCLICommandOptions,
132
    action: CommandAction
133
  ): Promise<WebpackCLICommand | undefined>;
134
  makeOption(command: WebpackCLICommand, option: WebpackCLIBuiltInOption): void;
135
  getBuiltInOptions(): WebpackCLIBuiltInOption[];
136

137
  // Info command integration
138
  getInfoOptions(): WebpackCLIBuiltInOption[];
139
  getInfoOutput(options: { output: string; additionalPackage: string[] }): Promise<string>;
140

141
  // Utility methods
142
  isMultipleCompiler(compiler: WebpackCompiler): compiler is MultiCompiler;
143
  isPromise<T>(value: Promise<T>): value is Promise<T>;
144
  isFunction(value: unknown): value is CallableFunction;
145
  isValidationError(error: Error): error is WebpackError;
146
  toKebabCase(str: string): string;
147
  capitalizeFirstLetter(str: string): string;
148
  getLogger(): WebpackCLILogger;
149
  createColors(useColors?: boolean): WebpackCLIColors;
150
  needWatchStdin(compiler: Compiler | MultiCompiler): boolean;
151
}
152
```
153

154
[Programmatic API](./programmatic-api.md)
155

156
### Plugin System
157

158
CLIPlugin for webpack integration providing progress reporting, bundle analysis, and CLI-specific webpack functionality.
159

160
```typescript { .api }
161
class CLIPlugin {
162
  constructor(options: CLIPluginOptions);
163
  apply(compiler: Compiler): void;
164
}
165

166
interface CLIPluginOptions {
167
  helpfulOutput: boolean;
168
  progress?: boolean | "profile";
169
  analyze?: boolean;
170
  hot?: boolean | "only";
171
  prefetch?: string;
172
  isMultiCompiler?: boolean;
173
  configPath?: string[];
174
}
175
```
176

177
[Plugin System](./plugin-system.md)
178

179
## Types
180

181
```typescript { .api }
182
interface WebpackCLIConfig {
183
  options: WebpackConfiguration | WebpackConfiguration[];
184
  path: WeakMap<object, string[]>;
185
}
186

187
interface WebpackCLILogger {
188
  error: LogHandler;
189
  warn: LogHandler;
190
  info: LogHandler;
191
  success: LogHandler;
192
  log: LogHandler;
193
  raw: LogHandler;
194
}
195

196
interface WebpackCLIColors extends Colorette {
197
  isColorSupported: boolean;
198
}
199

200
interface WebpackCLICommand extends Command {
201
  pkg: string | undefined;
202
  forHelp: boolean | undefined;
203
  _args: WebpackCLICommandOption[];
204
}
205

206
interface WebpackCLICommandOption extends CommanderOption {
207
  helpLevel?: "minimum" | "verbose";
208
}
209

210
interface WebpackCLIBuiltInOption extends WebpackCLIBuiltInFlag {
211
  hidden?: boolean;
212
  group?: "core";
213
}
214

215
interface PackageInstallOptions {
216
  preMessage?: () => void;
217
}
218

219
type PackageManager = "pnpm" | "yarn" | "npm";
220
type WebpackCompiler = Compiler | MultiCompiler;
221
type LogHandler = (value: any) => void;
222
type StringFormatter = (value: string) => string;
223
type CommandAction = (...args: any[]) => Promise<void> | void;
224
type BasicPrimitive = string | boolean | number;
225
```