Chrome Extension Network Request Blocker: A Developer Guide

Chrome extension network request blocking represents one of the most powerful capabilities available to browser extension developers. This functionality allows extensions to intercept, modify, or completely block HTTP and HTTPS requests before they reach their destination. For developers and power users, understanding this mechanism opens doors to ad blocking, API rate limiting, debugging, privacy enhancement, and custom network filtering.

Understanding the Network Blocking Architecture

Chrome provides the declarativeNetRequest API for extensions to block or modify network requests. This API was introduced in Manifest V3 as a privacy-focused replacement for the older webRequest blocking API. The key advantage is that extensions no longer need to intercept and inspect every single network request in user space, which improves performance and privacy.

The declarativeNetRequest API works through a ruleset system. You define rules in a JSON file, and Chrome applies these rules at the network layer. This means the blocking happens efficiently without needing to examine request contents in JavaScript.

Here’s a basic manifest configuration:

{
  "manifest_version": 3,
  "name": "Network Request Blocker",
  "version": "1.0",
  "permissions": ["declarativeNetRequest"],
  "host_permissions": ["<all_urls>"],
  "declarative_net_request": {
    "rule_resources": [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules.json"
    }]
  }
}

Defining Blocking Rules

The rules file contains an array of rule objects. Each rule specifies conditions and actions. When all conditions match a request, the corresponding action executes.

// rules.json
{
  "rules": [
    {
      "id": 1,
      "priority": 1,
      "action": { "type": "block" },
      "condition": {
        "urlFilter": "doubleclick.net",
        "resourceTypes": ["script", "image"]
      }
    },
    {
      "id": 2,
      "priority": 1,
      "action": { "type": "block" },
      "condition": {
        "urlFilter": ".*\\.googlesyndication\\.com",
        "resourceTypes": ["sub_frame"]
      }
    }
  ]
}

This example blocks scripts and images from doubleclick.net domains and prevents iframe requests to googlesyndication.com. The urlFilter uses regex patterns, giving you fine-grained control over what gets blocked.

Dynamic Rule Management

Static rules work well for fixed filtering lists, but sometimes you need runtime control. The declarativeNetRequest API provides functions to update rules dynamically:

// background.js
chrome.runtime.onInstalled.addListener(() => {
  // Initial rules are loaded from rules.json automatically
  console.log('Network blocker extension installed');
});

// Toggle blocking for specific domains
function toggleDomainBlocking(domain, enabled) {
  const rule = {
    id: 100,
    priority: 10,
    action: { 
      type: enabled ? 'block' : 'allow' 
    },
    condition: {
      urlFilter: domain,
      resourceTypes: ['xmlhttprequest', 'script']
    }
  };
  
  if (enabled) {
    chrome.declarativeNetRequest.updateRules({
      addRules: [rule],
      ruleResourcesToUpdate: ['ruleset_1']
    });
  } else {
    chrome.declarativeNetRequest.updateRules({
      removeRuleIds: [100],
      ruleResourcesToUpdate: ['ruleset_1']
    });
  }
}

// Listen for messages from popup or content script
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.action === 'toggleBlocking') {
    toggleDomainBlocking(message.domain, message.enabled);
    sendResponse({ success: true });
  }
});

This pattern enables UI-driven blocking where users can enable or disable filters through a popup interface.

Advanced Filtering Techniques

Beyond simple blocking, you can implement more sophisticated filtering. For API rate limiting, you might block repeated requests to the same endpoint:

{
  "rules": [
    {
      "id": 1,
      "priority": 1,
      "action": { "type": "block" },
      "condition": {
        "urlFilter": "api\\.example\\.com/data",
        "requestDomains": ["api.example.com"],
        "resourceTypes": ["xmlhttprequest"],
        "regexFilter": ".*"
      }
    },
    {
      "id": 2,
      "priority": 2,
      "action": { 
        "type": "redirect",
        "redirect": { "extensionPath": "/blocked.html" }
      },
      "condition": {
        "urlFilter": "api\\.example\\.com/data",
        "resourceTypes": ["xmlhttprequest"]
      }
    }
  ]
}

You can also use the allow action to create exceptions to broader blocking rules. Define a general block rule with low priority, then add specific allow rules with higher priority for URLs you want to permit.

Practical Use Cases

Debugging API Endpoints

When developing web applications, you can block specific API calls to test error handling or simulate failures. Create rules that block endpoints temporarily while you verify your application’s resilience.

Privacy Enhancement

Block known tracking domains and analytics scripts. Many privacy-focused extensions use this exact mechanism to prevent data collection by third-party trackers.

Bandwidth Conservation

If you’re on limited connectivity, block video autoplay, high-resolution image loading, or specific content types to reduce data usage.

Development Workflow

Block distracting websites or API endpoints during work hours. Combine with a simple popup UI to create a personal productivity tool.

Important Limitations

The declarativeNetRequest API has constraints you should understand. First, rules have a maximum limit per ruleset, though you can use multiple rulesets. Second, you cannot inspect or modify request bodies—blocking operates on URL and headers only. Third, some request types like main frame navigation cannot be blocked entirely in all cases.

Additionally, Chrome enforces strict rules about when extensions can use blocking rules. The extension must declare specific host permissions, and users must manually grant permission in some cases.

Testing Your Implementation

Always test network blocking thoroughly. Chrome provides a dedicated testing interface in chrome://extensions where you can enable logging for declarativeNetRequest events. Check the console for any rule processing errors, and verify that blocking actually occurs by monitoring network tabs in developer tools.

// Enable debug logging in background script
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener((info) => {
  console.log('Rule matched:', info);
});

This listener fires when rules match, helping you verify your conditions work as expected during development.

Conclusion

Chrome extension network request blocking provides a robust foundation for building privacy tools, debugging utilities, and productivity enhancements. The declarativeNetRequest API offers sufficient flexibility for most use cases while maintaining performance through its declarative approach. Start with simple domain blocking rules and progressively add dynamic management and advanced filtering as your requirements grow.

Built by theluckystrike — More at zovo.one