0
# web-ext
1

2
web-ext is a command line tool to help build, run, and test web extensions. It provides a comprehensive development workflow for WebExtensions across different browsers, with primary focus on Firefox extensions. The tool offers essential development commands, cross-browser support, automatic reloading during development, and streamlined publishing workflows.
3

4
## Package Information
5

6
- **Package Name**: web-ext
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Modules)
9
- **Installation**: `npm install web-ext`
10
- **Requirements**: Node.js >=18.0.0, npm >=8.0.0
11

12
## Core Imports
13

14
```javascript
15
import webExt from "web-ext";
16
import { main, cmd } from "web-ext";
17
```
18

19
For CommonJS (legacy, not recommended):
20

21
```javascript
22
const webExt = require("web-ext");
23
const { main, cmd } = webExt;
24
```
25

26
### Utility Imports
27

28
```javascript
29
import { ADBUtils, listADBDevices } from "web-ext/util/adb";
30
import { createLogger, consoleStream } from "web-ext/util/logger";
31
import { signAddon, Client } from "web-ext/util/submit-addon";
32
```
33

34
## Basic Usage
35

36
### CLI Usage
37

38
```bash
39
# Build an extension
40
web-ext build --source-dir=./my-extension
41

42
# Run extension in Firefox
43
web-ext run --source-dir=./my-extension
44

45
# Lint extension
46
web-ext lint --source-dir=./my-extension
47

48
# Sign extension for Firefox
49
web-ext sign --source-dir=./my-extension --api-key=... --api-secret=...
50
```
51

52
### Programmatic Usage
53

54
```javascript
55
import webExt from "web-ext";
56

57
// Run the CLI programmatically
58
await webExt.main('/path/to/package');
59

60
// Access individual commands
61
await webExt.cmd.build({
62
  sourceDir: './my-extension',
63
  artifactsDir: './web-ext-artifacts'
64
});
65

66
await webExt.cmd.run({
67
  sourceDir: './my-extension',
68
  target: ['firefox-desktop']
69
});
70
```
71

72
## Architecture
73

74
web-ext is structured around several key components:
75

76
- **CLI Interface**: Command-line program with yargs-based argument parsing and configuration
77
- **Command System**: Modular command implementations (build, run, lint, sign, docs, dump-config)
78
- **Extension Runners**: Browser-specific runners for Firefox desktop/mobile and Chromium browsers
79
- **Utility Libraries**: Specialized modules for ADB integration, logging, AMO submission, and file handling
80
- **Development Tools**: File watching, hot reloading, manifest validation, and desktop notifications
81

82
## Capabilities
83

84
### Main API
85

86
Core programmatic interface providing access to CLI functionality and individual commands.
87

88
```javascript { .api }
89
interface WebExt {
90
  main: (absolutePackageDir: string, options?: MainOptions) => Promise<void>;
91
  cmd: {
92
    build: (params: BuildParams, options?: BuildOptions) => Promise<BuildResult>;
93
    run: (params: RunParams, options?: RunOptions) => Promise<void>;
94
    lint: (params: LintParams, options?: LintOptions) => Promise<void>;
95
    sign: (params: SignParams, options?: SignOptions) => Promise<SignResult>;
96
    docs: (params: DocsParams, options?: DocsOptions) => Promise<void>;
97
    dumpConfig: (params: DumpConfigParams, options?: DumpConfigOptions) => Promise<void>;
98
  };
99
}
100
```
101

102
[Main API](./main-api.md)
103

104
### Build System
105

106
Extension packaging functionality for creating distributable .zip files with customizable file filtering and watch mode support.
107

108
```javascript { .api }
109
function build(params: BuildParams, options?: BuildOptions): Promise<BuildResult>;
110

111
interface BuildParams {
112
  sourceDir: string;
113
  artifactsDir: string;
114
  asNeeded?: boolean;
115
  filename?: string;
116
  overwriteDest?: boolean;
117
  ignoreFiles?: string[];
118
}
119
```
120

121
[Build System](./build-system.md)
122

123
### Extension Runners
124

125
Browser automation for running extensions in development mode with support for Firefox desktop, Firefox Android, and Chromium browsers.
126

