vue3-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vue 3 Best Practices

Vue 3 最佳实践

Comprehensive performance optimization and development guide for Vue 3 applications. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

面向Vue 3应用的全面性能优化与开发指南。包含8个分类下的45条规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Writing new Vue 3 components or composables
Implementing reactive data and computed properties
Reviewing code for performance issues
Refactoring from Vue 2 to Vue 3
Optimizing bundle size or load times
Working with state management (Pinia/Vuex)
Implementing async operations in components

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

编写新的Vue 3组件或可复用组合式函数（composables）
实现响应式数据与计算属性
评审代码以排查性能问题
从Vue 2迁移至Vue 3
优化包体积或加载时间
处理状态管理（Pinia/Vuex）相关工作
在组件中实现异步操作

Rule Categories by Priority

按优先级划分的规则分类


reactivity-
component-
bundle-
composition-
template-
state-
lifecycle-
advanced-

Priority	Category	Impact	Prefix
1	Reactivity Performance	CRITICAL	`reactivity-`
2	Component Optimization	CRITICAL	`component-`
3	Bundle Size & Loading	HIGH	`bundle-`
4	Composition API	MEDIUM-HIGH	`composition-`
5	Template Performance	MEDIUM	`template-`
6	State Management	MEDIUM	`state-`
7	Lifecycle Optimization	LOW-MEDIUM	`lifecycle-`
8	Advanced Patterns	LOW	`advanced-`


reactivity-
component-
bundle-
composition-
template-
state-
lifecycle-
advanced-

优先级	分类	影响程度	前缀
1	响应式性能	关键	`reactivity-`
2	组件优化	关键	`component-`
3	包体积与加载	高	`bundle-`
4	Composition API	中高	`composition-`
5	模板性能	中	`template-`
6	状态管理	中	`state-`
7	生命周期优化	中低	`lifecycle-`
8	高级模式	低	`advanced-`

Quick Reference

快速参考

1. Reactivity Performance (CRITICAL)

1. 响应式性能（关键）

```
reactivity-ref-vs-reactive
```
- Use ref for primitives, reactive for objects
```
reactivity-shallow-ref
```
- Use shallowRef for large immutable objects
```
reactivity-computed-caching
```
- Leverage computed property caching
```
reactivity-watch-vs-watcheffect
```
- Choose appropriate watcher
```
reactivity-unref-performance
```
- Minimize unref calls in hot paths
```
reactivity-readonly-immutable
```
- Use readonly for immutable data

```
reactivity-ref-vs-reactive
```
- 基础类型使用ref，对象类型使用reactive
```
reactivity-shallow-ref
```
- 大型不可变对象使用shallowRef
```
reactivity-computed-caching
```
- 利用计算属性的缓存特性
```
reactivity-watch-vs-watcheffect
```
- 选择合适的监听器
```
reactivity-unref-performance
```
- 在高频路径中尽量减少unref调用
```
reactivity-readonly-immutable
```
- 不可变数据使用readonly

2. Component Optimization (CRITICAL)

2. 组件优化（关键）

```
component-async-components
```
- Use defineAsyncComponent for heavy components
```
component-functional
```
- Use functional components for simple presentational logic
```
component-keep-alive
```
- Cache expensive components with keep-alive
```
component-lazy-hydration
```
- Implement lazy hydration for non-critical components
```
component-prop-validation
```
- Use efficient prop validation
```
component-emit-performance
```
- Optimize event emissions

```
component-async-components
```
- 大型组件使用defineAsyncComponent
```
component-functional
```
- 简单展示型逻辑使用函数式组件
```
component-keep-alive
```
- 使用keep-alive缓存开销较大的组件
```
component-lazy-hydration
```
- 对非关键组件实现懒水化
```
component-prop-validation
```
- 使用高效的属性校验
```
component-emit-performance
```
- 优化事件触发性能

3. Bundle Size & Loading (HIGH)

3. 包体积与加载（高）

```
bundle-tree-shaking
```
- Structure imports for optimal tree-shaking
```
bundle-dynamic-imports
```
- Use dynamic imports for code splitting
```
bundle-plugin-imports
```
- Use unplugin-auto-import for better DX
```
bundle-lodash-imports
```
- Import lodash functions individually
```
bundle-moment-alternatives
```
- Use day.js instead of moment.js
```
bundle-icons-optimization
```
- Optimize icon imports and usage

```
bundle-tree-shaking
```
- 合理组织导入以实现最优摇树优化
```
bundle-dynamic-imports
```
- 使用动态导入实现代码分割
```
bundle-plugin-imports
```
- 使用unplugin-auto-import提升开发体验（DX）
```
bundle-lodash-imports
```
- 单独导入lodash函数
```
bundle-moment-alternatives
```
- 使用day.js替代moment.js
```
bundle-icons-optimization
```
- 优化图标导入与使用

4. Composition API (MEDIUM-HIGH)

4. Composition API（中高）

```
composition-script-setup
```
- Prefer <script setup> for better performance
```
composition-composables-reuse
```
- Extract reusable logic into composables
```
composition-provide-inject
```
- Use provide/inject for dependency injection
```
composition-expose-selectively
```
- Expose only necessary properties
```
composition-reactive-transform
```
- Use reactive transform where appropriate
```
composition-auto-import
```
- Configure auto-imports for better DX

```
composition-script-setup
```
- 优先使用<script setup>以提升性能
```
composition-composables-reuse
```
- 将可复用逻辑提取为composables
```
composition-provide-inject
```
- 使用provide/inject实现依赖注入
```
composition-expose-selectively
```
- 仅暴露必要的属性
```
composition-reactive-transform
```
- 在合适场景下使用响应式转换
```
composition-auto-import
```
- 配置自动导入以提升开发体验（DX）

