sonofmagic weapp-vite React Best Practices
用途
在微信小程序中建立可预测的 React 19 编译、渲染和组件互操作边界，并用真实构建与 runtime 信号验证结果。
不适用场景
- 通用构建、分包、多平台或 CLI：使用
weapp-vite-best-practices。 - Wevu JSX/TSX 或 Vue SFC：分别使用
wevu-best-practices、weapp-vite-vue-sfc-best-practices。 - 原生项目向 Wevu/Vue SFC 渐进迁移：使用
native-to-weapp-vite-wevu-migration。 - 支付宝、抖音等非微信目标：当前 React runtime 尚未提供兼容承诺。
核心流程
- 先确认项目使用 React 19.2.x、
react-reconciler0.33.x 和@weapp-vite/react，不要引入react-dom。 - 在项目级
weapp.react启用 React owner；同一构建中的.jsx/.tsx全部归 React 编译链，不要与 Wevu JSX 混用。 - 从
auto建立基线：稳定结构生成原生 WXML/binding slots，无法静态证明且不含 bridge 的结构进入 dynamic tree。 - 页面原生入口负责创建 root、转发宿主事件和卸载；React 视图放在相邻 TSX 模块，避免把 Page 生命周期藏进组件树。
- 需要原生或 Wevu 自定义组件时，先在 JSON
usingComponents注册，再在当前 TSX 顶层用字符串字面量调用createNativeComponent。 - 需要 React-backed 小程序组件的默认插槽时使用
Slot；不要假设 scoped slot、model 或动态 tag 已受支持。 - React Compiler 默认保持关闭；只有安装
@swc/core并准备验证 fallback warning、sourcemap 和运行时行为时再启用。 - 按“runtime 单测 -> weapp-vite 编译测试 -> 构建 e2e -> DevTools runtime”逐层验证。
- WebView glass-easel 默认保持关闭；仅在开发者工具与真机基础库均不低于
3.8.12时由用户在宿主 JSON 中成对配置componentFramework与glassEaselWebview，再用wv analyze --glass-easel-check检查 static/dynamic WXML 和 SelectorQuery；React 静态模板沿用共享 WXML 实体转义契约。
关键边界
renderMode: 'dynamic'用于排查 reconciler tree；它不支持原生组件 bridge。renderMode: 'static'遇到无法静态证明的结构应直接失败，不能静默丢失语义。auto中的 bridge 不得出现在条件、列表等动态结构中，也不支持跨文件 bridge 声明。onValueChange映射为bind:value-change，onValueChangeCapture映射为capture-bind:value-change。- React 项目可显式安装
wevu编译.vue，但 TSX 仍归 React owner；互操作通过小程序自定义组件 bridge 完成。
输出
应用本 skill 时，输出必须包含：
- React owner、render mode 与平台边界诊断。
- 页面 root 生命周期与 TSX 文件级改动建议。
- 原生/Wevu bridge 注册和事件契约检查。
- 最小验证命令与需要真实 DevTools 覆盖的行为。
完成标记
- React 依赖组合和
weapp.react配置明确。 - root 在页面卸载时正确 unmount，宿主事件可转发。
- bridge tag 与
usingComponents一致，未使用当前不支持的动态结构。 - Compiler fallback、构建产物和真实 runtime 信号已经区分验证。
参考资料
- 配置、render mode 与 Compiler：
references/config-and-render-modes.md - 原生/Wevu 互操作：
references/component-interop.md - 验证分层：
references/validation-matrix.md