declarativeNetRequest Permission — Chrome Extension Reference
4 min readdeclarativeNetRequest Permission — Chrome Extension Reference
Overview
- Permission string:
"declarativeNetRequest"or"declarativeNetRequestWithHostAccess" - What it grants: Block, redirect, or modify network requests using declarative rules
- Risk level: Medium-High — can block/redirect any network traffic
- MV3 replacement: This replaces the
webRequestBlockingAPI from MV2 @theluckystrike/webext-permissionsdescription:describePermission('declarativeNetRequest')- Cross-ref:
docs/mv3/declarative-net-request.mdfor migration guide
Permission Variants
"declarativeNetRequest"— use rules defined in the manifest (static rulesets)"declarativeNetRequestWithHostAccess"— required to redirect requests to URLs the extension doesn’t have host permissions for"declarativeNetRequestFeedback"— access tochrome.declarativeNetRequest.onRuleMatchedDebugfor debugging
manifest.json Setup
{
"permissions": ["declarativeNetRequest"],
"declarative_net_request": {
"rule_resources": [{
"id": "ruleset_1",
"enabled": true,
"path": "rules.json"
}]
}
}
Key APIs
Static Rules (rules.json)
[{
"id": 1,
"priority": 1,
"action": { "type": "block" },
"condition": {
"urlFilter": "tracker.example.com",
"resourceTypes": ["script", "image"]
}
}]
- Defined in JSON files referenced by manifest
- Loaded at install time — very fast
- Up to 300,000 static rules across all rulesets (shared quota)
Dynamic Rules
chrome.declarativeNetRequest.updateDynamicRules({
addRules: [{
id: 1000,
priority: 1,
action: { type: "block" },
condition: { urlFilter: "ads.example.com" }
}],
removeRuleIds: [999]
});
- Added/removed at runtime
- Persist across extension restarts
- Limit: 30,000 dynamic rules
Session Rules
chrome.declarativeNetRequest.updateSessionRules({
addRules: [{ id: 2000, priority: 1, action: { type: "block" }, condition: { urlFilter: "temp.example.com" } }]
});
- Only exist for current browser session
- Cleared when browser restarts
- Limit: 5,000 session rules
Rule Actions
"block"— block the request entirely"redirect"— redirect to another URL (requires host permissions)"allow"— allow a request that would otherwise be blocked"allowAllRequests"— allow all requests in a frame"modifyHeaders"— add/remove/set request or response headers
Condition Matching
urlFilter: Pattern matching (||example.com,*tracking*)regexFilter: Full regex support (limited to 1000 regex rules)resourceTypes:"main_frame","sub_frame","script","image","xmlhttprequest", etc.domains/excludedDomains: Limit which sites trigger the rulerequestMethods:"get","post", etc.
Common Patterns
Ad/Tracker Blocker
- Static rules for known ad domains
- Dynamic rules for user-added blocks
- Store user block list with
@theluckystrike/webext-storage
Request Redirect
- Redirect HTTP to HTTPS
- Redirect old URLs to new ones
- Custom error pages
Header Modification
- Add security headers (CSP, X-Frame-Options)
- Remove tracking headers
- Modify User-Agent for specific sites
Runtime Permission Check
import { checkPermission } from '@theluckystrike/webext-permissions';
const result = await checkPermission('declarativeNetRequest');
Debugging
chrome.declarativeNetRequest.onRuleMatchedDebug(requiresdeclarativeNetRequestFeedbackpermission)chrome.declarativeNetRequest.getMatchedRules()— see which rules firedchrome.declarativeNetRequest.getDynamicRules()— list current dynamic rules
Limits Summary
| Type | Max Rules | |——|———–| | Static | 300,000 (shared) | | Dynamic | 30,000 | | Session | 5,000 | | Regex | 1,000 |
Gotchas
- Rule IDs must be globally unique — if you use the same ID in both static and dynamic rules, behavior is undefined. Establish a clear ID range convention (e.g., 1-9999 for static, 10000+ for dynamic).
- Regex rules have a hard limit of 1,000 — prefer
urlFilterpatterns overregexFilterwhenever possible. URL filter patterns cover most use cases and don’t count against the regex quota. - Static rules cannot be modified at runtime — they are baked into the extension package. Use
updateEnabledRulesets()to toggle entire rulesets on/off, or use dynamic rules for user-configurable blocking.
Common Errors
- Rule ID conflicts — each rule must have a unique ID
- Invalid
urlFilterpattern — test patterns carefully - Missing host permissions for redirects
- Exceeding rule count limits
Related Permissions
- webRequest — read-only network observation (MV3)
- activeTab — temporary host access for per-tab rules
API Reference
Frequently Asked Questions
What is declarativeNetRequest used for?
declarativeNetRequest allows extensions to block or modify network requests declaratively (without seeing the request content), which is required in Manifest V3.
Is declarativeNetRequest free to use?
Yes, the declarativeNetRequest API is free and doesn’t require any special approval, though there are ruleset size limits. —
Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.