127
```javascript { .api }
128
function run(params: RunParams, options?: RunOptions): Promise<void>;
129

130
interface RunParams {
131
  sourceDir: string;
132
  artifactsDir: string;
133
  target?: string[];
134
  firefox?: string;
135
  firefoxProfile?: string;
136
  chromiumBinary?: string;
137
  reload?: boolean;
138
  startUrl?: string[];
139
  // ... many more options
140
}
141
```
142

143
[Extension Runners](./extension-runners.md)
144

145
### Linting System
146

147
Extension validation using Mozilla's addons-linter with configurable output formats and validation rules.
148

149
```javascript { .api }
150
function lint(params: LintParams, options?: LintOptions): Promise<void>;
151

152
interface LintParams {
153
  sourceDir: string;
154
  artifactsDir: string;
155
  output?: 'text' | 'json';
156
  metadata?: boolean;
157
  warningsAsErrors?: boolean;
158
  privileged?: boolean;
159
  selfHosted?: boolean;
160
}
161
```
162

163
[Linting System](./linting-system.md)
164

165
### Signing and Publishing
166

167
AMO (addons.mozilla.org) integration for automated extension signing and publishing with JWT authentication.
168

169
```javascript { .api }
170
function sign(params: SignParams, options?: SignOptions): Promise<SignResult>;
171

172
interface SignParams {
173
  sourceDir: string;
174
  artifactsDir: string;
175
  apiKey: string;
176
  apiSecret: string;
177
  channel: 'listed' | 'unlisted';
178
  amoBaseUrl?: string;
179
  timeout?: number;
180
  approvalTimeout?: number;
181
}
182
```
183

184
[Signing and Publishing](./signing-publishing.md)
185

186
### Android Development
187

188
ADB integration for developing and testing extensions on Firefox for Android devices.
189

190
```javascript { .api }
191
class ADBUtils {
192
  constructor(params: ADBParams);
193
  discoverDevices(): Promise<string[]>;
194
  runShellCommand(deviceId: string, cmd: string): Promise<string>;
195
  pushFile(deviceId: string, localPath: string, devicePath: string): Promise<void>;
196
  startFirefoxAPK(deviceId: string, apk: string, apkComponent?: string, deviceProfileDir?: string): Promise<void>;
197
}
198

199
function listADBDevices(adbBin?: string): Promise<string[]>;
200
function listADBFirefoxAPKs(deviceId: string, adbBin?: string): Promise<string[]>;
201
```
202

203
[Android Development](./android-development.md)
204

205
### Logging System
206

207
Configurable logging infrastructure with console output, verbose modes, and log capture capabilities.
208

209
```javascript { .api }
210
function createLogger(moduleURL: string, options?: LoggerOptions): Logger;
211

212
class ConsoleStream {
213
  constructor(options: { verbose?: boolean });
214
  makeVerbose(): void;
215
  write(jsonString: string, options?: WriteOptions): void;
216
  startCapturing(): void;
217
  stopCapturing(): void;
218
  flushCapturedLogs(options?: FlushOptions): void;
219
}
220
```
221

222
[Logging System](./logging-system.md)
223

224
## Types
225

226
```javascript { .api }
227
interface MainOptions {
228
  getVersion?: (absolutePackageDir: string) => Promise<string>;
229
  commands?: CommandsObject;
230
  argv?: string[];
231
  runOptions?: RunOptions;
232
}
233

234
interface CommandsObject {
235
  build: (params: BuildParams, options?: BuildOptions) => Promise<BuildResult>;
236
  run: (params: RunParams, options?: RunOptions) => Promise<void>;
237
  lint: (params: LintParams, options?: LintOptions) => Promise<void>;
238
  sign: (params: SignParams, options?: SignOptions) => Promise<SignResult>;
239
  docs: (params: DocsParams, options?: DocsOptions) => Promise<void>;
240
  dumpConfig: (params: DumpConfigParams, options?: DumpConfigOptions) => Promise<void>;
241
}
242

243
interface BuildResult {
244
  extensionPath: string;
245
}
246

247
interface SignResult {
248
  success: boolean;
249
  id?: string;
250
  downloadedFiles?: string[];
251
}
252
```