Browser Extension Anti-Patterns

Common mistakes to avoid when developing browser extensions for Chrome, Firefox, and Safari.

Overview

This skill catalogs anti-patterns that lead to:

• Poor performance and memory leaks

• Store rejections (Chrome Web Store, AMO, Safari App Store)

• Security vulnerabilities

• Cross-browser incompatibilities

• Poor user experience

This skill covers:

• Performance anti-patterns

• Store rejection reasons

• API misuse patterns

• Manifest configuration mistakes

• Content script pitfalls

This skill does NOT cover:

• General JavaScript anti-patterns

• Server-side code issues

• Native messaging host problems

Quick Reference

Red Flags Checklist

Anti-Pattern Impact Solution

<all_urls> permission Store rejection Use specific host permissions

Blocking background operations Extension suspend issues Use async/Promise patterns

DOM polling in content scripts High CPU usage Use MutationObserver

Unbounded storage growth Memory exhaustion Implement retention policies

eval() or new Function()

CSP violation, store rejection Use static code

Performance Anti-Patterns

1. DOM Polling

Problem: Using setInterval to check for DOM changes.

// BAD: Polls every 100ms, wastes CPU setInterval(() => { const element = document.querySelector('.target'); if (element) { processElement(element); } }, 100);

Solution: Use MutationObserver.

// GOOD: Only fires when DOM changes const observer = new MutationObserver((mutations) => { for (const mutation of mutations) { const element = document.querySelector('.target'); if (element) { processElement(element); observer.disconnect(); } } }); observer.observe(document.body, { childList: true, subtree: true });

2. Synchronous Storage Access

Problem: Using synchronous storage patterns that block execution.

// BAD: Blocks until storage returns const data = await browser.storage.local.get('key'); // 50+ more sequential awaits...

Solution: Batch storage operations.

// GOOD: Single storage call const data = await browser.storage.local.get(['key1', 'key2', 'key3']);

3. Memory Leaks in Content Scripts

Problem: Event listeners not cleaned up when navigating away.

// BAD: Listener persists after navigation window.addEventListener('scroll', handleScroll);

Solution: Use AbortController or cleanup handlers.

// GOOD: Cleanup on unload const controller = new AbortController(); window.addEventListener('scroll', handleScroll, { signal: controller.signal }); window.addEventListener('beforeunload', () => controller.abort());

4. Large Message Payloads

Problem: Sending large data between background and content scripts.

// BAD: Serializing megabytes of data browser.runtime.sendMessage({ type: 'data', payload: hugeArray });

Solution: Use chunking or IndexedDB for large data.

// GOOD: Store in IndexedDB, pass reference await idb.put('largeData', hugeArray); browser.runtime.sendMessage({ type: 'dataReady', key: 'largeData' });

5. Blocking Service Worker

Problem: Long-running operations in service worker prevent suspension.

// BAD: Service worker can't sleep background.js: while (processing) { await processChunk(); // Runs for minutes... }

Solution: Use alarms for long operations.

// GOOD: Let service worker sleep between chunks browser.alarms.create('processChunk', { delayInMinutes: 0.1 }); browser.alarms.onAlarm.addListener(async (alarm) => { if (alarm.name === 'processChunk') { const done = await processNextChunk(); if (!done) { browser.alarms.create('processChunk', { delayInMinutes: 0.1 }); } } });

Store Rejection Reasons

Chrome Web Store

Reason Trigger Fix

Broad host permissions <all_urls> or :///* without justification Narrow to specific domains

Remote code execution Loading scripts from external URLs Bundle all code locally

Misleading metadata Description doesn't match functionality Accurate description

Excessive permissions Requesting unused permissions Remove unnecessary permissions

Privacy violation Collecting data without disclosure Add privacy policy

Single purpose violation Multiple unrelated features Split into separate extensions

Affiliate/redirect abuse Hidden affiliate links Transparent disclosure

Firefox Add-ons (AMO)

Reason Trigger Fix

Obfuscated code Minified code without source Submit source code

eval() usage Dynamic code execution Refactor to static code

Missing gecko ID No browser_specific_settings Add gecko.id to manifest

CSP violations Inline scripts in HTML Move to external files

Tracking without consent Analytics without disclosure Add opt-in consent

Safari App Store

Reason Trigger Fix

Missing privacy manifest iOS 17+ requirement Add PrivacyInfo.xcprivacy

Guideline 2.3 violations Inaccurate metadata Match screenshots to functionality

Guideline 4.2 violations Spam/low quality Add meaningful functionality

Missing entitlements Using APIs without entitlement Configure in Xcode

API Misuse Patterns

1. tabs.query Without Filters

