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,redirectormodifyHeaders.condition: which requests match. Common fields:urlFilter(adblock-style syntax) orregexFilter,resourceTypes,initiatorDomains,requestDomains,excludedRequestDomainsandrequestMethods.
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
declarativeNetRequestFeedbackpermission and listen toonRuleMatchedDebug. 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
- Forgetting
resourceTypes. Without it, a rule matches every type exceptmain_frame, so blocking a whole site needsmain_framelisted explicitly. - ID collisions between dynamic rules. Keep a counter in storage.
- Expecting regex flexibility. Some regex patterns are rejected for complexity, and compiled rules must stay under a size limit. Prefer
urlFilterwhere possible. - 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.