WXT browser extension performance optimization guidelines. This skill should be used when writing, reviewing, or refactoring WXT browser extension code to…
Community WXT Browser Extensions Best Practices Comprehensive performance optimization guide for WXT browser extension development. Contains 49 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation. Updated for WXT v0.20+. When to Apply Reference these guidelines when: Writing new WXT browser extension code Implementing service worker background scripts Injecting content scripts into web pages Setting up messaging between extension contexts Configuring manifest permissions and resources Rule Categories by Priority Priority Category Impact Prefix 1 Service Worker Lifecycle CRITICAL svc- 2 Content Script Injection CRITICAL inject- 3 Messaging Architecture HIGH msg- 4 Storage Patterns HIGH store- 5 Bundle Optimization MEDIUM-HIGH bundle- 6 Manifest Configuration MEDIUM manifest- 7 UI Performance MEDIUM ui- 8 TypeScript Patterns LOW-MEDIUM ts- Quick Reference 1. Service Worker Lifecycle (CRITICAL) svc-register-listeners-synchronously - Register listeners synchronously to prevent missed events svc-avoid-global-state - Use storage instead of in-memory state svc-keep-alive-patterns - Keep service worker alive for long operations svc-handle-install-update - Handle install and update lifecycle events svc-offscreen-documents - Use offscreen documents for DOM operations svc-declarative-net-request - Use declarative rules for network blocking 2. Content Script Injection (CRITICAL) inject-use-main-function - Place runtime code inside main() function inject-choose-correct-world - Select ISOLATED or MAIN world appropriately inject-run-at-timing - Configure appropriate runAt timing inject-use-ctx-invalidated - Handle context invalidation on update inject-dynamic-registration - Use runtime registration for conditional injection inject-all-frames - Configure allFrames for iframe handling inject-spa-navigation - Handle SPA navigation with wxt:locationchange 3. Messaging Architecture (HIGH) msg-type-safe-messaging - Use @webext-core/messaging for type-safe protocols msg-return-true-for-async - Return true for async message handlers (raw API) msg-use-tabs-sendmessage - Use tabs.sendMessage for content scripts msg-use-ports-for-streams - Use ports for streaming communication msg-handle-no-receiver - Handle missing message receivers msg-avoid-circular-messages - Prevent circular message loops 4. Storage Patterns (HIGH) store-use-define-item - Use storage.defineItem for type-safe access store-choose-storage-area - Select appropriate storage area store-batch-operations - Group related data into single defineItem store-watch-for-changes - Use watch() for reactive updates store-handle-quota-errors - Handle storage quota errors store-versioned-migrations - Use versioning for schema migrations 5. Bundle Optimization (MEDIUM-HIGH) bundle-split-entrypoints - Split code by entrypoint bundle-analyze-size - Analyze and monitor bundle size bundle-tree-shake-icons - Use direct imports for icon libraries bundle-externalize-wasm - Load WASM dynamically bundle-minify-content-scripts - Minimize content script size 6. Manifest Configuration (MEDIUM) manifest-minimal-permissions - Request minimal permissions manifest-use-optional-permissions - Use optional permissions progressively manifest-web-accessible-resources - Scope web accessible resources manifest-content-security-policy - Configure CSP correctly manifest-cross-browser-compatibility - Support multiple browsers 7. UI Performance (MEDIUM) ui-use-shadow-dom - Use Shadow DOM for injected UI ui-defer-rendering - Defer popup rendering until needed ui-cleanup-on-unmount - Clean up UI on unmount ui-sidepanel-persistence - Preserve sidepanel state ui-position-fixed-iframe - Use iframe for complex UI ui-avoid-layout-thrashing - Batch DOM reads and writes 8. TypeScript Patterns (LOW-MEDIUM) ts-use-imports-module - Use #imports virtual module and auto-imports ts-use-browser-not-chrome - Use browser namespace over chrome ts-type-entrypoint-options - Type entrypoint options explicitly ts-augment-browser-types - Augment types for missing APIs ts-strict-null-checks - Enable strict null checks ts-import-meta-env - Use import.meta for build info ts-avoid-any - Avoid any type in handlers ts-path-aliases - Use path aliases for imports 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 Reference Files File Description 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.