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