{"id":13475799,"url":"https://github.com/mozilla/web-ext","last_synced_at":"2025-05-14T22:05:42.454Z","repository":{"id":37445287,"uuid":"50859563","full_name":"mozilla/web-ext","owner":"mozilla","description":"A command line tool to help build, run, and test web extensions","archived":false,"fork":false,"pushed_at":"2025-05-12T07:50:51.000Z","size":10557,"stargazers_count":2871,"open_issues_count":217,"forks_count":355,"subscribers_count":48,"default_branch":"master","last_synced_at":"2025-05-14T22:05:26.503Z","etag":null,"topics":["add-ons","browser-extension","javascript","webextension","webextensions"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mozilla.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-02-01T18:08:32.000Z","updated_at":"2025-05-14T13:12:33.000Z","dependencies_parsed_at":"2024-04-18T11:27:58.839Z","dependency_job_id":"f92780bb-2148-45a8-8cb7-36158a254220","html_url":"https://github.com/mozilla/web-ext","commit_stats":{"total_commits":2190,"total_committers":100,"mean_commits":21.9,"dds":0.765296803652968,"last_synced_commit":"d655013c9650d24cf28a4d3556154fc9bdf52ea4"},"previous_names":[],"tags_count":86,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Fweb-ext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Fweb-ext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Fweb-ext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Fweb-ext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mozilla","download_url":"https://codeload.github.com/mozilla/web-ext/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254235687,"owners_count":22036962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["add-ons","browser-extension","javascript","webextension","webextensions"],"created_at":"2024-07-31T16:01:23.675Z","updated_at":"2025-05-14T22:05:42.411Z","avatar_url":"https://github.com/mozilla.png","language":"JavaScript","readme":"# Web-ext\n\nThis is a command line tool to help build, run, and test\n[WebExtensions](https://wiki.mozilla.org/WebExtensions).\n\n[![CircleCI](https://circleci.com/gh/mozilla/web-ext.svg?style=svg)](https://circleci.com/gh/mozilla/web-ext)\n[![codecov](https://codecov.io/gh/mozilla/web-ext/branch/master/graph/badge.svg)](https://codecov.io/gh/mozilla/web-ext)\n[![npm version](https://badge.fury.io/js/web-ext.svg)](https://badge.fury.io/js/web-ext)\n\nUltimately, it aims to support browser extensions in a standard, portable,\ncross-platform way. Initially, it will provide a streamlined experience for developing\n[Firefox Extensions](https://developer.mozilla.org/en-US/Add-ons/WebExtensions).\n\n## Documentation\n\n- [Getting started with web-ext][web-ext-user-docs]\n- [Command reference](https://extensionworkshop.com/documentation/develop/web-ext-command-reference/)\n\nHere are the commands you can run. Click on each one for detailed documentation or use `--help` on the command line, such as `web-ext build --help`.\n\n- [`run`](https://extensionworkshop.com/documentation/develop/web-ext-command-reference/#web-ext-run)\n  - Run the extension\n- [`lint`](https://extensionworkshop.com/documentation/develop/web-ext-command-reference/#web-ext-lint)\n  - Validate the extension source\n- [`sign`](https://extensionworkshop.com/documentation/develop/web-ext-command-reference/#web-ext-sign)\n  - Sign the extension so it can be installed in Firefox\n- [`build`](https://extensionworkshop.com/documentation/develop/web-ext-command-reference/#web-ext-build)\n  - Create an extension package from source\n- [`docs`](https://extensionworkshop.com/documentation/develop/web-ext-command-reference/#web-ext-docs)\n  - Open the `web-ext` documentation in a browser\n\n## Installation\n\n### Using npm\n\nFirst, make sure you are running the current\n[LTS](https://github.com/nodejs/LTS)\n(long term support) version of\n[NodeJS](https://nodejs.org/en/).\n\n#### Global command\n\nYou can install this command onto your machine globally with:\n\n    npm install --global web-ext\n\n#### For your project\n\nAlternatively, you can install this command as one of the\n[`devDependencies`](https://docs.npmjs.com/files/package.json#devdependencies)\nof your project. This method can help you control the version of `web-ext`\nas used by your team.\n\n    npm install --save-dev web-ext\n\nNext you can use the `web-ext` command in your project as an\n[npm script](https://docs.npmjs.com/misc/scripts).\nHere is an example where the `--source-dir` argument specifies where to find\nthe source code for your extension.\n\n`package.json`\n\n```json\n\"scripts\": {\n  \"start:firefox\": \"web-ext run --source-dir ./extension-dist/\",\n}\n```\n\nYou can always pass in additional commands to your npm scripts using\nthe `--` suffix. For example, the previous script could specify the Firefox\nversion on the command line with this:\n\n    npm run start:firefox -- --firefox=nightly\n\n### Using Homebrew (unofficial)\n\nThe community maintains a `web-ext` formula.\n\n```sh\nbrew install web-ext\n```\n\n## Installation from source\n\nYou'll need:\n\n- [Node.js](https://nodejs.org/en/) (current [LTS](https://github.com/nodejs/LTS))\n- [npm](https://www.npmjs.com/), 8.0.0 or higher is recommended\n\nOptionally, you may like:\n\n- [nvm](https://github.com/creationix/nvm), which helps manage node versions\n\nIf you had already installed `web-ext` from npm,\nyou may need to uninstall it first:\n\n    npm uninstall --global web-ext\n\nChange into the source and install all dependencies:\n\n    git clone https://github.com/mozilla/web-ext.git\n    cd web-ext\n    npm ci\n\nBuild the command:\n\n    npm run build\n\nLink it to your node installation:\n\n    npm link\n\nYou can now run it from any directory:\n\n    web-ext --help\n\nTo get updates, just pull changes and rebuild the executable. You don't\nneed to relink it.\n\n    cd /path/to/web-ext\n    git pull\n    npm run build\n\n## Using web-ext in NodeJS code\n\n**Note:** web-ext is primarily a command line tool and there is limited support for direct use of its internal API. Backward incompatible changes\nmay be introduced in minor and patch version updates to the web-ext npm package.\n\nAside from [using web-ext on the command line][web-ext-user-docs], you may wish to execute `web-ext` in NodeJS code.\n\nAs of version `7.0.0`, the `web-ext` npm package exports NodeJS native ES modules only. If you are using CommonJS, you will have to use [dynamic imports][dynamic-imports].\n\n### Examples\n\nYou are able to execute command functions without any argument validation. If you want to execute `web-ext run` you would do so like this:\n\n```js\nimport webExt from 'web-ext';\n\nwebExt.cmd\n  .run(\n    {\n      // These are command options derived from their CLI conterpart.\n      // In this example, --source-dir is specified as sourceDir.\n      firefox: '/path/to/Firefox-executable',\n      sourceDir: '/path/to/your/extension/source/',\n    },\n    {\n      // These are non CLI related options for each function.\n      // You need to specify this one so that your NodeJS application\n      // can continue running after web-ext is finished.\n      shouldExitProgram: false,\n    },\n  )\n  .then((extensionRunner) =\u003e {\n    // The command has finished. Each command resolves its\n    // promise with a different value.\n    console.log(extensionRunner);\n    // You can do a few things like:\n    // extensionRunner.reloadAllExtensions();\n    // extensionRunner.exit();\n  });\n```\n\nIf you would like to run an extension on Firefox for Android:\n\n```js\nimport * as adbUtils from \"web-ext/util/adb\";\n\n// Path to adb binary (optional parameter, auto-detected if missing)\nconst adbBin = \"/path/to/adb\";\n// Get an array of device ids (Array\u003cstring\u003e)\nconst deviceIds = await adbUtils.listADBDevices(adbBin);\nconst adbDevice = ...\n// Get an array of Firefox APKs (Array\u003cstring\u003e)\nconst firefoxAPKs = await adbUtils.listADBFirefoxAPKs(\n  deviceId, adbBin\n);\nconst firefoxApk = ...\n\nwebExt.cmd.run({\n  target: 'firefox-android',\n  firefoxApk,\n  adbDevice,\n  sourceDir: ...\n}).then((extensionRunner) =\u003e {...});\n```\n\nIf you would like to control logging, you can access the logger object. Here is an example of turning on verbose logging:\n\n```js\nimport * as webExtLogger from 'web-ext/util/logger';\n\nwebExtLogger.consoleStream.makeVerbose();\nwebExt.cmd.run({ sourceDir: './src' }, { shouldExitProgram: false });\n```\n\nYou can also disable the use of standard input:\n\n```js\nwebExt.cmd.run({ noInput: true }, { shouldExitProgram: false });\n```\n\n`web-ext` is designed for WebExtensions but you can try disabling manifest validation to work with legacy extensions. This is not officially supported.\n\n```js\nwebExt.cmd.run(\n  { sourceDir: './src' },\n  {\n    getValidatedManifest: () =\u003e ({\n      name: 'some-fake-name',\n      version: '1.0.0',\n    }),\n    shouldExitProgram: false,\n  },\n);\n```\n\nYou can also use `webExt.cmd.sign()` to request a signed xpi for a given extension source directory:\n\n```js\nwebExt.cmd.sign({\n  // NOTE: Please set userAgentString to a custom one of your choice.\n  userAgentString: 'YOUR-CUSTOM-USERAGENT',\n  apiKey,\n  apiSecret,\n  amoBaseUrl: 'https://addons.mozilla.org/api/v5/',\n  sourceDir: ...,\n  channel: 'unlisted',\n  ...\n});\n```\n\nYou can also access the internal signing module directly if you need to submit an xpi file without also building it.\n**Note:** submit-addon is internal web-ext module, using the webExt.cmd.sign() is the recommended API method.\n\n```js\nimport { signAddon } from 'web-ext/util/submit-addon';\n\nsignAddon({\n  // NOTE: Please set userAgentString to a custom one of your choice.\n  userAgentString: 'YOUR-CUSTOM-USERAGENT',\n  apiKey,\n  apiSecret,\n  amoBaseUrl: 'https://addons.mozilla.org/api/v5/',\n  id: 'extension-id@example.com',\n  xpiPath: pathToExtension,\n  savedUploadUuidPath: '.amo-upload-uuid',\n  channel: 'unlisted',\n});\n```\n\n## Should I Use It?\n\nYes! The web-ext tool enables you to build and ship extensions for Firefox.\nThis platform stabilized in\n[Firefox 48](https://blog.mozilla.org/addons/2016/04/29/webextensions-in-firefox-48/)\nwhich was released in April of 2016.\n\n## Get Involved\n\nHi! This tool is under active development. To get involved you can watch the repo,\nfile issues, create pull requests, or\n[contact us](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/Contact_us)\nto ask a question.\nRead the [contributing section](CONTRIBUTING.md) for how to develop new features.\n\n## Some Questions and Answers\n\n### Why do we need a command line tool?\n\nThis is a great question and one that we will ask ourselves for each new web-ext\nfeature. Most WebExtension functionality is baked into the browsers\nthemselves but a complimentary command line tool will still be helpful.\nHere is a partial list of examples:\n\n- File watching.\n  - When you edit a file, you may need to trigger certain commands (tests,\n    installation, etc).\n- Integrating with services.\n  - Mozilla offers some useful services such as\n    [linting](https://github.com/mozilla/addons-linter) and\n    [signing](https://addons-server.readthedocs.io/en/latest/topics/api/v4_frozen/signing.html)\n    extensions.\n\n[web-ext-user-docs]: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Getting_started_with_web-ext\n[dynamic-imports]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#dynamic_imports\n","funding_links":[],"categories":["JavaScript","browser-extension","Tools"],"sub_categories":["Development"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozilla%2Fweb-ext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmozilla%2Fweb-ext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozilla%2Fweb-ext/lists"}