Build System

/**
 * Build an extension package from source
 * @param params - Build configuration parameters
 * @param options - Optional build dependencies and settings
 * @returns Promise resolving to build result with extension path
 */
function build(params: BuildParams, options?: BuildOptions): Promise<BuildResult>;

interface BuildParams {
  /** Source directory containing the extension */
  sourceDir: string;
  /** Directory where the built extension will be saved */
  artifactsDir: string;
  /** Watch for file changes and rebuild automatically */
  asNeeded?: boolean;
  /** Custom filename for the extension package (supports template variables) */
  filename?: string;
  /** Overwrite existing extension package if it exists */
  overwriteDest?: boolean;
  /** Array of glob patterns for files to ignore during build */
  ignoreFiles?: string[];
  /** Enable verbose logging output */
  verbose?: boolean;
}

interface BuildOptions {
  /** Custom manifest validator function */
  manifestData?: object;
  /** Custom package creator function */
  packageCreator?: Function;
  /** Custom source watcher for asNeeded mode */
  sourceWatcher?: any;
  /** Should exit process on completion */
  shouldExitProgram?: boolean;
}

interface BuildResult {
  /** Absolute path to the created extension package */
  extensionPath: string;
}

import { cmd } from "web-ext";

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

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

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

// Build with watch mode for development
await cmd.build({
  sourceDir: './extension',
  artifactsDir: './build',
  asNeeded: true,  // Rebuilds on file changes
  verbose: true
});

/**
 * Convert a string to a safe filename by replacing invalid characters
 * @param name - Original filename string
 * @returns Safe filename with invalid characters replaced by underscores
 */
function safeFileName(name: string): string;

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

interface LocalizedNameOptions {
  /** Path to the messages.json file */
  messageFile: string;
  /** Parsed manifest.json data */
  manifestData: object;
}

import { safeFileName, getDefaultLocalizedName } from "web-ext/src/cmd/build.js";

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

// Get localized name
const localizedName = await getDefaultLocalizedName({
  messageFile: './extension/_locales/en/messages.json',
  manifestData: { name: "__MSG_extensionName__" }
});

interface PackageCreator {
  /**
   * Create extension package from validated manifest and source files
   * @param params - Package creation parameters
   * @returns Promise resolving to package creation result
   */
  (params: PackageCreatorParams): Promise<PackageResult>;
}

interface PackageCreatorParams {
  /** Validated manifest data */
  manifestData: object;
  /** Source directory path */
  sourceDir: string;
  /** File filter instance for determining included files */
  fileFilter: FileFilter;
  /** Destination directory for package */
  artifactsDir: string;
  /** Show verbose output */
  verbose: boolean;
  /** Overwrite existing files */
  overwriteDest: boolean;
  /** Custom filename template */
  filename?: string;
}

interface PackageResult {
  /** Path to created package file */
  extensionPath: string;
}

interface FileFilter {
  /** Check if a file should be included in the package */
  wantFile(filePath: string): boolean;
  /** Add additional patterns to ignore list */
  addToIgnoreList(files: string[]): void;
  /** Resolve relative paths against source directory */
  resolveWithSourceDir(file: string): string;
}

interface SourceWatcher {
  /** Watch source directory for changes and trigger rebuilds */
  watchForChanges(params: WatchParams): Promise<void>;
}

interface WatchParams {
  /** Source directory to watch */
  sourceDir: string;
  /** Callback function called on file changes */
  onChange: () => void;
  /** Should exit process on errors */
  shouldExitProgram: boolean;
}

// Watch mode is automatically enabled with asNeeded: true
await cmd.build({
  sourceDir: './extension',
  artifactsDir: './build',
  asNeeded: true  // Enables automatic rebuilding on file changes
});

/** Default filename template for extension packages */
const DEFAULT_FILENAME_TEMPLATE: string = "{name}-{version}.zip";