wxt-browser-extensions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Community WXT Browser Extensions Best Practices

社区WXT浏览器扩展最佳实践

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.

WXT浏览器扩展开发综合性能优化指南。包含8个类别共45条规则，按影响优先级排序，可指导自动化重构与代码生成。

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

在以下场景中参考本指南：

编写新的WXT浏览器扩展代码
实现Service Worker后台脚本
向网页中注入content scripts（内容脚本）
配置扩展上下文之间的消息通信
配置清单权限与资源

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


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

优先级	类别	影响程度	前缀
1	Service Worker生命周期	关键	`svc-`
2	Content Script注入	关键	`inject-`
3	消息通信架构	高	`msg-`
4	存储模式	高	`store-`
5	打包优化	中高	`bundle-`
6	清单配置	中	`manifest-`
7	UI性能	中	`ui-`
8	TypeScript模式	中低	`ts-`

Quick Reference

快速参考

1. Service Worker Lifecycle (CRITICAL)

1. Service Worker生命周期（关键）

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

```
svc-register-listeners-synchronously
```
- 同步注册监听器以避免错过事件
```
svc-avoid-global-state
```
- 使用存储而非内存状态
```
svc-keep-alive-patterns
```
- 保持Service Worker存活以处理长时间操作
```
svc-handle-install-update
```
- 处理安装与更新生命周期事件
```
svc-offscreen-documents
```
- 使用离屏文档处理DOM操作
```
svc-declarative-net-request
```
- 使用声明式规则拦截网络请求

2. Content Script Injection (CRITICAL)

2. Content Script注入（关键）

```
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-use-main-function
```
- 将运行时代码放入main()函数中
```
inject-choose-correct-world
```
- 合理选择ISOLATED或MAIN环境
```
inject-run-at-timing
```
- 配置合适的runAt时机
```
inject-use-ctx-invalidated
```
- 在更新时处理上下文失效问题
```
inject-dynamic-registration
```
- 使用运行时注册实现条件注入
```
inject-all-frames
```
- 配置allFrames以处理iframe

3. Messaging Architecture (HIGH)

3. 消息通信架构（高）

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

```
msg-return-true-for-async
```
- 异步消息处理函数返回true
```
msg-type-safe-messaging
```
- 定义类型安全的消息协议
```
msg-use-tabs-sendmessage
```
- 对content scripts使用tabs.sendMessage
```
msg-use-ports-for-streams
```
- 使用端口实现流式通信
```
msg-handle-no-receiver
```
- 处理消息接收方不存在的情况
```
msg-avoid-circular-messages
```
- 避免消息循环

4. Storage Patterns (HIGH)

4. 存储模式（高）

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

```
store-use-define-item
```
- 使用storage.defineItem实现类型安全的访问
```
store-choose-storage-area
```
- 选择合适的存储区域
```
store-batch-operations
```
- 批量处理存储操作
```
store-watch-for-changes
```
- 使用watch()实现响应式更新
```
store-handle-quota-errors
```
- 处理存储配额错误

5. Bundle Optimization (MEDIUM-HIGH)

5. 打包优化（中高）

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

```
bundle-split-entrypoints
```
- 按入口点拆分代码
```
bundle-analyze-size
```
- 分析并监控打包体积
```
bundle-tree-shake-icons
```
- 直接导入图标库以实现树摇优化
```
bundle-externalize-wasm
```
- 动态加载WASM
```
bundle-minify-content-scripts
```
- 最小化content scripts体积

6. Manifest Configuration (MEDIUM)

6. 清单配置（中）

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

```
manifest-minimal-permissions
```
- 请求最小权限
```
manifest-use-optional-permissions
```
- 逐步使用可选权限
```
manifest-web-accessible-resources
```
- 限制可访问的Web资源范围
```
manifest-content-security-policy
```
- 正确配置CSP
```
manifest-cross-browser-compatibility
```
- 支持多浏览器

7. UI Performance (MEDIUM)

7. UI性能（中）

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

```
ui-use-shadow-dom
```
- 使用Shadow DOM实现注入式UI
```
ui-defer-rendering
```
- 延迟弹窗渲染直到需要时
```
ui-cleanup-on-unmount
```
- 在卸载时清理UI
```
ui-sidepanel-persistence
```
- 保留侧边栏状态
```
ui-position-fixed-iframe
```
- 使用iframe实现复杂UI
```
ui-avoid-layout-thrashing
```
- 批量处理DOM读写以避免布局抖动

8. TypeScript Patterns (LOW-MEDIUM)

8. TypeScript模式（中低）

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

```
ts-use-browser-not-chrome
```
- 使用browser命名空间而非chrome
```
ts-type-entrypoint-options
```
- 显式为入口点选项添加类型
```
ts-augment-browser-types
```
- 扩展缺失API的类型定义
```
ts-strict-null-checks
```
- 启用严格空值检查
```
ts-import-meta-env
```
- 使用import.meta获取构建信息
```
ts-avoid-any
```
- 在处理函数中避免使用any类型
```
ts-path-aliases
```
- 使用路径别名简化导入

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

文件	描述
references/_sections.md	类别定义与排序
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息