wevu-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

wevu-best-practices

wevu最佳实践

Overview

概述

Write mini-program business logic with Vue-style ergonomics while respecting wevu runtime constraints. Keep hooks, state updates, and component contracts explicit.

以Vue风格的易用性编写小程序业务逻辑，同时遵守wevu运行时约束。保持钩子、状态更新和组件契约的明确性。

Workflow

工作流程

Set runtime conventions first

Import runtime APIs only from
```
wevu
```
.
Use
```
defineComponent
```
as the registration model for both pages and components.
Keep
```
data
```
as a function when using options-style state.

Use correct component/page boundaries

Define mini-program config via Script Setup JSON macros first.

For App/Page/Component SFC, prefer

defineAppJson

definePageJson

defineComponentJson

over

<json>

blocks.

Declare
```
usingComponents
```
through JSON config, not script-side ESM component registration.
Keep page hooks only in page contexts.

Keep reactive updates predictable

Use
```
ref/reactive/computed
```
for state and derive template data from them.
Register lifecycle hooks synchronously inside
```
setup()
```
.
Use explicit bindings for forms/events when semantics are complex.

Design events and two-way binding intentionally

Use
```
ctx.emit(event, detail, options)
```
with mini-program event semantics.
For reusable field bindings, prefer
```
bindModel
```
/
```
useBindModel
```
with explicit event and parser.
Avoid assuming full Vue web
```
v-model
```
feature parity in mini-program templates.

Structure stores for maintainability

Prefer Setup Store for simple domains and strong inference.
Use
```
storeToRefs
```
when destructuring state/getters.
Add
```
createStore()
```
only when global plugin/persistence hooks are needed.

Handle compatibility and testing explicitly

Do not use DOM/browser-only APIs in runtime logic.
For Node/Vitest tests, stub
```
Component
```
/
```
wx
```
when testing runtime bridges.
Treat lifecycle and provide/inject differences as platform constraints, not bugs.

先设置运行时约定

仅从
```
wevu
```
导入运行时API。
使用
```
defineComponent
```
作为页面和组件的注册模型。
当使用选项式状态时，将
```
data
```
保持为函数形式。

使用正确的组件/页面边界

首先通过Script Setup JSON宏定义小程序配置。
对于App/Page/Component SFC，优先使用
```
defineAppJson
```
/
```
definePageJson
```
/
```
defineComponentJson
```
而非
```
<json>
```
块。
通过JSON配置声明
```
usingComponents
```
，而非脚本端ESM组件注册。
仅在页面上下文中保留页面钩子。

保持响应式更新可预测

使用
```
ref/reactive/computed
```
管理状态，并从中派生模板数据。
在
```
setup()
```
内同步注册生命周期钩子。
当语义复杂时，为表单/事件使用显式绑定。

有意设计事件和双向绑定

结合小程序事件语义使用
```
ctx.emit(event, detail, options)
```
。
对于可复用的字段绑定，优先使用带显式事件和解析器的
```
bindModel
```
/
```
useBindModel
```
。
不要假设小程序模板中完全支持Vue Web的
```
v-model
```
功能。

为可维护性构建状态管理库

对于简单领域和强推断，优先使用Setup Store。
解构状态/ getter时使用
```
storeToRefs
```
。
仅在需要全局插件/持久化钩子时添加
```
createStore()
```
。

显式处理兼容性和测试

不要在运行时逻辑中使用仅DOM/浏览器的API。
对于Node/Vitest测试，在测试运行时桥接时模拟
```
Component
```
/
```
wx
```
。
将生命周期和provide/inject的差异视为平台约束，而非bug。

Guardrails

防护措施

Avoid hook registration after
```
await
```
in
```
setup()
```
.
Avoid direct state destructuring without
```
storeToRefs
```
for stores.
Avoid relying on undocumented Vue web-only behavior in templates or lifecycle timing.

避免在
```
setup()
```
中的
```
await
```
之后注册钩子。
避免在不使用
```
storeToRefs
```
的情况下直接解构状态管理库的状态。
避免在模板或生命周期时序中依赖未文档化的仅Vue Web的行为。

Completion Checklist

完成检查清单

API imports come from
```
wevu
```
, not
```
vue
```
runtime in business code.
Page/component JSON config strategy is consistent.
Hook registration timing is synchronous and predictable.
Store usage follows singleton +
```
storeToRefs
```
conventions.
Template bindings match mini-program-supported semantics.

业务代码中的API导入来自
```
wevu
```
，而非
```
vue
```
运行时。
页面/组件JSON配置策略一致。
钩子注册时序同步且可预测。
状态管理库的使用遵循单例+
```
storeToRefs
```
约定。
模板绑定符合小程序支持的语义。

References

参考资料

```
references/component-patterns.md
```
```
references/store-patterns.md
```
```
references/troubleshooting-checks.md
```

```
references/component-patterns.md
```
```
references/store-patterns.md
```
```
references/troubleshooting-checks.md
```