Chrome Extensions (Manifest V3) performance and code quality guidelines. Use when writing, reviewing, or refactoring Chrome extension code including service…
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
don't have the plugin yet? install it then click "run inline in claude" again.