home / skills / pproenca / dot-skills / wxt-browser-extensions

wxt-browser-extensions skill

safe

This skill helps you optimize WXT browser extensions by applying performance guidelines across service workers, content scripts, messaging, and APIs.

npx playbooks add skill pproenca/dot-skills --skill wxt-browser-extensions

Review the files below or copy the command above to add this skill to your agents.

Files (51)

SKILL.md

7.1 KB

---
name: wxt-browser-extensions
description: WXT browser extension performance optimization guidelines. This skill should be used when writing, reviewing, or refactoring WXT browser extension code to ensure optimal performance patterns. Triggers on tasks involving WXT, browser extensions, content scripts, service workers, messaging, and extension APIs.
---

# Community WXT Browser Extensions Best Practices

Comprehensive performance optimization guide for WXT browser extension development. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

## 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`](references/svc-register-listeners-synchronously.md) - Register listeners synchronously to prevent missed events
- [`svc-avoid-global-state`](references/svc-avoid-global-state.md) - Use storage instead of in-memory state
- [`svc-keep-alive-patterns`](references/svc-keep-alive-patterns.md) - Keep service worker alive for long operations
- [`svc-handle-install-update`](references/svc-handle-install-update.md) - Handle install and update lifecycle events
- [`svc-offscreen-documents`](references/svc-offscreen-documents.md) - Use offscreen documents for DOM operations
- [`svc-declarative-net-request`](references/svc-declarative-net-request.md) - Use declarative rules for network blocking

### 2. Content Script Injection (CRITICAL)

- [`inject-use-main-function`](references/inject-use-main-function.md) - Place runtime code inside main() function
- [`inject-choose-correct-world`](references/inject-choose-correct-world.md) - Select ISOLATED or MAIN world appropriately
- [`inject-run-at-timing`](references/inject-run-at-timing.md) - Configure appropriate runAt timing
- [`inject-use-ctx-invalidated`](references/inject-use-ctx-invalidated.md) - Handle context invalidation on update
- [`inject-dynamic-registration`](references/inject-dynamic-registration.md) - Use runtime registration for conditional injection
- [`inject-all-frames`](references/inject-all-frames.md) - Configure allFrames for iframe handling

### 3. Messaging Architecture (HIGH)

- [`msg-return-true-for-async`](references/msg-return-true-for-async.md) - Return true for async message handlers
- [`msg-type-safe-messaging`](references/msg-type-safe-messaging.md) - Define type-safe message protocols
- [`msg-use-tabs-sendmessage`](references/msg-use-tabs-sendmessage.md) - Use tabs.sendMessage for content scripts
- [`msg-use-ports-for-streams`](references/msg-use-ports-for-streams.md) - Use ports for streaming communication
- [`msg-handle-no-receiver`](references/msg-handle-no-receiver.md) - Handle missing message receivers
- [`msg-avoid-circular-messages`](references/msg-avoid-circular-messages.md) - Prevent circular message loops

### 4. Storage Patterns (HIGH)

- [`store-use-define-item`](references/store-use-define-item.md) - Use storage.defineItem for type-safe access
- [`store-choose-storage-area`](references/store-choose-storage-area.md) - Select appropriate storage area
- [`store-batch-operations`](references/store-batch-operations.md) - Batch storage operations
- [`store-watch-for-changes`](references/store-watch-for-changes.md) - Use watch() for reactive updates
- [`store-handle-quota-errors`](references/store-handle-quota-errors.md) - Handle storage quota errors

### 5. Bundle Optimization (MEDIUM-HIGH)

- [`bundle-split-entrypoints`](references/bundle-split-entrypoints.md) - Split code by entrypoint
- [`bundle-analyze-size`](references/bundle-analyze-size.md) - Analyze and monitor bundle size
- [`bundle-tree-shake-icons`](references/bundle-tree-shake-icons.md) - Use direct imports for icon libraries
- [`bundle-externalize-wasm`](references/bundle-externalize-wasm.md) - Load WASM dynamically
- [`bundle-minify-content-scripts`](references/bundle-minify-content-scripts.md) - Minimize content script size

### 6. Manifest Configuration (MEDIUM)

