Web Extension Utility Functions

4.0.0 · active · verified Sun Apr 19

webext-tools provides a collection of modular utility functions designed to simplify common tasks when developing Web Extensions for browsers like Chrome, Firefox, and Safari. The current stable version is 4.0.0, which exclusively targets Manifest V3. The package emphasizes modularity, with each utility function available via its own entry point, allowing developers to import only the specific tools they need and reducing bundle size. This approach differentiates it from monolithic utility libraries. While there isn't an explicit release cadence mentioned, the project sees active development and releases major versions periodically with breaking changes, consistently adapting to browser API changes.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'doesTabExist')
```
cause 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.

fix Change 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.
```
cause Using `webext-tools` version 4.0.0 or higher in an extension configured with `manifest_version: 2`.

fix Update 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").
```
cause Passing an invalid or deprecated string value to the `contexts` array of `createContextMenu` after the type strictness increase in v4.0.0.

fix Review 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').

Warnings

breaking The package no longer offers a single entry point. All utilities must now be imported individually from their specific file paths.
Fix: Update all imports from `import { someTool } from 'webext-tools';` to `import someTool from 'webext-tools/some-tool.js';`.
breaking Support for Manifest V2 (MV2) has been completely dropped. The package now exclusively targets Manifest V3 (MV3).
Fix: Ensure your extension's `manifest.json` specifies `manifest_version: 3`. If still on MV2, you must migrate your extension or use an older version of `webext-tools`.
breaking The `createContextMenu` function now enforces stricter typing for its `contexts` parameter.
Fix: Review all calls to `createContextMenu` and ensure the `contexts` array contains only valid, type-safe values as per the updated API definitions.
breaking The `addOptionsContextMenu` functionality has been moved out of `webext-tools` and into the `webext-bugs` package.
Fix: If you used `addOptionsContextMenu`, you need to install and import it from `webext-bugs` directly or implement the equivalent logic yourself.
breaking The `canAccessTab` function was removed in favor of directly using functionality from the `webext-content-scripts` package.
Fix: Replace calls to `canAccessTab` with direct usage of the relevant functions from `webext-content-scripts` or implement custom tab access logic.

Install

npm install webext-tools npm
yarn add webext-tools yarn
pnpm add webext-tools pnpm

Imports

doesTabExist
wrong:
```
import { doesTabExist } from 'webext-tools';
```
correct:
```
import doesTabExist from 'webext-tools/does-tab-exist.js';
```
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
wrong:
```
const createContextMenu = require('webext-tools/create-context-menu');
```
correct:
```
import createContextMenu from 'webext-tools/create-context-menu.js';
```
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
wrong:
```
import { setActionPopup } from 'webext-tools';
```
correct:
```
import setActionPopup from 'webext-tools/set-action-popup.js';
```
Introduced in v1.2.0, supports MV3 since v1.2.3. Requires specific file import since v4.0.0.
getExtensionUrl
wrong:
```
import * as tools from 'webext-tools'; tools.getExtensionUrl();
```
correct:
```
import getExtensionUrl from 'webext-tools/get-extension-url.js';
```
Added in v4.0.0. Follows the per-file default export pattern. Requires a valid extension context to use `browser.runtime.getURL` internally.

Quickstart

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);

view raw JSON →