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

wxt-browser-extensions skill

safe

/skills/.experimental/wxt-browser-extensions

This skill helps optimize WXT browser extension performance by applying best-practice guidelines across service workers, content scripts, messaging, and

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 (54)

SKILL.md

7.5 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 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`](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
- [`inject-spa-navigation`](references/inject-spa-navigation.md) - Handle SPA navigation with wxt:locationchange

### 3. Messaging Architecture (HIGH)

- [`msg-type-safe-messaging`](references/msg-type-safe-messaging.md) - Use @webext-core/messaging for type-safe protocols
- [`msg-return-true-for-async`](references/msg-return-true-for-async.md) - Return true for async message handlers (raw API)
- [`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) - Group related data into single defineItem
- [`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
- [`store-versioned-migrations`](references/store-versioned-migrations.md) - Use versioning for schema migrations

### 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-imports-module`](references/ts-use-imports-module.md) - Use #imports virtual module and auto-imports
- [`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 provides concise, prioritized performance optimization guidelines for WXT browser extension development. It helps engineers write, review, and refactor extension code to follow proven patterns for service workers, content scripts, messaging, storage, bundling, manifests, UI, and TypeScript. Use it to reduce runtime errors, lower resource usage, and improve responsiveness across extension contexts.

How this skill works

The skill inspects tasks involving WXT extension entrypoints and suggests rules from eight prioritized categories (service worker, injection, messaging, storage, bundle, manifest, UI, TypeScript). It flags high-impact patterns such as synchronous listener registration, context-aware content script injection, type-safe messaging, and storage batching, then recommends concrete refactors and configuration changes. Rules are tagged and ordered so tooling can apply the highest-impact fixes first.

When to use it

Writing new WXT browser extension code or scaffolding features
Refactoring service worker background scripts or lifecycle handling
Implementing or reviewing content script injection and runtime registration
Designing messaging protocols between service worker, popup, and content scripts
Optimizing bundle size, manifest permissions, and UI injection patterns

Best practices

Register service worker listeners synchronously and avoid global in-memory state
Encapsulate content script runtime in a main() function and pick the correct world and runAt timing
Use type-safe messaging libraries and ports for streaming; guard for missing receivers
Group related storage into defined items, watch for changes, and handle quota errors
Split bundles by entrypoint, tree-shake assets, and load WASM dynamically
Request minimal permissions, use optional permissions, and scope web accessible resources

Example use cases

Refactor a persistent background script to a service worker that registers listeners synchronously and uses storage.defineItem
Change content script injection to runtime registration for conditional pages and SPA navigation handling
Replace raw chrome.runtime messaging with @webext-core/messaging and ports for long-lived streams
Reduce extension size by splitting popup, content, and service worker bundles and tree-shaking icons
Migrate storage schema using versioned migrations and batch operations to lower read/write overhead

FAQ

Will the skill automatically change my manifest and code?

The skill provides targeted recommendations and refactor hints; integration with automated code changes depends on your tooling. Treat suggestions as prescriptive guidance to apply in reviews or CI checks.

Which rules should I prioritize first?

Start with CRITICAL categories: Service Worker Lifecycle and Content Script Injection, then Messaging and Storage. These yield the largest runtime and reliability improvements.