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 |