vue-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vue Best Practices

Vue最佳实践

Comprehensive performance optimization guide for Vue.js applications. Contains 40+ rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

Vue.js应用程序综合性能优化指南。包含8个类别下的40+条规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Writing new Vue components
Implementing reactive state and computed properties
Reviewing code for performance issues
Refactoring existing Vue code
Optimizing rendering and re-renders
Working with Composition API or Options API

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

编写新的Vue组件
实现响应式状态与计算属性
审查代码以排查性能问题
重构现有Vue代码
优化渲染与重渲染
使用Composition API或Options API

Rule Categories by Priority

按优先级划分的规则类别


reactivity-
component-
computed-
template-
composable-
state-
async-
advanced-

Priority	Category	Impact	Prefix
1	Reactivity Fundamentals	CRITICAL	`reactivity-`
2	Component Performance	CRITICAL	`component-`
3	Computed & Watchers	HIGH	`computed-`
4	Template Optimization	MEDIUM-HIGH	`template-`
5	Composition API Patterns	MEDIUM	`composable-`
6	State Management	MEDIUM	`state-`
7	Async & Data Fetching	LOW-MEDIUM	`async-`
8	Advanced Patterns	LOW	`advanced-`


reactivity-
component-
computed-
template-
composable-
state-
async-
advanced-

优先级	类别	影响程度	前缀
1	响应式基础	关键	`reactivity-`
2	组件性能	关键	`component-`
3	计算属性与监听器	高	`computed-`
4	模板优化	中高	`template-`
5	Composition API 模式	中	`composable-`
6	状态管理	中	`state-`
7	异步与数据获取	中低	`async-`
8	高级模式	低	`advanced-`

Quick Reference

快速参考

1. Reactivity Fundamentals (CRITICAL)

1. 响应式基础（关键）

```
reactivity-ref-vs-reactive
```
- Use ref() for primitives, reactive() for objects
```
reactivity-avoid-destructure
```
- Don't destructure reactive objects
```
reactivity-toRefs
```
- Use toRefs() when destructuring is needed
```
reactivity-shallowRef
```
- Use shallowRef() for large non-reactive data
```
reactivity-raw-values
```
- Use toRaw() for read-only operations on large data

```
reactivity-ref-vs-reactive
```
- 对基本类型使用ref()，对对象使用reactive()
```
reactivity-avoid-destructure
```
- 不要解构响应式对象
```
reactivity-toRefs
```
- 当需要解构时使用toRefs()
```
reactivity-shallowRef
```
- 对大型非响应式数据使用shallowRef()
```
reactivity-raw-values
```
- 对大型数据执行只读操作时使用toRaw()

2. Component Performance (CRITICAL)

2. 组件性能（关键）

```
component-v-once
```
- Use v-once for static content
```
component-v-memo
```
- Use v-memo for expensive list items
```
component-async
```
- Use defineAsyncComponent for heavy components
```
component-keep-alive
```
- Cache component state with KeepAlive
```
component-functional
```
- Prefer functional components for stateless UI

```
component-v-once
```
- 对静态内容使用v-once
```
component-v-memo
```
- 对开销大的列表项使用v-memo
```
component-async
```
- 对重型组件使用defineAsyncComponent
```
component-keep-alive
```
- 使用KeepAlive缓存组件状态
```
component-functional
```
- 无状态UI优先使用函数式组件

3. Computed & Watchers (HIGH)

3. 计算属性与监听器（高）

```
computed-cache
```
- Use computed() for derived values, not methods
```
computed-getter-only
```
- Avoid setters in computed when possible
```
computed-dependencies
```
- Minimize computed dependencies
```
watch-immediate
```
- Avoid immediate watchers, use computed instead
```
watch-deep-avoid
```
- Avoid deep watchers on large objects
```
watch-cleanup
```
- Always cleanup async watchers

```
computed-cache
```
- 对派生值使用computed()，而非方法
```
computed-getter-only
```
- 尽可能避免在computed中使用setter
```
computed-dependencies
```
- 最小化computed的依赖项
```
watch-immediate
```
- 避免使用immediate监听器，改用computed
```
watch-deep-avoid
```
- 避免对大型对象使用深度监听器
```
watch-cleanup
```
- 始终清理异步监听器

