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

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