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