Problem: Querying all tabs unnecessarily.

// BAD: Gets ALL tabs across ALL windows const tabs = await browser.tabs.query({});

Solution: Use specific filters.

// GOOD: Only active tab in current window const [tab] = await browser.tabs.query({ active: true, currentWindow: true });

2. executeScript Without Target

Problem: Injecting scripts without specifying target.

// BAD: Injects into wrong tab or fails silently browser.scripting.executeScript({ func: myFunction });

Solution: Always specify target.

// GOOD: Explicit target browser.scripting.executeScript({ target: { tabId: tab.id }, func: myFunction });

3. Ignoring Promise Rejections

Problem: Not handling API errors.

// BAD: Silent failures browser.tabs.sendMessage(tabId, message);

Solution: Handle errors appropriately.

// GOOD: Handle disconnected tabs try { await browser.tabs.sendMessage(tabId, message); } catch (error) { if (error.message.includes('disconnected')) { // Tab closed or navigated away - expected } else { console.error('Unexpected error:', error); } }

4. Storage Without Limits

Problem: Writing unlimited data to storage.

// BAD: Storage grows unbounded const history = await browser.storage.local.get('history'); history.items.push(newItem); // Never removes old items await browser.storage.local.set({ history });

Solution: Implement retention policy.

// GOOD: Limit to last 1000 items const MAX_HISTORY = 1000; const history = await browser.storage.local.get('history'); history.items.push(newItem); if (history.items.length > MAX_HISTORY) { history.items = history.items.slice(-MAX_HISTORY); } await browser.storage.local.set({ history });

Manifest Anti-Patterns

1. Over-Permissioning

// BAD: Requests everything { "permissions": [ "<all_urls>", "tabs", "history", "bookmarks", "downloads", "webRequest", "webRequestBlocking" ] }

// GOOD: Minimum viable permissions { "permissions": ["storage", "activeTab"], "optional_permissions": ["tabs"], "host_permissions": ["://example.com/"] }

2. Missing Icons

// BAD: Only one icon size { "icons": { "128": "icon.png" } }

// GOOD: Multiple sizes for different contexts { "icons": { "16": "icons/16.png", "32": "icons/32.png", "48": "icons/48.png", "128": "icons/128.png" } }

3. Insecure CSP

// BAD: Allows unsafe-eval { "content_security_policy": { "extension_pages": "script-src 'self' 'unsafe-eval'; object-src 'self'" } }

// GOOD: Strict CSP { "content_security_policy": { "extension_pages": "script-src 'self'; object-src 'self'" } }

Content Script Pitfalls

1. Global Namespace Pollution

Problem: Variables leak into page scope.

// BAD: Pollutes global namespace var myExtensionData = {};

// Also bad: top-level const/let in non-module scripts const config = {};

Solution: Use IIFE or modules.

// GOOD: IIFE isolation (function() { const myExtensionData = {}; // All code here })();

// BETTER: Use ES modules (MV3) // manifest.json: "content_scripts": [{ "js": ["content.js"], "type": "module" }]

2. Race Conditions with Page Scripts

Problem: Page scripts modify DOM before content script runs.

// BAD: Element may not exist yet or be replaced const button = document.querySelector('.submit'); button.addEventListener('click', handler);

Solution: Wait for element with timeout.

// GOOD: Wait for element with timeout function waitForElement(selector, timeout = 5000) { return new Promise((resolve, reject) => { const element = document.querySelector(selector); if (element) return resolve(element);

const observer = new MutationObserver(() => {
  const element = document.querySelector(selector);
  if (element) {
    observer.disconnect();
    resolve(element);
  }
});

observer.observe(document.body, { childList: true, subtree: true });
setTimeout(() => {
  observer.disconnect();
  reject(new Error(`Timeout waiting for ${selector}`));
}, timeout);

}); }

Cross-Browser Pitfalls

1. Chrome-Only APIs

Chrome API Firefox Alternative Safari Alternative

chrome.sidePanel

Not available Not available

chrome.offscreen

Not available Not available

chrome.declarativeNetRequest

Partial support Limited support

2. Callback vs Promise APIs

// BAD: Chrome callback style chrome.tabs.query({}, function(tabs) { // Works in Chrome, fails in Firefox });

// GOOD: Use webextension-polyfill or browser.* const tabs = await browser.tabs.query({});

Checklist Before Submission

• No <all_urls> without justification

• No eval() or new Function()

• No remote code loading

• No obfuscated/minified code (or source provided)

• Privacy policy if collecting data

• Accurate store description

• Multiple icon sizes

• Gecko ID for Firefox

• Tested on all target browsers

• Storage limits implemented

• Error handling for all API calls