5. Template Performance (MEDIUM)

5. 模板性能（中）

```
template-v-once
```
- Use v-once for static content
```
template-v-memo
```
- Use v-memo for expensive list rendering
```
template-key-optimization
```
- Optimize v-for keys for performance
```
template-conditional-rendering
```
- Choose v-if vs v-show appropriately
```
template-slot-performance
```
- Optimize slot usage and scoped slots
```
template-directive-optimization
```
- Create efficient custom directives

```
template-v-once
```
- 静态内容使用v-once
```
template-v-memo
```
- 开销较大的列表渲染使用v-memo
```
template-key-optimization
```
- 优化v-for的key以提升性能
```
template-conditional-rendering
```
- 合理选择v-if与v-show
```
template-slot-performance
```
- 优化插槽与作用域插槽的使用
```
template-directive-optimization
```
- 实现高效的自定义指令

6. State Management (MEDIUM)

6. 状态管理（中）

```
state-pinia-optimization
```
- Optimize Pinia store structure
```
state-store-composition
```
- Use store composition patterns
```
state-persistence
```
- Implement efficient state persistence
```
state-normalization
```
- Normalize complex state structures
```
state-subscription
```
- Optimize state subscriptions
```
state-devtools
```
- Configure devtools for debugging

```
state-pinia-optimization
```
- 优化Pinia store结构
```
state-store-composition
```
- 使用store组合模式
```
state-persistence
```
- 实现高效的状态持久化
```
state-normalization
```
- 规范化复杂状态结构
```
state-subscription
```
- 优化状态订阅
```
state-devtools
```
- 配置开发者工具以调试

7. Lifecycle Optimization (LOW-MEDIUM)

7. 生命周期优化（中低）

```
lifecycle-cleanup
```
- Properly cleanup resources in onUnmounted
```
lifecycle-async-setup
```
- Handle async operations in setup
```
lifecycle-watchers-cleanup
```
- Clean up watchers and effects
```
lifecycle-dom-access
```
- Access DOM safely in lifecycle hooks
```
lifecycle-ssr-considerations
```
- Handle SSR lifecycle differences

```
lifecycle-cleanup
```
- 在onUnmounted中正确清理资源
```
lifecycle-async-setup
```
- 在setup中处理异步操作
```
lifecycle-watchers-cleanup
```
- 清理监听器与副作用
```
lifecycle-dom-access
```
- 在生命周期钩子中安全访问DOM
```
lifecycle-ssr-considerations
```
- 处理SSR生命周期差异

8. Advanced Patterns (LOW)

8. 高级模式（低）

```
advanced-teleport-usage
```
- Use Teleport for portal patterns
```
advanced-suspense-async
```
- Implement Suspense with async components
```
advanced-custom-renderer
```
- Create custom renderers when needed
```
advanced-compiler-macros
```
- Use compiler macros effectively
```
advanced-plugin-development
```
- Develop efficient Vue plugins

```
advanced-teleport-usage
```
- 使用Teleport实现门户模式
```
advanced-suspense-async
```
- 结合异步组件实现Suspense
```
advanced-custom-renderer
```
- 在需要时创建自定义渲染器
```
advanced-compiler-macros
```
- 有效使用编译器宏
```
advanced-plugin-development
```
- 开发高效的Vue插件

Framework Integration

框架集成

Vite Integration

Vite集成

Utilize Vite's fast HMR and build optimizations
Configure proper chunk splitting strategies
Use Vite plugins for Vue-specific optimizations

利用Vite的快速热模块替换（HMR）与构建优化
配置合理的代码分割策略
使用针对Vue的Vite插件优化

TypeScript Integration

TypeScript集成

Leverage Vue 3's improved TypeScript support
Use proper type definitions for better DX
Configure TypeScript for optimal build performance

利用Vue 3增强的TypeScript支持
使用正确的类型定义以提升开发体验（DX）
配置TypeScript以实现最优构建性能

Testing Integration

测试集成

Use Vue Test Utils with Composition API
Implement efficient component testing strategies
Optimize test performance and reliability

结合Composition API使用Vue Test Utils
实现高效的组件测试策略
优化测试性能与可靠性

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/reactivity-ref-vs-reactive.md
rules/component-async-components.md
rules/composition-script-setup.md

Each rule file contains:

Brief explanation of why it matters
Incorrect Vue 3 code example with explanation
Correct Vue 3 code example with explanation
Performance impact and measurements
Additional context and Vue 3-specific considerations

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

rules/reactivity-ref-vs-reactive.md
rules/component-async-components.md
rules/composition-script-setup.md

每个规则文件包含：

规则重要性的简要说明
错误的Vue 3代码示例及解释
正确的Vue 3代码示例及解释
性能影响与度量
额外背景信息及Vue 3特定注意事项

Migration from Vue 2

从Vue 2迁移

Special considerations for migrating from Vue 2:

Composition API vs Options API patterns
Reactivity system changes and optimizations
Component definition and registration updates
Event handling and lifecycle changes

从Vue 2迁移的特殊注意事项：

Composition API与Options API模式对比
响应式系统的变更与优化
组件定义与注册的更新
事件处理与生命周期的变更

Performance Monitoring

性能监控

Tools and techniques for monitoring Vue 3 performance:

Vue DevTools integration
Performance profiling with browser tools
Bundle analysis and optimization
Runtime performance monitoring

用于监控Vue 3性能的工具与技术：

Vue DevTools集成
使用浏览器工具进行性能分析
包分析与优化
运行时性能监控