App Integration: WeChat Mini Program

WeChat Mini Program development, tabBar configuration and CloudBase integration

How to Use

See How to Use Skill for detailed usage.

Test Skill

You can use the following prompts to test:

"Help me create a WeChat Mini Program project and integrate CloudBase"
"Implement complete integration between Mini Program and CloudBase"
"How do I adjust the Mini Program tabBar to text-only style, remove icon placeholders and eliminate white space above labels?"

Use AI to develop mini programs and integrate CloudBase

Installation and Viewing

To install all CloudBase Skills, run:

npx skills add tencentcloudbase/cloudbase-skills

To install only the current Skill, run:

npx skills add https://github.com/tencentcloudbase/skills --skill miniprogram-development

View current Skill online: miniprogram-development

Skill Rules Original Text

View SKILL.md Original

## 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.

### 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`.
- 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)

1. **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

2. **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

3. **Route by scenario**
   - If the task involves debugging, previewing, publishing, opening DevTools, console/network, or `wechatide`, read [debug and preview reference](references/devtools-debug-preview.md) first
   - If choosing between WeChat IDE Skills and CloudBase MCP, read [WeChat IDE Skills vs CloudBase MCP](references/wxide-vs-cloudbase-mcp.md)
   - If the task involves CloudBase, `wx.cloud`, cloud functions, CloudBase database/storage, or CloudBase identity handling, read [CloudBase integration reference](references/cloudbase-integration.md)
   - If the task involves `tabBar`, icon assets, or label spacing, prefer the text-only custom `tabBar` default below unless the user explicitly requires icons

4. **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

5. **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](references/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

1. **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

2. **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

3. **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`

```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](references/devtools-debug-preview.md) and [WeChat IDE Skills vs CloudBase MCP](references/wxide-vs-cloudbase-mcp.md)

## Minimal project skeleton

`app.js`

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

`pages/index/index.js`

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

`pages/index/index.wxml`

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

`pages/index/index.json`

```json
{
  "navigationBarTitleText": "Home"
}
```

`project.config.json`

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

## References

- [CloudBase Mini Program Integration](references/cloudbase-integration.md) — use this when the mini program project explicitly integrates CloudBase
- [WeChat DevTools Debug and Preview](references/devtools-debug-preview.md) — Nightly / `wechatide` paths, required context, and no-Nightly fallbacks
- [WeChat IDE Skills vs CloudBase MCP](references/wxide-vs-cloudbase-mcp.md) — layering and when to use which execution surface
- [Common Pitfalls](references/pitfalls.md) — read before generating code for optional chaining, TDesign styling, Canvas + storage, and environment issues

How to Use​

Test Skill​

Installation and Viewing​

Skill Rules Original Text​

How to Use

Test Skill

Installation and Viewing

Skill Rules Original Text