miniprogram-development

SKILL.md

Sibling skills (local only)

Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../auth-tool-cloudbase/SKILL.md.

If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.

Cross-cutting protocols (required before code changes or deployments):

Change Safety Protocol: ../cloudbase-platform/references/protocols/change-safety-protocol.md

Deployment Gate: ../cloudbase-platform/references/protocols/deployment-gate.md

Activation Contract

Use this first when

The request is about WeChat Mini Program structure, pages, preview, publishing, or CloudBase mini program integration.

Read before writing code if

The user mentions wx.cloud, CloudBase mini programs, OPENID, mini program deployment/debug workflows, Nightly DevTools, wechatide, or WeChat IDE Skills.

The user mentions message push (消息推送), customer-service auto-reply (客服消息/自动回复), or binding MsgType/Event callbacks to cloud functions.

Then also read

CloudBase auth -> ../auth-wechat-miniprogram/SKILL.md

CloudBase document DB -> ../cloudbase-document-database-in-wechat-miniprogram/SKILL.md

Mini Program WeChat Pay or Integration Center generated payment functions -> ../cloudbase-wechat-integration/SKILL.md (official docs: https://docs.cloudbase.net/integration/wechat-pay-miniprogram/index.md)

UI generation -> ../ui-design/SKILL.md first

Do NOT use for

Web auth flows or Web SDK-specific frontend implementation.

WeChat Pay, payment callbacks, refunds, or Official Account OAuth details; use cloudbase-wechat-integration for those scenarios.

Common mistakes / gotchas

Generating a Web-style login flow for mini programs.

Mixing Web SDK assumptions into wx.cloud projects.

Applying CloudBase constraints before confirming the project actually uses CloudBase.

Assuming Stable WeChat Developer Tools includes Nightly Skills/wechatide (it may not).

Forcing CloudBase MCP Tencent Cloud login for daily mini program cloud ops when Nightly wechatide already works.

Inventing wechatide tool names or flags instead of using --help / Nightly tools.yaml.

Bypassing wxide CLI / IDE for message-push ops with low-level transport before cloud_*_msg_push is exposed (see message-push-customer-service.md).

Assuming cloud-function return values auto-reply to customer-service chats (must use cloud.openapi.customerServiceMessage.send).

Making code or configuration changes without first following the Change Safety Protocol (cloudbase-platform/references/protocols/change-safety-protocol.md).

Performing mini program upload/publish without first completing the checks in cloudbase-platform/references/protocols/deployment-gate.md.

When to use this skill

Use this skill for WeChat Mini Program development when you need to:

Build or modify mini program pages and components

Organize mini program project structure and configuration

Debug, preview, or publish mini program projects

Work with WeChat Developer Tools workflows

Handle mini program runtime behavior, assets, or page config files

Integrate CloudBase in a mini program project when explicitly needed

Do NOT use for:

Web frontend development (use web-development)

Pure backend service development (use cloudrun-development or cloud-functions as appropriate)

UI design-only tasks without mini program development context (use ui-design)

How to use this skill (for a coding agent)

Start with the general mini program workflow

Treat WeChat Mini Program development as the default scope

Do not assume the project uses CloudBase unless the user or codebase indicates it

Follow mini program project conventions

Keep mini program source under the configured mini program root

Ensure page files include the required configuration file such as index.json

Check project.config.json before suggesting preview or IDE workflows

Route by scenario

If the task involves debugging, previewing, publishing, opening DevTools, console/network, or wechatide, read debug and preview reference first

If choosing between WeChat IDE Skills and CloudBase MCP, read WeChat IDE Skills vs CloudBase MCP

If the task involves CloudBase, wx.cloud, cloud functions, CloudBase database/storage, or CloudBase identity handling, read CloudBase integration reference

If the task involves mini program SEO / WeChat search optimization / page indexing / search promotion (小程序搜索优化、页面收录、搜索推广、关键词排名), read Mini Program SEO & WeChat Search Optimization first

If the task involves message push (消息推送), customer-service auto-reply (客服消息自动回复), MsgType/Event → cloud function binding, or push-related function logs, read Message Push & Customer Service Auto-Reply first

If the task involves tabBar, icon assets, or label spacing, prefer the text-only custom tabBar default below unless the user explicitly requires icons

Use CloudBase rules only when applicable

CloudBase / 微信云开发 is an important mini program integration path, but not a universal requirement

Only apply CloudBase-specific auth, database, storage, or cloud function constraints when the project is using CloudBase

Recommend the right preview/debug/cloud-ops path

Prefer Nightly WeChat Developer Tools (built-in Skills/MCP) and execute via wechatide when available — see devtools-debug-preview.md

Nightly download: https://developers.weixin.qq.com/miniprogram/dev/devtools/nightly_backup.html

If Nightly / wechatide is unavailable, fall back to miniprogram-ci for preview/upload and CloudBase MCP for cloud resources

WeChat Mini Program Development Rules

General Project Rules

Project Structure

Mini program code should follow the project root configured in project.config.json

Keep page-level files complete, including .json configuration files

Ensure referenced local assets actually exist to avoid compile failures

Configuration Checks

Check project.config.json before opening, previewing, or publishing a project

Confirm appid is available when a real preview, upload, or WeChat Developer Tools workflow is required

Confirm miniprogramRoot and related path settings are correct

Resource Handling

For tabBar, prefer a text-only custom tabBar by default when the user does not explicitly need icons. This avoids icon asset handling, removes reserved icon space, and makes the label area easier to align.

Only generate local icon assets and configure iconPath / selectedIconPath when the user explicitly asks for tab icons or the design requires them.

When generating local asset references such as icons, ensure the files are downloaded into the project.

Keep file paths stable and consistent with mini program config files.

Recommended default for simple tabBar

Use tabBar.custom = true, keep only pagePath and text in app.json, and render text-only items in the custom component so there is no icon slot and no extra blank area above the label.

app.json

{
  "tabBar": {
    "custom": true,
    "list": [
      { "pagePath": "pages/index/index", "text": "首页" },
      { "pagePath": "pages/travel/travel", "text": "行程" },
      { "pagePath": "pages/my/my", "text": "我的" }
    ]
  }
}

Keep the custom tabBar layout text-only, and use flex centering or matching height and line-height to remove the blank area above the label. Switch to downloaded local icons only when the user explicitly wants icon-based tabs.

CloudBase as a Mini Program Sub-Scenario

If the user explicitly uses CloudBase, wx.cloud, Tencent CloudBase, 腾讯云开发, or 云开发, follow the CloudBase integration reference

In CloudBase mini program projects, use wx.cloud APIs and CloudBase environment configuration appropriately

Do not apply CloudBase-specific rules to non-CloudBase mini program projects

Debugging, Preview, and Publishing

Prefer Nightly DevTools + wechatide for open project, compile, simulator, console/network debug, preview, upload, and daily cloud ops (WeChat login — no separate Tencent Cloud login)

Always pass required context: -c <clientName>, absolute --project, valid appid, and cloud env when needed

If Nightly / wechatide is not available, use miniprogram-ci as the fallback for preview/upload/npm, and CloudBase MCP for cloud resources; tell the user to install Nightly for full Skills/MCP

For detailed workflows, read debug and preview reference and WeChat IDE Skills vs CloudBase MCP

Message Push & Customer Service Auto-Reply

微信生态专章：消息推送 / 客服自动回复细节以中文 reference 为准（术语保留英文 API 名）。

Current only ops path: WeChat Developer Tools IDE + wxide CLI. Do not teach low-level bypasses while cloud_query_msg_push / cloud_manage_msg_push are not yet exposed (track 9109db6b).

Deploy receiver functions with cloud_fn_deploy and --remote-npm-install; bind (MsgType, Event) → one cloud function in the IDE message-push panel until CLI tools land.

Customer-service auto-reply requires cloud.openapi.customerServiceMessage.send plus config.json openapi permissions — function return values alone do not reply.

Function logs: IDE 云开发控制台 → 云函数 → 日志; CLI log query is pending (9109db6b / d5735473).

Full reference: Message Push & Customer Service Auto-Reply

Minimal project skeleton

app.js

App({
  onLaunch() {
    console.log("Mini Program launched");
  },
});

pages/index/index.js

Page({
  data: {
    message: "Hello CloudBase Mini Program",
  },
});

pages/index/index.wxml

<view class="page">
  <text>{{message}}</text>
</view>

pages/index/index.json

{
  "navigationBarTitleText": "Home"
}

project.config.json

{
  "appid": "your-mini-program-appid",
  "projectname": "cloudbase-mini-program",
  "miniprogramRoot": "./",
  "compileType": "miniprogram"
}

References

CloudBase Mini Program Integration — use this when the mini program project explicitly integrates CloudBase

WeChat DevTools Debug and Preview — Nightly / wechatide paths, required context, and no-Nightly fallbacks

WeChat IDE Skills vs CloudBase MCP — layering and when to use which execution surface

Message Push & Customer Service Auto-Reply — 消息推送 / 客服自动回复 via wxide CLI + IDE (no low-level bypass; pending cloud_*_msg_push)

Mini Program SEO & WeChat Search Optimization — 小程序搜索优化 / page indexing / search promotion (mpcrawler, URL reachability, navigator jumps, titles & thumbnails)

Common Pitfalls — read before generating code for optional chaining, TDesign styling, Canvas + storage, and environment issues