wxt-browser-extensions

Original：🇺🇸 English

Translated

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.

4installs

Sourcepproenca/dot-skills

Added on2026-02-04

NPX Install

npx skill4agent add pproenca/dot-skills wxt-browser-extensions

SKILL.md Content

View Translation Comparison →

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


svc-
inject-
msg-
store-
bundle-
manifest-
ui-
ts-

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
```
- 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

3. Messaging Architecture (HIGH)

```
msg-return-true-for-async
```
- Return true for async message handlers
```
msg-type-safe-messaging
```
- Define type-safe message protocols
```
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
```
- Batch storage operations
```
store-watch-for-changes
```
- Use watch() for reactive updates
```
store-handle-quota-errors
```
- Handle storage quota errors

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-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

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information