kienbui1995/cross-browser-compat

Cross-Browser Compatibility

When to Use

• Building an extension that needs to work in Chrome + Firefox (most common)
• Adding Safari support (requires Xcode conversion)
• Debugging browser-specific API differences
• Choosing between Chrome-only and cross-browser approach

Core Jobs

1. Browser Support Matrix

| Feature | Chrome | Firefox | Safari | Edge | |---------|--------|---------|--------|------| | Manifest V3 | ✅ Required | ✅ Supported | ✅ Required | ✅ Required | | Service Workers | ✅ | ✅ (110+) | ✅ | ✅ | | Side Panel | ✅ (114+) | ❌ (sidebar) | ❌ | ✅ | | declarativeNetRequest | ✅ | ✅ | ✅ | ✅ | | chrome.* namespace | ✅ | ✅ (alias) | ✅ (alias) | ✅ | | browser.* namespace | ❌ native | ✅ native | ✅ native | ❌ native |

2. webextension-polyfill (Recommended)

Use @mozilla/webextension-polyfill for Promise-based APIs across browsers:

import browser from 'webextension-polyfill';
// Works in Chrome, Firefox, Safari, Edge
const tabs = await browser.tabs.query({ active: true });

3. Firefox-Specific Differences

• Firefox uses browser.* namespace natively (Promise-based)
• Firefox requires browser_specific_settings in manifest:

"browser_specific_settings": {
  "gecko": {
    "id": "[email protected]",
    "strict_min_version": "109.0"
  }
}

• Firefox does NOT support Side Panel (has its own sidebar API)
• Firefox blocks some cross-origin requests that Chrome allows

4. Safari via Xcode

# Convert Chrome extension to Safari format
xcrun safari-web-extension-converter /path/to/extension --project-location ./safari-ext

• Requires Xcode + Apple Developer account ($99/year)
• Distributed through Mac App Store (not separate store)
• User must enable extension in Safari settings

5. Build-time Detection

// Runtime browser detection
const isFirefox = navigator.userAgent.includes('Firefox');
const isChrome = !!window.chrome && !!window.chrome.runtime;

// Feature detection (preferred)
const hasSidePanel = !!chrome.sidePanel;

Key Concepts

• chrome.* — Chrome/Edge native; aliased in Firefox/Safari
• browser.* — Firefox/Safari native; NOT available in Chrome without polyfill
• webextension-polyfill — wraps callback APIs in Promises, normalizes browser differences
• Gecko ID — Firefox requires unique extension ID in browser_specific_settings
• WXT/Plasmo — handle cross-browser builds automatically

Checklist

• [ ] Using webextension-polyfill or WXT for cross-browser Promise APIs?
• [ ] Firefox browser_specific_settings.gecko.id set in manifest?
• [ ] Side Panel replaced with fallback for Firefox?
• [ ] Feature detection used (not browser-string sniffing)?
• [ ] Tested in Firefox (not just Chrome)?

Output Format

• 🔴 Critical — browser.* calls without polyfill in Chrome, missing Gecko ID for Firefox
• 🟡 Warning — Chrome-only APIs without fallback, no Firefox testing
• 🟢 Suggestion — webextension-polyfill for cleaner cross-browser code, WXT for automated builds

Common Pitfalls

• browser.tabs.query() fails in Chrome without polyfill — use chrome.* or add polyfill
• Firefox rejects extension without browser_specific_settings.gecko.id
• Safari extension requires full Xcode project + App Store review (not just a zip)