> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Extension.js needs Node.js 22.12 or newer; Node.js 18 and 20 do not work. It also runs on Deno 2.5+ and Bun 1.2+.
> The default browser target is chromium and a build lands in dist/<browser>, so dist/chromium by default. extension build writes a zip only when --zip is passed.
> Prefix a manifest key with a browser name when browsers differ. chromium: covers every Chromium-family target and Safari builds read it too. Since 4.1.19 chrome: means Chrome alone and edge: means Edge alone.
> Write one background.service_worker in manifest.json instead of hand-writing per-browser background keys; Extension.js converts it for each browser.
> package.json or deno.json marks the project root, not manifest.json. A config file is optional, and only extension.config.js, .mjs and .cjs are loaded, never .ts.
> The bundler is Rspack, extended through the config hook in extension.config.js. A project needs no separate bundler config file.
> Use --no-browser to skip the browser launch; --no-runner no longer exists and --no-open still launches the browser. Use --output for machine output; --format and --wait-format are deprecated.

# Intercept network requests

> Observe HTTP traffic from a browser extension with non-blocking webRequest listeners, understand MV3 blocking limits, and inspect requests in a devtools panel.

Watch every request a page makes with the `webRequest` API. In Manifest V3 the listeners are observational: you can log, measure, and analyze traffic, but not rewrite it in JavaScript.

## What MV3 allows

| Goal | Available API |
| - | - |
| Observe requests and responses | `webRequest` non-blocking listeners |
| Block, redirect, modify headers | `declarativeNetRequest` rules |
| Blocking `webRequest` handlers | Policy-installed extensions only (`webRequestBlocking`) |
| Handle proxy or VPN auth | `onAuthRequired` with the `webRequestAuthProvider` permission |

Regular Chrome installs cannot use `webRequestBlocking` in Manifest V3. If your goal is to block or rewrite traffic, declare rules instead. See [Build an ad blocker](https://extension.js.org/docs/workflows/build-an-ad-blocker.md).

## Manifest

The `webRequest` events only fire for hosts that your extension can access, so pair the permission with host permissions.

```json manifest.json theme={null}
{
  "manifest_version": 3,
  "name": "Request Inspector",
  "version": "1.0.0",
  "permissions": ["webRequest"],
  "host_permissions": ["<all_urls>"],
  "background": {
    "service_worker": "background.js"
  },
  "devtools_page": "devtools/index.html"
}
```

## Observe requests in the background

Register listeners at the top level of the background script, so the service worker re-registers them on every wake.

```js background.js theme={null}
chrome.webRequest.onBeforeRequest.addListener(
  (details) => {
    console.log('→', details.method, details.url, details.type)
  },
  { urls: ['<all_urls>'] }
)

chrome.webRequest.onCompleted.addListener(
  (details) => {
    console.log('←', details.statusCode, details.url)
  },
  { urls: ['<all_urls>'] }
)

chrome.webRequest.onErrorOccurred.addListener(
  (details) => {
    console.warn('✗', details.error, details.url)
  },
  { urls: ['<all_urls>'] }
)
```

Each `details` object carries the request id, tab id, method, URL, resource type, and timing. Correlate events by `details.requestId` to build a full request timeline.

## Inspect requests in a devtools panel

For request inspection with response bodies, a devtools panel is the better surface. The `chrome.devtools.network` API exposes finished requests as HAR entries, and it needs no `webRequest` permission.

The `devtools_page` registers the panel:

```js devtools/scripts.js theme={null}
chrome.devtools.panels.create('Requests', '', 'panel/index.html')
```

The panel then records traffic for the inspected tab:

```js panel/scripts.js theme={null}
chrome.devtools.network.onRequestFinished.addListener((entry) => {
  console.log(entry.request.method, entry.request.url, entry.response.status)

  entry.getContent((body) => {
    if (body) console.log('body bytes:', body.length)
  })
})
```

The listener only receives traffic while devtools is open on that tab. Use `chrome.devtools.network.getHAR` to read what loaded before the panel attached.

## Run it

```bash theme={null}
npx extension@latest dev ./request-inspector --browser=chromium
```

Open any page and watch the background console log traffic. Then open devtools on the page and choose the Requests panel.

## Firefox differences

* Firefox Manifest V3 still supports blocking `webRequest` with the `webRequestBlocking` permission.
* Firefox treats Manifest V3 host permissions as opt-in. Users grant them from the extensions panel, not at install time.
* Firefox runs the background as an event page, not a service worker. Top-level listener registration works on both.
* The devtools APIs above work in Firefox under the same `chrome.devtools.*` names.

See [Cross-browser compatibility](https://extension.js.org/docs/features/cross-browser-compatibility.md) for the shared API surface.

## Start from a template

The `devtools` template ships a working `devtools_page` plus panel wiring.

```bash theme={null}
npx extension@latest create request-inspector --template=devtools
```

Repository: [extension-js/templates/devtools](https://github.com/extension-js/templates/tree/main/examples/devtools)

## Best practices

* Narrow the `urls` filter on each listener instead of listening to `<all_urls>` in production.
* Correlate events by `requestId` rather than by URL, since pages repeat URLs.
* Keep listeners fast, because every observed request invokes them.
* Request the narrowest host permissions that your feature needs.
* Use `declarativeNetRequest` for blocking, and keep `webRequest` for observation.

## Next steps

* Block traffic declaratively in [Build an ad blocker](https://extension.js.org/docs/workflows/build-an-ad-blocker.md).
* Review host permission hygiene in the [Security checklist](https://extension.js.org/docs/workflows/security-checklist.md).
* Review [Manifest V3 concepts](https://extension.js.org/docs/concepts/manifest-v3.md) for the service-worker lifecycle.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.