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

sw-

content-

msg-

storage-

net-

mem-

ui-

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