weapp-vite-vue-sfc-best-practices

Overview

Implement Vue SFC in mini-programs with a two-layer mindset: compile-time rules (weapp-vite) and runtime behavior (wevu). Keep SFC structure explicit, avoid web-only assumptions, and optimize for predictable output.

Workflow

1. Establish SFC boundaries

• Treat <template>/<script>/<style>/<json> as separate responsibilities.
• Keep mini-program config in <json> or Script Setup JSON macros.
• Avoid script-side ESM component registration for mini-program components.

2. Choose script strategy

• Prefer <script setup lang="ts"> for page/component logic.
• Import runtime APIs from wevu (not vue) in business logic.
• Keep hook registration synchronous in setup().

3. Configure JSON correctly

• Use one macro family per SFC: definePageJson or defineComponentJson or defineAppJson.
• Keep macro calls top-level and single-argument.
• Remember macro output has highest merge priority over <json> and auto-inferred config.

4. Author templates with compatibility constraints

• Use mini-program component/event semantics.
• For v-model, only use assignable left values (x, x.y, x[i]).
• Avoid relying on unsupported patterns (v-model modifiers/arguments, v-bind="object" expansion).

5. Coordinate with wevu runtime

• Use defineComponent model for page/component registration.
• Use explicit value/event bindings or bindModel for complex form components.
• Keep page event hooks aligned with page context and trigger conditions.

6. Troubleshoot by stage

• Compile-time issues: check macro usage, usingComponents, template syntax limits.
• Runtime issues: check API import source, hook timing, setData/diff expectations.
• IDE/type issues: check Volar plugin and vueCompilerOptions.lib alignment.

Guardrails

• Do not treat mini-program component registration like web Vue component registration.
• Do not register hooks after await in setup().
• Do not assume web Vue template features are fully available in mini-program compilation.
• Do not mix multiple JSON macro families in one SFC.

Completion Checklist

• SFC config path is clear (<json> or one JSON macro family).
• usingComponents strategy is deterministic and path-safe.
• Template usage avoids unsupported directive forms.
• Runtime API imports come from wevu.
• Hook timing and page/component context are valid.

References

• references/macro-config-checklist.md
• references/template-compat-matrix.md
• references/troubleshooting-playbook.md