- [`manifest-minimal-permissions`](references/manifest-minimal-permissions.md) - Request minimal permissions
- [`manifest-use-optional-permissions`](references/manifest-use-optional-permissions.md) - Use optional permissions progressively
- [`manifest-web-accessible-resources`](references/manifest-web-accessible-resources.md) - Scope web accessible resources
- [`manifest-content-security-policy`](references/manifest-content-security-policy.md) - Configure CSP correctly
- [`manifest-cross-browser-compatibility`](references/manifest-cross-browser-compatibility.md) - Support multiple browsers

### 7. UI Performance (MEDIUM)

- [`ui-use-shadow-dom`](references/ui-use-shadow-dom.md) - Use Shadow DOM for injected UI
- [`ui-defer-rendering`](references/ui-defer-rendering.md) - Defer popup rendering until needed
- [`ui-cleanup-on-unmount`](references/ui-cleanup-on-unmount.md) - Clean up UI on unmount
- [`ui-sidepanel-persistence`](references/ui-sidepanel-persistence.md) - Preserve sidepanel state
- [`ui-position-fixed-iframe`](references/ui-position-fixed-iframe.md) - Use iframe for complex UI
- [`ui-avoid-layout-thrashing`](references/ui-avoid-layout-thrashing.md) - Batch DOM reads and writes

### 8. TypeScript Patterns (LOW-MEDIUM)

- [`ts-use-browser-not-chrome`](references/ts-use-browser-not-chrome.md) - Use browser namespace over chrome
- [`ts-type-entrypoint-options`](references/ts-type-entrypoint-options.md) - Type entrypoint options explicitly
- [`ts-augment-browser-types`](references/ts-augment-browser-types.md) - Augment types for missing APIs
- [`ts-strict-null-checks`](references/ts-strict-null-checks.md) - Enable strict null checks
- [`ts-import-meta-env`](references/ts-import-meta-env.md) - Use import.meta for build info
- [`ts-avoid-any`](references/ts-avoid-any.md) - Avoid any type in handlers
- [`ts-path-aliases`](references/ts-path-aliases.md) - Use path aliases for imports

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

Overview

This skill delivers prioritized performance optimization guidelines for WXT browser extension development. It consolidates critical rules across service workers, content scripts, messaging, storage, bundling, manifest config, UI, and TypeScript patterns. Use it to drive code reviews, automated refactors, and new extension implementations focused on runtime efficiency and reliability.

How this skill works

The skill inspects tasks involving WXT extension code, content scripts, service workers, messaging, and extension APIs and maps them to a set of prioritized rules. It recommends concrete patterns (e.g., synchronous listener registration, runtime injection strategies, batched storage) and highlights high-impact fixes first. The guidance references modular rules that can be applied selectively during writing, reviewing, or refactoring.

When to use it

Creating or refactoring service worker background scripts
Designing or injecting content scripts into web pages
Implementing messaging between extension contexts (ports, sendMessage)
Configuring manifest permissions, resources, or CSP
Optimizing bundle size and runtime startup for extension entrypoints

Best practices

Register service worker listeners synchronously and avoid relying on global in-memory state
Place runtime code inside a main() for content scripts and choose the correct execution world
Use ports for streaming or long-lived channels and return true for async handlers
Batch storage operations, choose the right storage area, and watch for changes instead of polling
Split bundles by entrypoint, tree-shake icon imports, and minify content scripts
Request minimal and optional permissions; scope web-accessible resources and enforce CSP

Example use cases

Refactor a persistent background script into a service-worker-friendly pattern with keep-alive and storage-backed state
Convert static content script injection to runtime registration for conditional loading and iframe handling
Replace ad-hoc messaging loops with typed protocols and port-based streams to avoid circular messages
Reduce popup and content script payload by splitting entrypoints and dynamic-loading WASM or heavy libs
Audit manifest for minimal permissions and cross-browser compatibility while tightening web accessible resources

FAQ

Which rules should I prioritize first?

Start with Service Worker Lifecycle and Content Script Injection rules (critical impact), then address Messaging and Storage patterns. Bundle and manifest optimizations follow.

How do I handle long-running tasks in a service worker?

Use keep-alive patterns, offscreen documents when DOM is required, and persist intermediate state to storage instead of globals to avoid termination issues.