Wxt Browser Extensions

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