extension-functions-best-practices
Extension Functions Best Practices
Implementation guidance for browser extension features across 13 categories. Each category includes reference open-source projects and links to detailed implementation guides.
When to Use
- Building extension features in any supported category
- Looking for proven patterns and reference implementations
- Choosing libraries and APIs for specific functionality
- Understanding permission requirements
How Reference Projects Are Chosen
- Verifiable: Prefer projects you can install from a store, or build into a loadable extension from GitHub, with real Issues/Releases.
- Behavior-aligned: Table Highlights describe user-visible behavior (e.g. “merge HLS segments”) rather than only “call the downloads API”.
- Download / streaming: Tutorial-style
chrome.downloads+ anm3u8URL is often not enough for a playable file; treat rules/download.md (“Reality check & common pitfalls”) and repos such as Cat Catch, Live Stream Downloader, and Video DownloadHelper as the ground truth.
Feature Categories
1. Video
Common Features: Enhancement (rotation, speed, zoom), download (media sniffing, M3U8/MPD), screen recording
| Reference Projects | Type | Highlights |
|---|---|---|
| Video Roll | Enhancement | Rotation, zoom, filters, VR mode (in-page <video> UX) |
| Cat Catch | Download | Sniffing, M3U8/MPD parsing, handoff to N_m3u8DL-RE and similar (high activity) |
| Live Stream Downloader | Download | In-extension HLS detection and multi-threaded merge to disk (store build for comparison) |
| Video DownloadHelper | Download | General sniffing + vdhcoapp companion (production-grade OSS core) |
| HLS Downloader | Download | HLS detection and download flow |
| Screenity | Recording | Screen/camera recording with annotations |
Key Libraries: Mediabunny (lightweight media processing), Native MediaRecorder API
Implementation Guide: rules/video.md
2. Audio
Common Features: Volume boost, per-tab volume control, audio visualization
| Reference Projects | Type | Highlights |
|---|---|---|
| Better Volume Booster | Volume Boost | Domain memory, mono/stereo toggle |
| Tab Volume | Volume Control | Per-tab control with hotkeys |
Key APIs: Web Audio API (AudioContext, GainNode), chrome.tabCapture
Implementation Guide: rules/audio.md
3. Image
Common Features: Batch download, hover preview, background image extraction, screenshot (visible/full page/element)
| Reference Projects | Type | Highlights |
|---|---|---|
| Image Downloader | Download | Batch download with filtering |
| Pic-Grabber | Download | Shadow DOM, lazy-load support |
| screenshot-extension | Screenshot | Full-page / region capture flow (MIT) |
| webpage-screenshot | Screenshot | Classic full-page capture (ISC) |
Key Techniques: Canvas processing, Shadow DOM traversal, chrome.tabs.captureVisibleTab
Libraries: html2canvas, dom-to-image (for full page screenshots)
Implementation Guide: rules/image.md
4. Translation
Common Features: Page translation, bilingual display, select-to-translate, PDF translation
| Reference Projects | Type | Highlights |
|---|---|---|
| Immersive Translate | Page Translation | Bilingual, PDF support |
| Read Frog | AI Translation | Context-aware explanations |
| OpenAI Translator | AI Translation | ChatGPT-based translation |
Key Libraries: Readability.js (content extraction), PDF.js
Implementation Guide: rules/translation.md
5. Download
Common Features: Resource sniffing, batch download, external downloader integration
| Reference Projects | Type | Highlights |
|---|---|---|
| Cat Catch | Sniffing | Resource sniffing, M3U8/MPD, external downloaders (end-to-end “finish the file”) |
| Live Stream Downloader | HLS | Merge segments in-extension vs. chrome.downloads saving only the playlist |
| Video DownloadHelper | Sniffing + app | Browser + native companion |
| Stream Detector | Detection | Export cookies for aria2 / yt-dlp, etc. |
| Turbo Download Manager v2 | Manager | Multi-connection, resume (direct URLs / files) |
External Tools: N_m3u8DL-RE, yt-dlp, aria2
Implementation Guide: rules/download.md
6. Userscript
Common Features: Script manager, page enhancement, automation
| Reference Projects | Type | Highlights |
|---|---|---|
| Tampermonkey | Manager | Most popular, cloud sync |
| Violentmonkey | Manager | Open source, lightweight |
| Greasemonkey | Manager | Firefox native |
Dev Tools: vite-plugin-monkey - Modern development with HMR
Implementation Guide: rules/userscript.md
7. AI
Common Features: Sidebar chat, page summarization, reading assistant, prompt enhancement
| Reference Projects | Type | Highlights |
|---|---|---|
| BrainyAI | Sidebar | Multi-model sidebar (check Issues/Releases for maintenance) |
| ChatGPT Box | Integration | Selection, summarize, site integrations (GPL-3.0, buildable reference) |
| Scroll | Navigation | LLM web UI navigation helpers (MIT) |
Chrome built-in AI (on-device): Extensions and AI — Prompt, Summarizer, Translator, Language Detector, Writer, Rewriter, Proofreader (status table). Official samples: ai.gemini-on-device, ai.gemini-on-device-summarization.
Built-in AI implementation guide: rules/chrome-built-in-ai.md
Key APIs: OpenAI API, Google Gemini API, Anthropic Claude API, Ollama (local); built-in: LanguageModel (Prompt API), Summarizer, Translator, LanguageDetector, etc. (docs)
SDKs: Vercel AI SDK, LangChain.js, LlamaIndex (TypeScript); typings: @types/dom-chromium-ai
Implementation Guide: rules/ai.md
8. Ad Blocker
Common Features: Ad blocking, tracker blocking, privacy protection, malware protection
| Reference Projects | Type | Highlights |
|---|---|---|
| uBlock Origin | Ad Blocker | Efficient, low resource |
| Privacy Badger | Privacy | Algorithmic tracker detection |
Filter Lists: EasyList, EasyPrivacy, uBlock filters
Implementation Guide: rules/adblocker.md
9. Theme
Common Features: Dark mode, custom CSS injection, theme management
| Reference Projects | Type | Highlights |
|---|---|---|
| Dark Reader | Dark Mode | Smart inversion, dynamic themes |
| Stylus | CSS Manager | UserCSS support, cloud sync |
NPM Package: darkreader - Use in your projects
Implementation Guide: rules/theme.md
10. Email
Common Features: Email notifications, quick preview, multi-account support
| Reference Projects | Type | Highlights |
|---|---|---|
| Mail Checker Plus | Gmail | Unread badge, list preview, mark read, etc. (GPL-3.0, Gmail API reference) |
| gmail-api-chrome-extension | Gmail API | Minimal OAuth + Gmail REST sample (MIT, auth flow learning) |
Key APIs: Gmail API, chrome.identity
Implementation Guide: rules/email.md
11. Game
Common Features: WebAssembly modification, memory editing, auto-click
| Reference Projects | Type | Highlights |
|---|---|---|
| Cetus | WASM Hacking | Memory search, freeze, breakpoints |
Note: Use responsibly, only on single-player/offline games
Implementation Guide: rules/game.md
12. Password Manager
Common Features: Password storage, auto-fill, password generation, encryption
| Reference Projects | Type | Highlights |
|---|---|---|
| Bitwarden | Full Featured | Cloud sync, cross-platform |
| KeePassXC-Browser | Integration | Local password database |
Key APIs: Web Crypto API (AES-256-GCM, PBKDF2)
Implementation Guide: rules/password-manager.md
13. Web3 Wallet
Common Features: Wallet management, transaction signing, DApp connection, multi-chain
| Reference Projects | Type | Highlights |
|---|---|---|
| MetaMask | Wallet | Industry standard, EIP-1193 |
| Rabby | Wallet | Multi-chain, transaction simulation |
| Rainbow | Wallet | Extension source (distinct from mobile app repo) |
Key Libraries: ethers.js, viem
Standards: EIP-1193 (Provider API), EIP-712 (Typed Data)
Implementation Guide: rules/web3.md
Library Choices Summary
| Domain | Preferred | Avoid (in extension) |
|---|---|---|
| Video/Audio processing | Mediabunny | FFmpeg.wasm (large, slow) |
| Recording | Native MediaRecorder | Heavy encoder libs |
| Screenshots | chrome.tabs.captureVisibleTab | Large image libs |
| AI | Remote API calls | Large local models (WASM/ONNX) |
| Translation | Remote API | Bundled NLP models |
| Userscript execution | Sandboxed iframe | Direct eval() |
| Download | chrome.downloads + stream | In-memory buffering |
| Encryption | Web Crypto API | Custom crypto implementations |
Permissions Quick Reference
| Feature | Key Permissions |
|---|---|
| Video Download | downloads, webRequest/declarativeNetRequest |
| Audio Processing | tabCapture, offscreen (MV3) |
| Image Download | downloads, activeTab |
| Translation | activeTab, storage |
| Userscript | <all_urls>, storage |
| AI | sidePanel, storage |
| Ad Blocker | declarativeNetRequest, <all_urls> |
| Theme | activeTab, scripting |
identity, notifications |
|
| Password Manager | storage, activeTab, scripting |
| Web3 | storage, activeTab, scripting |
Additional Resources
- Detailed References: reference.md
- Addfox Best Practices: Use the addfox-best-practices skill for project structure
- Chrome Extension Docs: https://developer.chrome.com/docs/extensions/
- Firefox Extension Docs: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions