Quickstart
Get up and running with the Web Extension SDK.
Before you begin building your extension, make sure to download the libraries you'll need and configure the
manifest.json
file.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 pageewe-content.js
, which must be loaded as a content script
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 installation, make sure you have Node 16.10.0 or higher on your system.
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
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.Now that you've got an extension up and running, be sure to test it to ensure it's functioning as expected.
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
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, andtest-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
With your build running, you may want to consider other features available for your extension.
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();
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);
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.
Last modified 1mo ago