Developer

declarativeNetRequest by Example: Blocking, Redirecting and Modifying Headers in MV3

Working declarativeNetRequest rules for Manifest V3: static and dynamic rules, redirects, header changes, allowlists, priorities, debugging and Chrome's limits.

declarativeNetRequest (DNR) is how Manifest V3 extensions block or change network requests in Chrome, Edge and Brave. Instead of inspecting each request in your own code, you give the browser a list of rules, and the browser applies them. It’s faster and more private, and it’s also a different way of thinking that trips people up at first.

This guide is a set of working examples. Limits and behavior are from Chrome’s declarativeNetRequest reference, as of November 2026. For why DNR replaced blocking webRequest, see Manifest V3 explained.

The anatomy of a rule

Every rule has four parts:

{
  "id": 1,
  "priority": 1,
  "action": { "type": "block" },
  "condition": {
    "urlFilter": "||tracker.example^",
    "resourceTypes": ["script", "image", "xmlhttprequest"]
  }
}
  • id: unique within its ruleset (or within dynamic/session rules).
  • priority: higher wins when several rules match.
  • action.type: block, allow, allowAllRequests, upgradeScheme, redirect or modifyHeaders.
  • condition: which requests match. Common fields: urlFilter (adblock-style syntax) or regexFilter, resourceTypes, initiatorDomains, requestDomains, excludedRequestDomains and requestMethods.

The urlFilter syntax: || anchors to a domain (and its subdomains), ^ is a separator such as /, ? or the end of the URL, * is a wildcard, and | anchors the start or end of the URL.

Three kinds of rules

Kind Defined Persists Typical use
Static JSON files listed in the manifest Until the extension updates Large, shipped filter lists
Dynamic updateDynamicRules() at runtime Across restarts and updates User-created rules, allowlists
Session updateSessionRules() at runtime Until the browser closes Temporary toggles

Example 1: a static blocking ruleset

manifest.json:

{
  "manifest_version": 3,
  "name": "Tracker Trimmer",
  "version": "1.0.0",
  "permissions": ["declarativeNetRequest"],
  "declarative_net_request": {
    "rule_resources": [
      { "id": "trackers", "enabled": true, "path": "rules/trackers.json" }
    ]
  }
}

rules/trackers.json:

[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {
      "urlFilter": "||tracker.example^",
      "resourceTypes": ["script", "image", "xmlhttprequest", "ping"]
    }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {
      "urlFilter": "||ads.example^",
      "domainType": "thirdParty"
    }
  }
]

The declarativeNetRequest permission shows the install warning “Block content on any page”. Blocking with static rules doesn’t require host permissions. That’s one of DNR’s privacy benefits.

Example 2: an allowlist that beats your block rules

Let users allow a site. An allowAllRequests rule on the main frame allows everything that page loads:

async function allowSite(domain) {
  await chrome.declarativeNetRequest.updateDynamicRules({
    addRules: [{
      id: 1000 + Math.floor(Math.random() * 100000),
      priority: 100,
      action: { type: 'allowAllRequests' },
      condition: { requestDomains: [domain], resourceTypes: ['main_frame'] },
    }],
  });
}

Give allow rules a higher priority than your block rules. In production, track IDs in storage instead of using random numbers, so you can remove the rule later with removeRuleIds.

Example 3: upgrade to HTTPS

{
  "id": 3,
  "priority": 1,
  "action": { "type": "upgradeScheme" },
  "condition": { "requestDomains": ["legacy.example"], "resourceTypes": ["main_frame", "sub_frame"] }
}

Example 4: redirect a request

Redirects need host permissions for the request URL (and its initiator), and the target can be an extension resource or another URL:

{
  "id": 4,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": { "extensionPath": "/blocked.html" }
  },
  "condition": { "urlFilter": "||distracting.example^", "resourceTypes": ["main_frame"] }
}

To redirect to an extension page, list it under web_accessible_resources. Redirecting the main frame like this is how “focus mode” extensions show a “you blocked this site” page.

Example 5: modify headers

{
  "id": 5,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [
      { "header": "x-debug-mode", "operation": "set", "value": "1" }
    ],
    "responseHeaders": [
      { "header": "x-powered-by", "operation": "remove" }
    ]
  },
  "condition": { "requestDomains": ["staging.example.com"], "resourceTypes": ["main_frame", "xmlhttprequest"] }
}

Header changes also need host permissions for the affected sites. Use them carefully. Removing security headers such as Content-Security-Policy or X-Frame-Options on arbitrary sites is exactly what malicious extensions have done, and it’s a quick way to fail Chrome Web Store review.

The limits (Chrome, November 2026)

Limit Value
Static rulesets declared / enabled 100 / 50
Static rules guaranteed per extension 30,000 (more from a shared global pool)
Dynamic rules (“safe”) 30,000
“Unsafe” dynamic rules 5,000
Regex rules (static and dynamic counted separately) 1,000

“Unsafe” rules are those with redirect or header-modification actions. They have a lower cap.

Debugging rules

  • During development, add the declarativeNetRequestFeedback permission and listen to onRuleMatchedDebug. It fires for every match, but only for unpacked extensions:
chrome.declarativeNetRequest.onRuleMatchedDebug?.addListener((info) => {
  console.log('Matched', info.rule.ruleId, info.request.url);
});
  • In production, getMatchedRules() returns matches for tabs where you have access. It’s rate-limited, though calls tied to a user gesture are exempt.
  • Validate rule files: Chrome reports invalid rules when you load the extension. Check the Errors button on chrome://extensions.
  • Badge counts: setExtensionActionOptions({ displayActionCountAsBadgeText: true }) shows the number of matched requests on your icon.

Common mistakes

  1. Forgetting resourceTypes. Without it, a rule matches every type except main_frame, so blocking a whole site needs main_frame listed explicitly.
  2. ID collisions between dynamic rules. Keep a counter in storage.
  3. Expecting regex flexibility. Some regex patterns are rejected for complexity, and compiled rules must stay under a size limit. Prefer urlFilter where possible.
  4. Assuming Firefox is identical. Firefox supports DNR but has its own limits and also offers blocking webRequest. See the cross-browser checklist.

DNR rewards planning: decide which rules are static, which are user-controlled, and how they interact through priorities, and the API is fast and predictable.

Keep reading