Blocky - Browser Ad Blocker Extension

A powerful and lightweight ad blocker browser extension for Chrome and Edge that blocks ads using multiple filter sources.

Features

• ✅ Multi-Source Filtering: Uses EasyList and uBlock Origin filter lists
• 🚀 High Performance: Built with Manifest V3 and declarative net request
• 🎯 Smart Blocking: Combines network-level and DOM-based blocking
• 📊 Statistics: Track blocked ads and protected sites
• ⚙️ Customizable: Whitelist sites, custom rules, and blocking levels
• 🔒 Privacy-Focused: No data collection, all processing happens locally

Installation

For Development

1. Clone this repository
2. Open Chrome/Edge and navigate to chrome://extensions/
3. Enable "Developer mode"
4. Click "Load unpacked" and select the extension folder
5. The extension should now appear in your browser toolbar

From Chrome Web Store

Coming soon - extension will be available on the Chrome Web Store and Edge

Usage

Basic Usage

1. Click the Blocky icon in your browser toolbar
2. The extension is enabled by default and starts blocking ads immediately
3. View blocking statistics in the popup
4. Toggle blocking on/off as needed

Whitelisting Sites

1. Visit a site you want to whitelist
2. Click the Blocky icon
3. Click "Whitelist Site" to disable blocking for that domain

Customizing Settings

1. Right-click the Blocky icon and select "Options"
2. Configure filter lists, blocking levels, and custom rules
3. Manage your whitelist and export/import settings

Project Structure

Blocky/
├── manifest.json          # Extension configuration
├── background.js          # Service worker for background tasks
├── content.js             # Content script for DOM manipulation
├── popup.html             # Extension popup interface
├── options.html           # Settings page
├── scripts/
│   ├── popup.js          # Popup functionality
│   └── options.js        # Options page functionality
├── styles/
│   ├── popup.css         # Popup styling
│   └── options.css       # Options page styling
├── rules/
│   ├── easylist_rules.json    # EasyList blocking rules
│   └── ublock_rules.json      # uBlock Origin rules
├── icons/                # Extension icons
└── README.md

Technical Details

Manifest V3

This extension uses Manifest V3, which provides:

• Enhanced security through service workers
• Declarative net request for efficient blocking
• Improved performance and battery life

Filter Sources

• EasyList: Primary ad blocking filter list with ~30,000 rules
• uBlock Origin: Additional blocking rules with ~15,000 rules
• Custom Rules: User-defined blocking rules in AdBlock Plus syntax

Blocking Methods

1. Network Blocking: Uses declarativeNetRequest to block requests
2. DOM Blocking: Content script removes ad elements from pages
3. CSS Blocking: Hides common ad containers with CSS rules

Development

Prerequisites

• Chrome or Edge browser
• Basic knowledge of JavaScript and browser extensions

Local Development

1. Make changes to the extension files
2. Go to chrome://extensions/
3. Click the refresh icon for the Blocky extension
4. Test your changes

Adding New Filter Rules

1. Edit the rule files in the rules/ directory
2. Follow the declarativeNetRequest rule format
3. Update the rule IDs to avoid conflicts
4. Test thoroughly before deployment

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Filter Rule Format

The extension uses Chrome's declarativeNetRequest format:

{
  "id": 1001,
  "priority": 1,
  "action": { "type": "block" },
  "condition": {
    "urlFilter": "*://ads.example.com/*",
    "resourceTypes": ["script", "image", "xmlhttprequest"]
  }
}

Privacy Policy

Blocky respects your privacy:

• No data is collected or transmitted to external servers
• All blocking happens locally in your browser
• Statistics are stored locally on your device
• No user tracking or analytics
• Filter lists are updated directly from their sources

Performance

• Minimal memory footprint (~5MB)
• Fast startup time (<100ms)
• Efficient rule matching
• No impact on browser performance
• Battery-friendly design

Compatibility

• Chrome: Version 88+
• Edge: Version 88+
• Brave: Compatible
• Opera: Compatible with Chrome extensions

Known Issues

• Some dynamic ads may require page refresh to be blocked
• Whitelist changes require tab reload to take effect
• Custom rules syntax is limited to basic AdBlock Plus format

Roadmap

• Support for additional filter lists
• Advanced rule syntax support
• Anti-adblock countermeasures

License

MIT License - see LICENSE file for details

Support

• Report bugs: GitHub Issues
• Feature requests: GitHub Discussions
• Documentation: Wiki

Acknowledgments

• EasyList maintainers for the filter lists
• uBlock Origin project for inspiration and filter rules
• Chrome Extension documentation and community

---

Made with ❤️ and ✨ for a better web browsing experience