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

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