weapp-vite-best-practices

目的

Build or refactor weapp-vite projects with stable defaults first, then optimize packaging and performance. Prioritize predictable output and reproducible CI.

触发信号

• User asks about vite.config.ts + weapp config design.
• User asks how to organize pages/components/subpackages in weapp-vite.
• User reports build output problems: missing pages/components, wrong output root, route generation mismatch, chunk duplication.
• User asks about CI automation with WeChat DevTools or weapp-ide-cli.
• User asks how weapp-vite CLI and weapp-ide-cli should split command ownership / passthrough.
• User asks when to use autoRoutes, auto-imported components, or chunk shared strategy.

适用边界

Use this skill when the core issue is project-level architecture or build orchestration.

Do not use this as the primary skill when:

• The issue is mainly Vue SFC template/macro syntax. Use weapp-vite-vue-sfc-best-practices.
• The issue is mainly runtime lifecycle/state/store patterns. Use wevu-best-practices.
• The task is native mini-program to weapp-vite migration planning. Use native-to-weapp-vite-wevu-migration.

快速开始

1. Confirm baseline runtime and source roots.
2. Classify goal: new setup, refactor, debug, or performance optimization.
3. Apply minimum viable config changes in vite.config.ts and app/page JSON sources.
4. Verify with targeted build/type checks before suggesting broader cleanup.

执行流程

1. Gather context first

• Inspect vite.config.ts, app.json source strategy, pages/subpackages layout, and scripts.
• Confirm weapp.srcRoot and expected output root.
• Ask for missing constraints only when blocked (target platform, package limits, CI environment).

2. Build a minimal strategy

• Keep config layering explicit: generic Vite config vs mini-program-specific weapp section.
• Prefer convention-first setup (autoRoutes, auto components) and add overrides only when required.
• Choose subpackage mode intentionally:
  • normal subpackage for shared context.
  • independent subpackage only when strict isolation is necessary.
• Choose weapp.chunks.sharedStrategy by explicit goal:
  • duplicate for better subpackage first-open performance.
  • hoist for stronger deduplication and package-size control.
• When handling CLI orchestration between weapp-vite and weapp-ide-cli, keep a single source-of-truth command catalog:
  • Define and export full top-level command names in weapp-ide-cli.
  • Let weapp-vite consume that export for passthrough decision.
  • Resolve commands in this order: weapp-vite native commands first, then weapp-ide-cli passthrough only if command is cataloged.

3. Diagnose by symptom category

• Output missing/wrong path: verify srcRoot, route generation source, and glob coverage.
• Slow build: inspect plugin timing and high-cost transforms.
• Route/component generation mismatch: verify generated artifacts and resolver behavior.

4. Propose actionable edits

• Give concrete file-level changes with rationale and expected impact.
• Avoid broad config rewrites when a local fix can solve the issue.

5. Verify narrowly

• Prefer targeted checks, for example:

pnpm build:pkgs
pnpm vitest run <related-test-file>

• Only suggest full regression when change scope requires it.

约束

• Do not optimize chunk strategy before srcRoot and route generation are confirmed.
• Do not combine many advanced overrides in the first iteration.
• Do not assume web-only conventions; keep mini-program JSON semantics explicit.
• Do not mix architecture refactor with unrelated business logic changes.
• Do not implement IDE command passthrough with hardcoded duplicate lists in multiple packages.
• Do not passthrough unknown commands blindly; require catalog hit before delegation.

输出要求

When applying this skill, return:

• A short diagnosis summary.
• A minimal change list with concrete file targets.
• Suggested verification commands (narrow first, then broad if needed).
• Tradeoff notes for subpackage/chunk choices.

完成检查

• vite.config.ts has a clear and minimal weapp section.
• pages/subPackages source-of-truth is explicit (manual or auto routes).
• Component registration strategy is deterministic (auto import + resolver policy).
• Subpackage/chunk strategy is selected with stated reason.
• Dev/CI workflow is reproducible and not dependent on manual IDE clicks.
• CLI dispatch ownership is deterministic: native-first, catalog-based passthrough second.
• Command catalog changes are made in weapp-ide-cli and consumed by weapp-vite, not duplicated.

参考资料

• references/config-playbook.md
• references/debug-playbook.md
• references/cli-dispatch-playbook.md