SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsweapp-vite-vue-sfc-best-practices

weapp-vite-vue-sfc-best-practices

Frontend & websites

View repository

Updated 10-16 16:10

About this skill

weapp-vite-vue-sfc-best-practices

Purpose

Write pages and components in mini program projects with Vue SFC that are "predictable to compile, verifiable at runtime, and type-traceable".

When to use

  • When the user asks how a .vue file should be written.
  • When the user asks how to choose between JSON macros and <json> .
  • When the user asks how to configure definePageMeta / layout.
  • When the user hits template compatibility or compile errors.
  • When the user hits .weapp-vite type output, component declarations, or route type drift.
  • When the user wants to use uni-app Vue SFC component libraries such as Wot UI and uview-plus in WeChat mini programs and on the Web.
  • When the user wants to use template-only .vue、<script lang="jsx"> / <script setup lang="tsx">, or handle multi-platform SFC compilation differences.

Not applicable scenarios

This skill focuses on SFC authoring and compile-time compatibility.

  • Project-level build configuration: use weapp-vite-best-practices。
  • wevu Lifecycle and store: use wevu-best-practices。
  • Migration planning: use native-to-weapp-vite-wevu-migration。
  • React JSX/TSX after the project enables weapp.react : use weapp-vite-react-best-practices。

Core workflow

  1. First determine the problem stage:
    • Compile time: macros, templates,usingComponents
    • Runtime: events, hooks, reactivity
    • Tooling layer: Volar,.weapp-vite、typed outputs
  2. By default use <script setup lang="ts">。
    • Template-only SFC is allowed to have no script block;wv prepare must be scanned as an SFC template; do not mistakenly hand template text to the JSX parser.
    • Wevu JSX/TSX and JSX/TSX inside SFC belong to the Wevu compiler; project-level weapp.react once enabled, standalone .jsx/.tsx belongs to the React owner.
  3. Prefer macros for JSON:defineAppJson、definePageJson、defineComponentJson; page metadata goes through definePageMeta。
  4. Apply template compatibility rules:
    • v-model can only act on assignable lvalues
    • Do not assume all Web Vue template features are available
    • usingComponents go through JSON macros / auto-import, not the Web Vue registration approach
    • In the documentation of third-party mini program UI libraries (such as TDesign Mini Program and Vant Weapp), TNode、slotand custom content are usually mini program native slots or attribute rendering; do not treat them as Vue scoped slots by default
    • Third-party uni-app Vue SFC component libraries and native mini program UI libraries are not the same path: the former requires the resolver to return sourceType: 'wevu-sfc' / real resolvedId, and pass through weapp.uniApp.include to explicitly allow dependency transformation
    • Only when there are explicit slot props (such as <template #item="{ item }">) or explicit enhanced scoped slot scenarios should you generate generic:scoped-slots-*
    • When forwarding <slot /> to a child component's named slot, do not generate or suggest <block slot="..."><slot /></block>; the real DevTools runtime will lose the forwarded content. The WeChat platform uses an internal virtualHost wrapper by default; to return to the old real-node behavior, configure weapp.vue.template.slotFallbackWrapperStrategy: 'view'; for customization, prefer the component-internal static attribute slot-wrapper="cover-view"、slot-wrapper-footer="view"、slot-wrapper-class="..."、slot-wrapper-footer-class="..." or project configuration weapp.vue.template.slotFallbackWrapper; in global rules, component matches template tag names,componentName matches child component static defineOptions({ name })
    • A custom slot wrapper must be able to carry actual child content; for example, text is not suitable for wrapping <view>，block will be fallen back by the compiler to view
    • Vue/Wevu component tag output remains kebab-case; optional chaining and nullish coalescing must be converted into expressions executable by the target mini program template
    • When weapp.i18n is enabled, import the build instance weapp-vite/i18n from i18n, and explicitly wire it in with defineOptions({ behaviors: [i18n.behavior] }) ; the logic layer accesses translations and locale through i18n.global , and templates can directly call the configured t(...)
    • i18n only allows direct template calls of configured functions;t(resolveKey()) or other nested calls still fall back to the logic thread, do not rely on arbitrary functions executing in WXML
    • The WeChat target supports scoped CSS, default/named CSS Modules, useCssModule() in synchronous setup, and CSS v-bind(); CSS vars are merged into the existing style of each template root node
    • :deep() / :global() / :slotted() only use forms that can be mapped to mini program selectors; treat other platforms as experimental until verified in the corresponding IDE/real device
  5. If typed-router.d.ts、typed-components.d.ts、components.d.ts drifts, first run wv prepare。
  6. If the project has a root AGENTS.md or local dist/docs/vue-sfc.md, the SFC syntax must be consistent with its constraints.
  7. For multi-platform SFC, verify only one -p <platform> target at a time; the Web runtime is for browser compatibility integration testing and does not replace the target mini program IDE/real device.

Toolchain and hot update boundaries

  • For Volar type issues, first check .weapp-vite/tsconfig.app.json, solution references, and vueCompilerOptions.plugins; do not replace managed configuration with implicit root directory inclusion.
  • skipTemplateCodegen will move template bindings and WXS types out of the template context; when "property does not exist" appears, first rule out that configuration.
  • Rely on JSON-only HMR only when JSON macros or configuration change; behavior, template, and runtime changes are still verified through the full SFC compilation chain.
  • defineConfig It is recommended to import from weapp-vite/config to preserve weapp.* 's context types and Hover documentation.

For the detailed matrix, see references/tooling-and-hmr-matrix.md。

Constraints

  • Do not mix multiple sets of JSON macros in one SFC.
  • Do not treat mini program component registration as Web Vue component registration.
  • Do not configure only the Wot UI or uview-plus resolver while omitting weapp.uniApp.include, and do not automatically add npm dependencies to the transformation scope. uview-plus should call mount$u() and synchronize $u, do not go through the Web global component registration process.
  • Do not mistake the ordinary default slot of kebab-case third-party native components such as t-*、van-* for an enhanced scoped slot.
  • Do not ignore prepare and .weapp-vite artifacts.
  • Do not casually perform unrelated runtime refactoring while fixing SFC syntax.
  • Do not treat the built-in i18n as an ICU/MessageFormat runtime; v1 only supports simple key lookup and {name} / {user.name} interpolation.

Output

When applying this skill, the output must include:

  • Problem stage diagnosis.
  • SFC-level change recommendations.
  • Template compatibility considerations.
  • Minimal verification commands.

Completion markers

  • Macro usage is clear and singular.
  • The template does not use unsupported syntax.
  • usingComponents The path is safe and the source is clear.
  • .weapp-vite Support for file and type output has been synchronized.

References

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