Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
doesTabExist
✓ import doesTabExist from 'webext-tools/does-tab-exist.js';
✗ import { doesTabExist } from 'webext-tools';
Since v4.0.0, each utility is a default export from its specific file path. The old single-entry point named import no longer works.
createContextMenu
✓ import createContextMenu from 'webext-tools/create-context-menu.js';
✗ const createContextMenu = require('webext-tools/create-context-menu');
Introduced in v3.0.0. As of v4.0.0, it must be imported from its dedicated file. Primarily designed for ESM usage in modern browser extensions.
setActionPopup
✓ import setActionPopup from 'webext-tools/set-action-popup.js';
✗ import { setActionPopup } from 'webext-tools';
Introduced in v1.2.0, supports MV3 since v1.2.3. Requires specific file import since v4.0.0.
getExtensionUrl
✓ import getExtensionUrl from 'webext-tools/get-extension-url.js';
✗ import * as tools from 'webext-tools'; tools.getExtensionUrl();
Added in v4.0.0. Follows the per-file default export pattern. Requires a valid extension context to use `browser.runtime.getURL` internally.
This quickstart demonstrates how to import and use several `webext-tools` utilities within a Web Extension's background script, including creating a context menu and setting the browser action popup. It includes a mock `browser` API for basic local execution understanding, though it requires a real extension environment.
import createContextMenu from 'webext-tools/create-context-menu.js';
import getExtensionUrl from 'webext-tools/get-extension-url.js';
import setActionPopup from 'webext-tools/set-action-popup.js';
// This polyfill/mock ensures `browser` API is available for demonstration purposes
// In a real Web Extension, `browser` is globally available.
const browser = globalThis.browser || {
tabs: {
create: (options) => console.log('Creating tab:', options.url)
},
contextMenus: {
create: (options) => {
console.log(`Creating context menu: ID='${options.id}', Title='${options.title}', Contexts='${options.contexts}'`);
// Simulate adding an onclick listener
if (options.onclick) {
console.log('Context menu handler registered.');
// In a real extension, this would react to actual clicks.
}
}
},
action: {
setPopup: (options) => console.log('Setting action popup:', options.popup)
},
runtime: {
getURL: (path) => `chrome-extension://your_extension_id/${path}`,
onInstalled: { addListener: (cb) => cb() }, // Mock event listener
onStartup: { addListener: (cb) => cb() } // Mock event listener
}
};
async function setupExtensionUtilities() {
// Create a context menu item that opens an extension page
createContextMenu({
id: 'open-webext-page',
title: 'Open Example Page (webext-tools)',
contexts: ['page', 'selection'],
onclick: (info, tab) => {
if (tab?.url) {
console.log(`Context menu clicked on URL: ${tab.url}`);
browser.tabs.create({
url: getExtensionUrl('pages/example.html'),
active: true
});
}
}
});
// Dynamically set the browser action popup to an HTML file within the extension
setActionPopup('pages/popup.html');
console.log('webext-tools utilities initialized in background script.');
}
// Ensure setup runs when the extension loads or updates
browser.runtime.onInstalled.addListener(setupExtensionUtilities);
browser.runtime.onStartup.addListener(setupExtensionUtilities);
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'doesTabExist')
Attempting to use a utility function like `doesTabExist` via a named import or after incorrect CommonJS `require` syntax, which is no longer supported for individual tools since v4.0.0.
fixChange the import statement from `import { doesTabExist } from 'webext-tools';` to `import doesTabExist from 'webext-tools/does-tab-exist.js';` Extension is running in Manifest V2, but requires Manifest V3.
Using `webext-tools` version 4.0.0 or higher in an extension configured with `manifest_version: 2`.
fixUpdate your extension's `manifest.json` to specify `"manifest_version": 3` and migrate any other MV2-specific APIs to their MV3 equivalents.
Error: Invalid value for property 'contexts'. (Received: "all").
Passing an invalid or deprecated string value to the `contexts` array of `createContextMenu` after the type strictness increase in v4.0.0.
fixReview the Web Extension API documentation for `contextMenus.create` and the `webext-tools` types for `createContextMenu` to use valid `contexts` strings (e.g., 'page', 'selection', 'link').
Audit
Dependencies
No dependency data recorded yet.