0
# Build System
1

2
Extension packaging functionality for creating distributable .zip files with customizable file filtering, localization support, and watch mode for development.
3

4
## Capabilities
5

6
### Build Function
7

8
Creates a packaged extension (.zip file) from source directory with comprehensive file filtering and validation.
9

10
```javascript { .api }
11
/**
12
 * Build an extension package from source
13
 * @param params - Build configuration parameters
14
 * @param options - Optional build dependencies and settings
15
 * @returns Promise resolving to build result with extension path
16
 */
17
function build(params: BuildParams, options?: BuildOptions): Promise<BuildResult>;
18

19
interface BuildParams {
20
  /** Source directory containing the extension */
21
  sourceDir: string;
22
  /** Directory where the built extension will be saved */
23
  artifactsDir: string;
24
  /** Watch for file changes and rebuild automatically */
25
  asNeeded?: boolean;
26
  /** Custom filename for the extension package (supports template variables) */
27
  filename?: string;
28
  /** Overwrite existing extension package if it exists */
29
  overwriteDest?: boolean;
30
  /** Array of glob patterns for files to ignore during build */
31
  ignoreFiles?: string[];
32
  /** Enable verbose logging output */
33
  verbose?: boolean;
34
}
35

36
interface BuildOptions {
37
  /** Custom manifest validator function */
38
  manifestData?: object;
39
  /** Custom package creator function */
40
  packageCreator?: Function;
41
  /** Custom source watcher for asNeeded mode */
42
  sourceWatcher?: any;
43
  /** Should exit process on completion */
44
  shouldExitProgram?: boolean;
45
}
46

47
interface BuildResult {
48
  /** Absolute path to the created extension package */
49
  extensionPath: string;
50
}
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
import { cmd } from "web-ext";
57

58
// Basic build
59
const result = await cmd.build({
60
  sourceDir: './my-extension',
61
  artifactsDir: './web-ext-artifacts'
62
});
63

64
console.log('Extension built at:', result.extensionPath);
65

66
// Build with custom filename and file filtering
67
await cmd.build({
68
  sourceDir: './src',
69
  artifactsDir: './dist',
70
  filename: 'my-extension-v{version}.zip',
71
  overwriteDest: true,
72
  ignoreFiles: ['*.log', 'node_modules/**', 'src/**/*.test.js']
73
});
74

75
// Build with watch mode for development
76
await cmd.build({
77
  sourceDir: './extension',
78
  artifactsDir: './build',
79
  asNeeded: true,  // Rebuilds on file changes
80
  verbose: true
81
});
82
```
83

84
### File Name Utilities
85

86
Utilities for generating safe filenames and handling localized extension names.
87

88
```javascript { .api }
89
/**
90
 * Convert a string to a safe filename by replacing invalid characters
91
 * @param name - Original filename string
92
 * @returns Safe filename with invalid characters replaced by underscores
93
 */
94
function safeFileName(name: string): string;
95

96
/**
97
 * Get the localized name from _locales/messages.json if available
98
 * @param options - Configuration for localized name extraction
99
 * @returns Promise resolving to the localized extension name
100
 */
101
function getDefaultLocalizedName(options: LocalizedNameOptions): Promise<string>;
102

103
interface LocalizedNameOptions {
104
  /** Path to the messages.json file */
105
  messageFile: string;
106
  /** Parsed manifest.json data */
107
  manifestData: object;
108
}
109
```
110

111
**Usage Examples:**
112

113
```javascript
114
import { safeFileName, getDefaultLocalizedName } from "web-ext/src/cmd/build.js";
115

116
// Generate safe filename
117
const safeName = safeFileName("My Awesome Extension!");
118
// Result: "my_awesome_extension_"
119

120
// Get localized name
121
const localizedName = await getDefaultLocalizedName({
122
  messageFile: './extension/_locales/en/messages.json',
123
  manifestData: { name: "__MSG_extensionName__" }
124
});
125
```
126

127
### Package Creation
128

129
Advanced package creation with custom file handling and compression options.
130

131
```javascript { .api }
132
interface PackageCreator {
133
  /**
134
   * Create extension package from validated manifest and source files
135
   * @param params - Package creation parameters
136
   * @returns Promise resolving to package creation result
137
   */
138
  (params: PackageCreatorParams): Promise<PackageResult>;
139
}
140

141
interface PackageCreatorParams {
142
  /** Validated manifest data */
143
  manifestData: object;
144
  /** Source directory path */
145
  sourceDir: string;
146
  /** File filter instance for determining included files */
147
  fileFilter: FileFilter;
148
  /** Destination directory for package */
149
  artifactsDir: string;
150
  /** Show verbose output */
151
  verbose: boolean;
152
  /** Overwrite existing files */
153
  overwriteDest: boolean;
154
  /** Custom filename template */
155
  filename?: string;
156
}
157

158
interface PackageResult {
159
  /** Path to created package file */
160
  extensionPath: string;
161
}
162
```
163

164
### File Filtering
165

166
Built-in file filtering system with default ignore patterns and custom rule support.
167

168
```javascript { .api }
169
interface FileFilter {
170
  /** Check if a file should be included in the package */
171
  wantFile(filePath: string): boolean;
172
  /** Add additional patterns to ignore list */
173
  addToIgnoreList(files: string[]): void;
174
  /** Resolve relative paths against source directory */
175
  resolveWithSourceDir(file: string): string;
176
}
177
```
178

179
**Default Ignored Patterns:**
180
- `**/*.xpi` - Firefox extension packages
181
- `**/*.zip` - Zip archives  
182
- `**/.*` - Hidden files and directories
183
- `**/node_modules` - Node.js dependencies
184

185
### Watch Mode
186

187
Automatic rebuilding when source files change during development.
188

189
```javascript { .api }
190
interface SourceWatcher {
191
  /** Watch source directory for changes and trigger rebuilds */
192
  watchForChanges(params: WatchParams): Promise<void>;
193
}
194

195
interface WatchParams {
196
  /** Source directory to watch */
197
  sourceDir: string;
198
  /** Callback function called on file changes */
199
  onChange: () => void;
200
  /** Should exit process on errors */
201
  shouldExitProgram: boolean;
202
}
203
```
204

205
**Usage Example:**
206

207
```javascript
208
// Watch mode is automatically enabled with asNeeded: true
209
await cmd.build({
210
  sourceDir: './extension',
211
  artifactsDir: './build',
212
  asNeeded: true  // Enables automatic rebuilding on file changes
213
});
214
```
215

216
## Constants
217

218
```javascript { .api }
219
/** Default filename template for extension packages */
220
const DEFAULT_FILENAME_TEMPLATE: string = "{name}-{version}.zip";
221
```
222

223
## Error Handling
224

225
The build system handles various error conditions:
226

227
- **Missing manifest.json**: Throws `UsageError` if manifest.json is not found
228
- **Invalid manifest**: Validates required fields (name, version) and throws detailed errors
229
- **File access errors**: Handles permission issues and missing directories
230
- **Package creation failures**: Reports compression and file system errors
231
- **Localization errors**: Validates _locales/messages.json format and content