0Pricing
Browser Extensions Development (Chrome & Edge) · Lesson

Dynamic Rules & Debugging declarativeNetRequest

Add and update rules at runtime, manage rule IDs and priorities, and observe matched requests for debugging.

Dynamic Rules & Debugging declarativeNetRequest is a free Browser Extensions Development (Chrome & Edge) lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Browser Extensions Development (Chrome & Edge) learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Static vs Dynamic Rules

declarativeNetRequest supports two rule kinds. Static rules ship in JSON files in the manifest. Dynamic rules are added at runtime and persist across restarts.

Dynamic rules let your extension adapt to user choices without an update.

Declaring the Permission

You need the declarativeNetRequest permission. For dynamic rules at runtime, that is all you require.

{
  "permissions": ["declarativeNetRequest"]
}

The Shape of a Rule

Each rule has an id, a priority, an action, and a condition. The condition decides which requests match.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "block" },
  "condition": { "urlFilter": "ads.example.com" }
}

Adding Dynamic Rules

Use updateDynamicRules to add rules. Pass them in the addRules array.

chrome.declarativeNetRequest.updateDynamicRules({
  addRules: [{
    id: 1, priority: 1,
    action: { type: 'block' },
    condition: { urlFilter: 'tracker.com', resourceTypes: ['script'] }
  }]
})

Removing Rules by ID

The same call removes rules by listing their IDs in removeRuleIds. Adds and removes can happen together.

chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: [1]
})

Unique Rule IDs

Every dynamic rule needs a unique numeric id. Reusing an existing ID without removing it first causes an error.

const existing = await chrome.declarativeNetRequest.getDynamicRules()
const nextId = Math.max(0, ...existing.map(r => r.id)) + 1

Priorities Resolve Conflicts

When multiple rules match, priority decides which wins. Higher priority takes precedence; allow rules can override block rules at the same level.

{ "id": 2, "priority": 2, "action": { "type": "allow" }, "condition": { "urlFilter": "safe.com" } }

Session Rules

If you want rules that vanish when the browser closes, use updateSessionRules instead. They never persist to disk.

chrome.declarativeNetRequest.updateSessionRules({
  addRules: [tempRule]
})

Observing Matched Requests

For debugging, enable the feedback permission and listen to onRuleMatchedDebug to see which rule fired for each request.

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener((info) => {
  console.log('Matched rule ' + info.rule.ruleId)
})

Inspecting Current Rules

Call getDynamicRules to list everything currently active. This is essential when a rule misbehaves and you need to confirm what is installed.

const rules = await chrome.declarativeNetRequest.getDynamicRules()
console.log(rules.length + ' active rules')

Staying Within Limits

There is a cap on the number of dynamic rules. Audit and remove stale rules instead of piling on, and group conditions where possible to stay efficient.

Quick Check

Test your dynamic rules knowledge.

Recap

You learned dynamic request rules:

  • Add and remove with updateDynamicRules
  • Keep IDs unique and use priority for conflicts
  • Use session rules for temporary state
  • Debug with onRuleMatchedDebug and getDynamicRules
  • Respect rule count limits

Runtime rules let your extension adapt without shipping an update.

Frequently asked questions

Is the “Dynamic Rules & Debugging declarativeNetRequest” lesson free?

Yes — the full text of “Dynamic Rules & Debugging declarativeNetRequest” is free to read here on the web, and the Browser Extensions Development (Chrome & Edge) course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Browser Extensions Development (Chrome & Edge) course, upgrade to CoddyKit PRO.

What will I learn in “Dynamic Rules & Debugging declarativeNetRequest”?

Add and update rules at runtime, manage rule IDs and priorities, and observe matched requests for debugging. You practise Browser Extensions Development (Chrome & Edge) with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Browser Extensions Development (Chrome & Edge)?

No prior experience is required. Browser Extensions Development (Chrome & Edge) on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Dynamic Rules & Debugging declarativeNetRequest” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Browser Extensions Development (Chrome & Edge) lesson?

Yes. Every Browser Extensions Development (Chrome & Edge) lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Blocking Network Requests
  2. Modifying Request Headers
  3. Redirecting & Rewriting URLs
  4. Dynamic Rules & Debugging declarativeNetRequest
← Back to Browser Extensions Development (Chrome & Edge)