Chrome Developer Relations Chrome Extensions Best Practices
Comprehensive performance optimization guide for Chrome Extensions (Manifest V3), maintained by Chrome Developer Relations. Contains 40+ rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
When to Apply
Reference these guidelines when:
Writing new Chrome extension code Migrating from Manifest V2 to Manifest V3 Optimizing service worker lifecycle and state management Implementing content scripts for page interaction Debugging performance issues in extensions Rule Categories by Priority Priority Category Impact Prefix 1 Service Worker Lifecycle CRITICAL sw- 2 Content Script Optimization CRITICAL content- 3 Message Passing Efficiency HIGH msg- 4 Storage Operations HIGH storage- 5 Network & Permissions MEDIUM-HIGH net- 6 Memory Management MEDIUM mem- 7 UI Performance MEDIUM ui- 8 API Usage Patterns LOW-MEDIUM api- Quick Reference 1. Service Worker Lifecycle (CRITICAL) sw-persist-state-storage - Persist state with chrome.storage instead of global variables sw-avoid-keepalive - Avoid artificial service worker keep-alive patterns sw-use-alarms-api - Use chrome.alarms instead of setTimeout/setInterval sw-return-true-async - Return true from message listeners for async responses sw-register-listeners-toplevel - Register event listeners at top level sw-use-offscreen-for-dom - Use offscreen documents for DOM APIs 2. Content Script Optimization (CRITICAL) content-use-specific-matches - Use specific URL match patterns content-use-document-idle - Use document_idle for content script injection content-programmatic-injection - Prefer programmatic injection over manifest declaration content-minimize-script-size - Minimize content script bundle size content-batch-dom-operations - Batch DOM operations to minimize reflows content-use-mutation-observer - Use MutationObserver instead of polling 3. Message Passing Efficiency (HIGH) msg-use-ports-for-frequent - Use port connections for frequent message exchange msg-minimize-payload-size - Minimize message payload size msg-debounce-frequent-events - Debounce high-frequency events before messaging msg-check-lasterror - Always check chrome.runtime.lastError msg-avoid-broadcast-to-all-tabs - Avoid broadcasting messages to all tabs 4. Storage Operations (HIGH) storage-batch-operations - Batch storage operations instead of individual calls storage-choose-correct-type - Choose the correct storage type for your use case storage-cache-frequently-accessed - Cache frequently accessed storage values storage-use-session-for-temp - Use storage.session for temporary runtime data storage-avoid-storing-large-blobs - Avoid storing large binary blobs 5. Network & Permissions (MEDIUM-HIGH) net-use-declarativenetrequest - Use declarativeNetRequest instead of webRequest net-request-minimal-permissions - Request minimal required permissions net-use-activetab - Use activeTab permission instead of broad host permissions net-limit-csp-modifications - Avoid modifying Content Security Policy headers 6. Memory Management (MEDIUM) mem-cleanup-event-listeners - Clean up event listeners when content script unloads mem-avoid-detached-dom - Avoid holding references to detached DOM nodes mem-avoid-closure-leaks - Avoid accidental closure memory leaks mem-clear-intervals-timeouts - Clear intervals and timeouts on cleanup mem-use-weak-collections - Use WeakMap and WeakSet for DOM element references 7. UI Performance (MEDIUM) ui-minimize-popup-bundle - Minimize popup bundle size for fast startup ui-render-with-cached-data - Render popup UI with cached data first ui-batch-badge-updates - Batch badge updates to avoid flicker ui-use-options-page-lazy - Lazy load options page sections 8. API Usage Patterns (LOW-MEDIUM) api-use-promises-over-callbacks - Use promise-based API calls over callbacks api-query-tabs-efficiently - Query tabs with specific filters api-avoid-redundant-api-calls - Avoid redundant API calls in loops api-use-alarms-minperiod - Respect alarms API minimum period api-handle-context-invalidated - Handle extension context invalidated errors api-use-declarative-content - Use declarative content API for page actions How to Use
Read individual reference files for detailed explanations and code examples:
Section definitions - Category structure and impact levels Rule template - Template for adding new rules Full Compiled Document
For a complete guide with all rules in a single document, see AGENTS.md.
Reference Files File Description AGENTS.md Complete compiled guide with all rules references/_sections.md Category definitions and ordering assets/templates/_template.md Template for new rules metadata.json Version and reference information