uBlock Deployment and Usage Guide

Prerequisites

• Browser: Chrome, Firefox, Safari, Opera, or Edge
• Node.js (for development): v12 or higher
• npm (for development): v6 or higher
• Git: For cloning the repository

Installation

For End Users (Browser Extension)

Chrome:

• Install from Chrome Web Store
• Or install manually from GitHub releases

Firefox:

• Install from Firefox Add-ons site
• Or install manually from GitHub releases

Safari:

• Install from uBlock homepage

Opera:

• Install the Chrome version from GitHub releases

For Developers

# Clone the repository
git clone https://github.com/uBlock-LLC/uBlock.git
cd uBlock

# Install dependencies
npm install

Configuration

Filter Lists

uBlock comes with several filter lists enabled by default:

• EasyList (ads)
• Acceptable Ads
• ABP Anti-Circumvention Filter List
• Cryptocurrency Mining Protection List

You can customize these in the extension settings or add more lists for tracking, analytics, and malware protection.

Development Configuration

No specific environment variables are required for development. The extension uses the browser's storage API for settings.

Build & Run

Development

# Build for development
npm run build:dev

# Watch for changes
npm run watch

Production

# Build for production
npm run build

# Create distributable package
npm run dist

Running in Browser

1. Open your browser's extension management page
2. Enable "Developer mode"
3. Click "Load unpacked extension"
4. Select the dist folder from your cloned repository

Deployment

Browser Extension Stores

To deploy to official browser stores:

1. Chrome Web Store: Package the extension and upload through the Chrome Developer Dashboard
2. Firefox Add-ons: Use the web-ext tool to package and submit
3. Safari Extensions: Submit through the Safari Extensions Developer Program

Manual Distribution

For internal or private distribution:

• Use the npm run dist command to create distributable packages
• Host the .zip files on your own server
• Provide direct download links for users

Troubleshooting

Common Issues

Extension not loading:

• Ensure "Developer mode" is enabled in your browser's extension settings
• Check browser console for JavaScript errors
• Verify the dist folder contains all necessary files

Filters not working:

• Check if filter lists are properly loaded in settings
• Verify internet connection for remote filter updates
• Clear browser cache and restart the browser

Performance issues:

• Disable unnecessary filter lists
• Avoid running multiple ad blockers simultaneously
• Check for conflicting extensions

Debug Mode

Enable debug mode in extension settings to:

• View detailed logging in browser console
• Monitor network requests being blocked
• Test custom filter rules

Memory Usage

If experiencing high memory usage:

• Check the memory benchmark results in the README
• Consider disabling resource-intensive filter lists
• Monitor with browser's built-in task manager

CPU Usage

For high CPU usage:

• Review the CPU benchmark data in the README
• Disable cosmetic filtering if not needed
• Check for inefficient custom rules

Filter Syntax Issues

For problems with custom filters:

• Refer to the filter syntax documentation
• Test rules using the element picker tool
• Check for syntax errors in custom filter lists