4. Template Optimization (MEDIUM-HIGH)

4. 模板优化（中高）

```
template-v-show-vs-if
```
- v-show for frequent toggles, v-if for rare
```
template-key-attribute
```
- Always use unique keys in v-for
```
template-avoid-v-if-v-for
```
- Never use v-if and v-for on same element
```
template-static-hoisting
```
- Let compiler hoist static content
```
template-event-modifiers
```
- Use event modifiers instead of JS handlers

```
template-v-show-vs-if
```
- 频繁切换用v-show，极少切换用v-if
```
template-key-attribute
```
- 在v-for中始终使用唯一key
```
template-avoid-v-if-v-for
```
- 永远不要在同一元素上同时使用v-if和v-for
```
template-static-hoisting
```
- 让编译器提升静态内容
```
template-event-modifiers
```
- 使用事件修饰符替代JS处理函数

5. Composition API Patterns (MEDIUM)

5. Composition API 模式（中）

```
composable-single-responsibility
```
- One concern per composable
```
composable-return-refs
```
- Return refs, not reactive objects
```
composable-cleanup
```
- Handle cleanup in composables
```
composable-lazy-init
```
- Lazy initialize expensive resources
```
composable-provide-inject
```
- Use provide/inject for deep prop drilling

```
composable-single-responsibility
```
- 每个composable只处理一个关注点
```
composable-return-refs
```
- 返回refs，而非响应式对象
```
composable-cleanup
```
- 在composable中处理清理逻辑
```
composable-lazy-init
```
- 延迟初始化开销大的资源
```
composable-provide-inject
```
- 使用provide/inject解决深层props透传问题

6. State Management (MEDIUM)

6. 状态管理（中）

```
state-pinia-stores
```
- Split stores by domain
```
state-getters
```
- Use getters for computed state
```
state-actions-mutations
```
- Keep mutations simple, logic in actions
```
state-subscription-cleanup
```
- Cleanup store subscriptions

```
state-pinia-stores
```
- 按领域拆分stores
```
state-getters
```
- 对计算后的状态使用getters
```
state-actions-mutations
```
- 保持mutations简单，逻辑放在actions中
```
state-subscription-cleanup
```
- 清理store订阅

7. Async & Data Fetching (LOW-MEDIUM)

7. 异步与数据获取（中低）

```
async-suspense
```
- Use Suspense for async component loading
```
async-error-boundaries
```
- Handle async errors gracefully
```
async-stale-while-revalidate
```
- Implement SWR pattern for data fetching
```
async-abort-controller
```
- Cancel pending requests on unmount

```
async-suspense
```
- 使用Suspense处理异步组件加载
```
async-error-boundaries
```
- 优雅处理异步错误
```
async-stale-while-revalidate
```
- 实现SWR模式进行数据获取
```
async-abort-controller
```
- 在组件卸载时取消待处理请求

8. Advanced Patterns (LOW)

8. 高级模式（低）

```
advanced-custom-directives
```
- Create directives for DOM manipulation
```
advanced-render-functions
```
- Use render functions for dynamic templates
```
advanced-teleport
```
- Use Teleport for modals and overlays
```
advanced-transition-groups
```
- Optimize list transitions

```
advanced-custom-directives
```
- 创建自定义指令处理DOM操作
```
advanced-render-functions
```
- 使用渲染函数处理动态模板
```
advanced-teleport
```
- 使用Teleport处理模态框与浮层
```
advanced-transition-groups
```
- 优化列表过渡效果

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/reactivity-ref-vs-reactive.md
rules/component-v-memo.md
rules/_sections.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

阅读单个规则文件获取详细说明与代码示例：

rules/reactivity-ref-vs-reactive.md
rules/component-v-memo.md
rules/_sections.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例及解释
正确代码示例及解释
额外背景信息与参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有展开规则的完整指南：

AGENTS.md