wx-cloudfunctions

WX Cloud Functions

Contract

Use this skill to develop TypeScript WeChat cloud functions following the project's layered module conventions, and to package them with vite-plugin-uni-cloudfunctions.

Do not use this skill for:

• Operational data writes (adding prompts/categories/images) — redirect to content-ops.
• CloudBase environment management, security rules, cloud storage — redirect to cloudbase skill.
• Preview/automation operations in WeChat DevTools — redirect to wechatide-skill.

Stop and ask when: the ER diagram of the new collection's data model has not been confirmed by the user but cloud sync is requested; or an action is expected to have high concurrency/long duration and the user needs to decide whether to split it into a separate cloud function.

Input Contract

Required:

• Business requirements: function name (module name), action list, input/output of each action
• CloudBase collections and fields involved

Optional (read when needed):

• references/conventions.md — complete 13 rules + CloudBase system field list (required reading when creating a function or doing a review)
• references/mcp-setup.md — configuration templates when cloudbase MCP is unavailable (Claude Code / Cursor / Codex, placeholder version)
• assets/function-scaffold.md — file skeleton template to copy when creating a cloud function
• assets/tsconfig.json / assets/tsconfig.app.json / assets/tsconfig.cloudfunctions.json — project references three-piece template (copy to project root when the project lacks it)

Output Contract

Return:

• List of changed file paths
• Type check and unit test results (command + pass/fail)
• Build artifact verification results (dist/**/cloudfunctions/<fn>/index.js whether generated)
• If the data model is added/changed: mermaid ER diagram (including field types and associations) and user confirmation record

Add a cloud function (one function = one business module)

1. Read references/conventions.md, confirm the layering and naming rules.
2. If a new collection is involved: first use mermaid erDiagram to draw the data model (noting field types and associations) and have the user confirm it; fields must not have the same names as CloudBase system fields (see references for the list). Only after confirmation may it be synced to the cloud via cloudbase MCP.
   • If no cloudbase MCP tool is available in the session: follow references/mcp-setup.md to write the corresponding client's MCP configuration into the project (Claude Code → .mcp.json，Cursor → .cursor/mcp.json，Codex → .codex/config.toml), write only placeholders for environment variables, then prompt the user to manually fill in the real CLOUDBASE_ENV_ID / CLOUDBASE_API_KEY and reload MCP; skip the cloud sync step until it is configured.
3. Follow assets/function-scaffold.md to create the directory skeleton:
   • cloudfunctions/<fn>/：index.ts、package.json、handlers.ts、services.ts、repository.ts(CloudBase data access + DTO conversion),model.ts（zod v4 schema）、model.d.ts(pure TS types),__tests__/、debug/
   • cross-function reusable pieces go in cloudfunctions/_shared/lib/：runtime.ts(SDK initialization + entry assembly wrapper),errors.ts、sort.ts, common validation pieces
   • If the project root lacks the project references configuration, copy the three tsconfig templates from assets (tsconfig.json / tsconfig.app.json / tsconfig.cloudfunctions.json); the app side must exclude out cloudfunctions/
4. Implementation order:model.ts schema → services.ts interface + default implementation → handlers.ts action dispatch → repository.ts real implementation → index.ts via _shared/lib/runtime.ts assembly export main。
5. payload validation defaults to .strict(), illegal input throws BAD_REQUEST; scenarios such as integrating with third-party APIs may be relaxed, but the reason must be explained in code comments.
6. For each action, add an event JSON sample under debug/ , for direct pasting during local debugging in WeChat DevTools.
7. __tests__/ Inject mock services for pure-logic unit tests, without depending on real CloudBase.

Modify an existing cloud function

1. Read all layered files of the target function first, then start work; when adding an action, update the action enum, model schema, debug sample, and unit tests in sync.
2. Do not do incidental refactoring; importing between functions is forbidden, and importing local files other than cloudfunctions/ is forbidden (the plugin enforces this).

Packaging and publishing (vite-plugin-uni-cloudfunctions)

Packaging uniformly uses the npm package vite-plugin-uni-cloudfunctions(Vite plugin, peer dependency Vite ^5.2.8）：

// vite.config.ts
import { uniCloudFunctions } from 'vite-plugin-uni-cloudfunctions';

export default defineConfig({
  plugins: [uniCloudFunctions({ external: ['wx-server-sdk'] })],
});

• Development period:UNI_PLATFORM=mp-weixin dev server watcher incremental compilation → dist/dev/mp-weixin/cloudfunctions/
• Production period: a regular mini program build is sufficient; the plugin at writeBundle compiles and publishes → dist/build/mp-weixin/cloudfunctions/
• Each function outputs a self-contained single file index.js + its own package.json；external only allows bare package names (default ['wx-server-sdk']), and external dependencies must be written into the function-level package.json dependencies
• Hand-writing deployment/copy scripts is forbidden; do not bypass the plugin to write artifacts directly into dist

Validation

# 云函数独立类型检查
pnpm exec tsc -p tsconfig.cloudfunctions.json --noEmit

# 单测
pnpm vitest run cloudfunctions

# 构建产物验证
pnpm build:mp-weixin
test -f dist/build/mp-weixin/cloudfunctions/<fn>/index.js && echo OK

Only when all pass is it considered complete; include commands and results in the report. Data model changes require a record of the user-confirmed ER diagram.

Common Mistakes

• Manually passing _openid to write operations — the SDK manages it automatically, and passing it manually will directly throw an error.
• Custom fields colliding with CloudBase system fields (createdAt/updatedAt/owner etc., see references for the full table).
• In _shared , put function-private action enums/payload schemas — function-specific schemas stay inside the function model.ts，_shared only holds truly common components.
• Cloud functions holding cross-request in-memory state — they must be stateless and idempotent; rate limiting/deduplication goes through the audit collection.
• Adding a new action but forgetting to sync the debug JSON sample and unit tests.