mcpField
W
weapp-vite-react-best-practices

weapp-vite-react-best-practices

github.com/sonofmagicDevelopment273 installsUpdated 6d ago
Repository

About weapp-vite-react-best-practices

weapp-vite-react-best-practices is a practice guide for React 19 projects in WeChat Mini Programs. It defines boundaries for compilation, rendering, and component interoperation, and recommends layered checks from builds to DevTools runtime behavior.

Key features

  1. 01Configure React ownership and render modes
  2. 02Manage page root lifecycle and host events
  3. 03Register native and Wevu component bridges
  4. 04Check component and event interoperation
  5. 05Validate compilation, builds, and runtime in layers

Use cases

  1. 01Set up a React 19 WeChat Mini Program
  2. 02Investigate static and dynamic rendering
  3. 03Connect native or Wevu custom components
  4. 04Verify builds and DevTools runtime behavior

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/sonofmagic/skills --skill weapp-vite-react-best-practices

After installing, type/weapp-vite-react-best-practicesin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
component-interop.md
config-and-render-modes.md
validation-matrix.md

Details

From the project README

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 尚未提供兼容承诺。

核心流程

  1. 当前工作区验证组合为 React 19.3.x、react-reconciler 0.34.x 和 @weapp-vite/react，不要引入 react-dom。
  2. 在项目级 weapp.react 启用 React owner；同一构建中的 .jsx / .tsx 全部归 React 编译链，不要与 Wevu JSX 混用。
  3. 从 auto 建立基线：稳定结构生成原生 WXML/binding slots，无法静态证明且不含 bridge 的结构进入 dynamic tree。
  4. 页面原生入口负责创建 root、转发宿主事件和卸载；React 视图放在相邻 TSX 模块，避免把 Page 生命周期藏进组件树。
  5. 需要原生或 Wevu 自定义组件时，先在 JSON usingComponents 注册，再在当前 TSX 顶层用字符串字面量调用 createNativeComponent。
  6. 需要 React-backed 小程序组件的默认插槽时使用 Slot；不要假设 scoped slot、model 或动态 tag 已受支持。
  7. React Compiler 默认保持关闭；只有安装 @swc/core 并准备验证 fallback warning、sourcemap 和运行时行为时再启用。
  8. 按“runtime 单测 -> weapp-vite 编译测试 -> 构建 e2e -> DevTools runtime”逐层验证。
  9. 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

Comments

Markdown supported