tessl/npm-web-ext

A command line tool to help build, run, and test web extensions

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

web-ext

Name: tessl/npm-web-ext
Author: tessl

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.

Package Information

Package Name: web-ext
Package Type: npm
Language: JavaScript (ES Modules)
Installation: npm install web-ext
Requirements: Node.js >=18.0.0, npm >=8.0.0

Core Imports

import webExt from "web-ext";
import { main, cmd } from "web-ext";

For CommonJS (legacy, not recommended):

const webExt = require("web-ext");
const { main, cmd } = webExt;

Utility Imports

import { ADBUtils, listADBDevices } from "web-ext/util/adb";
import { createLogger, consoleStream } from "web-ext/util/logger";
import { signAddon, Client } from "web-ext/util/submit-addon";

Basic Usage

CLI Usage

# Build an extension
web-ext build --source-dir=./my-extension

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

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

# Sign extension for Firefox
web-ext sign --source-dir=./my-extension --api-key=... --api-secret=...

Programmatic Usage

import webExt from "web-ext";

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

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

await webExt.cmd.run({
  sourceDir: './my-extension',
  target: ['firefox-desktop']
});

Architecture

web-ext is structured around several key components:

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

Capabilities

Main API

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

interface WebExt {
  main: (absolutePackageDir: string, options?: MainOptions) => Promise<void>;
  cmd: {
    build: (params: BuildParams, options?: BuildOptions) => Promise<BuildResult>;
    run: (params: RunParams, options?: RunOptions) => Promise<void>;
    lint: (params: LintParams, options?: LintOptions) => Promise<void>;
    sign: (params: SignParams, options?: SignOptions) => Promise<SignResult>;
    docs: (params: DocsParams, options?: DocsOptions) => Promise<void>;
    dumpConfig: (params: DumpConfigParams, options?: DumpConfigOptions) => Promise<void>;
  };
}

Main API

Build System

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

function build(params: BuildParams, options?: BuildOptions): Promise<BuildResult>;

interface BuildParams {
  sourceDir: string;
  artifactsDir: string;
  asNeeded?: boolean;
  filename?: string;
  overwriteDest?: boolean;
  ignoreFiles?: string[];
}

Build System

Extension Runners

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

function run(params: RunParams, options?: RunOptions): Promise<void>;

interface RunParams {
  sourceDir: string;
  artifactsDir: string;
  target?: string[];
  firefox?: string;
  firefoxProfile?: string;
  chromiumBinary?: string;
  reload?: boolean;
  startUrl?: string[];
  // ... many more options
}

Extension Runners

Linting System

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

function lint(params: LintParams, options?: LintOptions): Promise<void>;

interface LintParams {
  sourceDir: string;
  artifactsDir: string;
  output?: 'text' | 'json';
  metadata?: boolean;
  warningsAsErrors?: boolean;
  privileged?: boolean;
  selfHosted?: boolean;
}

Linting System

Signing and Publishing

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

function sign(params: SignParams, options?: SignOptions): Promise<SignResult>;

interface SignParams {
  sourceDir: string;
  artifactsDir: string;
  apiKey: string;
  apiSecret: string;
  channel: 'listed' | 'unlisted';
  amoBaseUrl?: string;
  timeout?: number;
  approvalTimeout?: number;
}

Signing and Publishing

Android Development

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

class ADBUtils {
  constructor(params: ADBParams);
  discoverDevices(): Promise<string[]>;
  runShellCommand(deviceId: string, cmd: string): Promise<string>;
  pushFile(deviceId: string, localPath: string, devicePath: string): Promise<void>;
  startFirefoxAPK(deviceId: string, apk: string, apkComponent?: string, deviceProfileDir?: string): Promise<void>;
}

function listADBDevices(adbBin?: string): Promise<string[]>;
function listADBFirefoxAPKs(deviceId: string, adbBin?: string): Promise<string[]>;

Android Development

Logging System

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

function createLogger(moduleURL: string, options?: LoggerOptions): Logger;

class ConsoleStream {
  constructor(options: { verbose?: boolean });
  makeVerbose(): void;
  write(jsonString: string, options?: WriteOptions): void;
  startCapturing(): void;
  stopCapturing(): void;
  flushCapturedLogs(options?: FlushOptions): void;
}

Logging System

Types

interface MainOptions {
  getVersion?: (absolutePackageDir: string) => Promise<string>;
  commands?: CommandsObject;
  argv?: string[];
  runOptions?: RunOptions;
}

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

interface BuildResult {
  extensionPath: string;
}

interface SignResult {
  success: boolean;
  id?: string;
  downloadedFiles?: string[];
}