Chrome Extension Best Practices

Comprehensive performance and code quality guide for Chrome Extensions (Manifest V3). Contains 67 rules across 12 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-
9	Code Style & Naming	MEDIUM	style-
10	Component Patterns	MEDIUM	comp-
11	Error Handling	HIGH	err-
12	Testing Patterns	MEDIUM	test-

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

9. Code Style & Naming (MEDIUM)

• style-boolean-naming - Use is/has/should prefixes for boolean variables
• style-cache-naming - Use consistent cache variable naming
• style-constants - Define constants for magic values
• style-directory-structure - Organize code by feature/layer
• style-file-naming - Use consistent file naming conventions
• style-function-naming - Use descriptive function names
• style-import-type - Use type-only imports for types
• style-index-entry-points - Use index files for module entry points
• style-message-enums - Use enums for message types
• style-type-naming - Use PascalCase for types and interfaces

10. Component Patterns (MEDIUM)

• comp-adapter-interface - Use adapter pattern for browser APIs
• comp-content-script-structure - Structure content scripts consistently
• comp-css-class-patterns - Use BEM or prefixed CSS classes
• comp-manager-class - Use manager classes for complex state
• comp-type-guards - Use type guards for runtime validation
• comp-ui-components - Create reusable UI components

11. Error Handling (HIGH)

• err-context-invalidation - Handle extension context invalidation
• err-early-return - Use early returns for error handling
• err-null-coalescing - Use nullish coalescing for defaults
• err-promise-barrier - Use promise barriers for coordination
• err-storage-operations - Handle storage operation failures
• err-url-parsing - Safely parse URLs with try/catch
• err-validation-pattern - Validate inputs at boundaries

12. Testing Patterns (MEDIUM)

• test-browser-api-mocking - Mock chrome APIs in tests
• test-organization - Organize tests by feature
• test-validation-functions - Test validation functions thoroughly

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