Quickstart

Get up and running with the Web Extension SDK.
Before you begin
Before you begin building your extension, make sure to download the libraries you'll need and configure the manifest.json file.
Downloading the libraries
The Web Extension (WebExt) library comes in two parts, which you'll need to include in the extension's background page:
ewe-api.js, which you'll include in your extension's background page
ewe-content.js, which must be loaded as a content script
Make sure you've downloaded the latest builds of both.
Configuring the manifest file
Your extension's manifest.json file requires one of the following configurations; choose between the Manifest V2 and Manifest V3-compatible code, depending on your project:
Manifest V2
Manifest V3
{
  "manifest_version": 2,
  "background": {
    "scripts": [
      "ewe-api.js"
    ]
  },
  "content_scripts": [
    {
      "all_frames": true,
      "js": [
        "ewe-content.js"
      ],
      "match_about_blank": true,
      "matches": [
        "http://*/*",
        "https://*/*"
      ],
      "run_at": "document_start"
    }
  ],
  "permissions": [
    "webNavigation",
    "webRequest",
    "webRequestBlocking",
    "unlimitedStorage",
    "<all_urls>"
  ]
}
{
  "manifest_version": 3,
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [
    {
      "all_frames": true,
      "js": [
        "ewe-content.js"
      ],
      "match_about_blank": true,
      "matches": [
        "http://*/*",
        "https://*/*"
      ],
      "run_at": "document_start"
    }
  ],
  "permissions": [
    "declarativeNetRequestWithHostAccess",
    "declarativeNetRequestFeedback",
    "scripting",
    "storage",
    "tabs",
    "webNavigation",
    "webRequest",
    "unlimitedStorage"
  ],
  "host_permissions": [
    "<all_urls>"
  ],
  "declarative_net_request": <output from "subs-generate" script>
}
For more on the permissions in the extension manifest, read Required permissions.
Quick Start
For installation, make sure you have Node 16.10.0 or higher on your system.
Installing dependencies and build the libraries
1. Now that you've downloaded the libraries and configured the manifest.json file, run the following command to update and install the dependencies.
npm install
2. Next, run the following command to build the libraries:
npm run build
3. To lint your code, run the following command:
npm run lint
4. Last, to start the extension build, run the following command.
npm start
Blocking ads
With the libraries and dependencies installed, you're now ready to start blocking ads.
Access the API in your own background scripts through the global EWE object. Call EWE.start() to start blocking ads.
Testing your extension
Now that you've got an extension up and running, be sure to test it to ensure it's functioning as expected.
Serving test pages
Whether you manually load the test extension or use the test runner, the test suite requires locally served test pages. Run them with the following command.
npm run test-server
Using the test extension
The test extension is built on both the /dist/test-mv2 and /dist/test-mv3 folders. You can load both folders as unpacked extensions under chrome://extensions in Chromium-based browsers, and under about:debugging in Firefox.
Once you've loaded the extension, the test suite opens in a new tab. To test the API manually through the global EWE object, you can inspect your extension's background page.
Keep the following in mind when testing your extension:
test-mv2 contains a Manifest Version 2 extension, and test-mv3 contains a Manifest Version 3 extension.
For popup tests, disable your browser's built-in popup blocking on localhost.
Test options
The timeout option overrides the per-test timeout in milliseconds.
The grep uses a regular expression to filter the tests to be run.
Using the test runner
Run the following command to enable the test runner.
npm test -- {v2|v3} {chromium|firefox|edge} [version|channel] [options]
Testing the bundle
Run the following command to make sure users can import and re-bundle your code.
npm run test-bundle
For more information on testing, view the WebExt SDK Testing documentation.
Going further
With your build running, you may want to consider other features available for your extension.
Module bundlers
Because ewe-api.js runs as a Universal Module Definition (UMD) module, you can use it with module bundlers.
If you use a module bundler, omit ewe-api.js from your manifest.json file. As a result, your build won't contain a global EWE object.
Review the following snippets to see the ewe-api.js as both a CommonJS and ESM module.
CommonJS
const EWE = require("./ewe-api.js");
EWE.start();
ESM
import * as EWE from "./ewe-api.js";
EWE.start();
Supporting snippet Filters
To enable support for snippet filters, download the snippets library and make it available to the EWE object with the following command:
let response = await fetch("snippets.js");
let code = await response.text();
EWE.snippets.setLibrary(code);
For more on snippets, view the Snippets documentation.
Incorporating machine learning models
You'll find a models folder included with the library bundles you downloaded. To support machine learning enabled snippets, make sure to include the models folder and its contents in your extension bundle. Include the folder in the same directory as ewe-api.js.
Machine learning enabled snippets are optional, though without them, your extension cannot make use of eyeo's machine learning models.
Web Extension SDK - Previous
Getting Started
Required permissions
Last modified 1mo ago