Miniprogram Development

Standalone Install Note

If this environment only installed the current skill, start from the CloudBase main entry and use the published cloudbase/references/... paths for sibling skills.

• CloudBase main entry: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md
• Current skill raw source: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/miniprogram-development/SKILL.md

Keep local references/... paths for files that ship with the current skill directory. When this file points to a sibling skill such as auth-tool or web-development, use the standalone fallback URL shown next to that reference.

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

• Change Safety Protocol: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-platform/references/protocols/change-safety-protocol.md
• Deployment Gate: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/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, or mini program deployment/debug workflows.

Then also read

• CloudBase auth -> ../auth-wechat/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-wechat/SKILL.md)
• CloudBase document DB -> ../no-sql-wx-mp-sdk/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/no-sql-wx-mp-sdk/SKILL.md)
• Mini Program WeChat Pay or Integration Center generated payment functions -> ../cloudbase-wechat-integration/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-wechat-integration/SKILL.md; official docs: https://docs.cloudbase.net/integration/wechat-pay-miniprogram/index.md)
• UI generation -> ../ui-design/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/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.
• 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 CloudBase, wx.cloud, cloud functions, CloudBase database/storage, or CloudBase identity handling, read CloudBase integration reference
• If the task involves debugging, previewing, publishing, WeChat Developer Tools, or no-DevTools workflows, read debug and preview reference
• 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 path

• Prefer WeChat Developer Tools for simulator, panel-based debugging, preview, and real-device validation
• If WeChat Developer Tools is unavailable, use miniprogram-ci for preview, upload, and npm build workflows where appropriate

---

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

{
  "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

• If WeChat Developer Tools is available, use it as the primary path for simulator debugging, panel inspection, preview, and device validation
• If WeChat Developer Tools is not available, use miniprogram-ci as the fallback path for preview, upload, and npm build-related automation
• For detailed workflows, read debug and preview reference

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 — use this for debugging, preview, publishing, and no-DevTools fallback workflows
• Common Pitfalls — read before generating code for optional chaining, TDesign styling, Canvas + storage, and environment issues

CloudBase Mini Program References

This document supplements SKILL.md with practical WeChat Mini Program + CloudBase integration guidance.

How to use this reference (for a coding agent)

1. Understand platform differences

• WeChat Mini Program and Web have completely different authentication approaches.
• Must strictly distinguish between platforms.
• Never mix Web authentication methods into mini program projects.
• Mini programs with CloudBase are naturally login-free.

2. Follow CloudBase best practices

• Use wx.cloud APIs on the mini program client side.
• Configure appropriate database permissions before relying on client writes.
• Prefer cloud functions for cross-collection operations and privileged writes.
• Use OPENID from cloud.getWXContext() as the stable user identifier on the server side.

3. Use correct SDKs and APIs

• Mini program client code should use wx.cloud.database(), wx.cloud.callFunction(), and wx.cloud.uploadFile() as appropriate.
• Do not use Web SDK authentication patterns in mini programs.
• Use envQuery to get environment ID when available.

4. Use CloudBase MCP via mcporter (CLI) when IDE MCP is not available

• You do not need to hard-code Secret ID / Secret Key / Env ID in config.
• CloudBase MCP supports device-code login via the auth tool, so credentials can be obtained interactively.
• Add CloudBase MCP server in config/mcporter.json:

If other MCP servers already exist, keep them and only add the cloudbase entry.

     {
       "mcpServers": {
         "cloudbase": {
           "command": "npx",
           "args": ["@cloudbase/cloudbase-mcp@latest"],
           "description": "CloudBase MCP",
           "lifecycle": "keep-alive"
         }
       }
     }

• Discover tools and schemas:
• npx mcporter list — list configured servers
• npx mcporter describe cloudbase --all-parameters — inspect CloudBase server config and get full tool schemas with all parameters (⚠️ 必须加 `--all-parameters` 才能获取完整参数信息)
• npx mcporter list cloudbase --schema — get full JSON schema for all CloudBase tools
• npx mcporter call cloudbase.help --output json — discover available CloudBase tools and their schemas
• Call CloudBase tools (auth flow examples):
• npx mcporter call cloudbase.auth action=status --output json
• npx mcporter call cloudbase.auth action=start_auth authMode=device --output json
• npx mcporter call cloudbase.auth action=set_env envId=env-xxx --output json

1. Environment Initialization

Mini programs using CloudBase should initialize wx.cloud once during app startup.

App({
  onLaunch() {
    wx.cloud.init({
      env: "your-env-id",
      traceUser: true,
    });
  },
});

Rules

• Always obtain the environment ID via envQuery when available.
• Prefer a single app-level initialization instead of repeated page-level initialization.
• Use traceUser: true unless there is a clear reason not to, so CloudBase can associate requests with the current WeChat user.

2. Authentication Model

Mini program CloudBase is naturally login-free.

Required behavior

• Do not generate login pages or login flows.
• Do not port Web authentication patterns into mini programs.
• In cloud functions, retrieve user identity with cloud.getWXContext().OPENID.

const cloud = require("wx-server-sdk");
cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV });

exports.main = async () => {
  const wxContext = cloud.getWXContext();
  return {
    openid: wxContext.OPENID,
  };
};

3. Recommended Capability Boundaries

Use the right CloudBase capability in the right layer.

Client side

• wx.cloud.database() for client-safe reads and user-scoped writes
• wx.cloud.uploadFile() for user-generated assets
• wx.cloud.callFunction() for invoking backend orchestration

Cloud functions

• Privileged writes
• Cross-collection transactions or workflows
• Third-party API integration
• Data normalization / validation
• Accessing trusted user identity via OPENID

4. Environment Selection

• Do not hard-code a random environment ID.
• Prefer obtaining the environment ID from tooling such as envQuery.
• Initialize CloudBase once, usually in app.js / app.ts.

5. WeChat Developer Tools and Project Shape

• Confirm project.config.json includes appid before asking the user to open the project.
• Mini program source is typically under miniprogram/.
• Cloud functions are typically under cloudfunctions/.
• Generated pages should include companion config files such as index.json.

6. AI and Model Usage

• Mini programs on supported base library versions can use wx.cloud.extend.AI.
• Keep prompts and model selection explicit.
• If streaming is used, consume the stream fully and update UI incrementally where appropriate.

7. Fallback When IDE MCP Is Unavailable

If IDE-native MCP integration is unavailable, use the CloudBase MCP through mcporter and complete login with device-code auth instead of embedding secrets in config.

8. Console and Operational Links

When relevant, guide users to the CloudBase console for:

• environment settings
• database permission rules
• cloud function deployment status
• storage management
• billing / package information

Prefer console guidance over guessing permissions or environment state.

Common Pitfalls in WeChat Mini Program Development

This file captures high-frequency mistakes observed in real projects. Use these as pre-flight checks before generating code.

1. Optional Chaining (?.) and Modern Syntax

Problem: Many base libraries and WeChat DevTools versions do not support optional chaining (obj?.prop) or nullish coalescing (??).

Correct approach:

• Use traditional if checks or && / || patterns.
• Prefer wx.getSystemInfoSync() + version checks only when truly needed.

Example to avoid:

const name = user?.name ?? 'Guest';   // Often breaks

Safe alternative:

const name = (user && user.name) || 'Guest';

2. TDesign Component Styling (Especially ::after)

Problem: TDesign components use pseudo-elements for borders, icons, and states. Overriding with simple class selectors often fails.

Key points:

• Use CSS custom properties (variables) provided by TDesign when possible.
• Target ::after and ::before carefully with high specificity or !important only as last resort.
• Test on real device — DevTools preview can hide rendering differences.

Recommended pattern:

/* Prefer variables first */
.t-button {
  --td-button-border-color: transparent;
}

/* Only fall back to ::after when necessary */
.custom-cell::after {
  border-color: var(--td-border-color, #e5e5e5) !important;
}

3. Canvas in Mini Games + Cloud Storage Permissions

Problem: Canvas drawing + saving to cloud storage frequently fails due to permission or context issues.

Checklist:

• Use wx.createCanvasContext (2D) or wx.createOffscreenCanvas correctly for the target base lib.
• Request scope.writePhotosAlbum or use canvasToTempFilePath + wx.cloud.uploadFile with proper auth.
• For cloud storage, ensure the file path uses the correct env and the storage permission rule allows the openid or role.

Common failure: Saving canvas as image then uploading without handling the temporary file path correctly.

4. Environment & Code Configuration Drift

Problem: Developer tools environment does not match the actual cloud environment used in code.

Prevention:

• Always verify project.config.json → cloudbaseRoot and appid.
• Use wx.cloud.init({ env: 'your-real-env-id' }) explicitly.
• After changing cloud environment in DevTools, restart the simulator.
• For CI/CD with miniprogram-ci, the IP whitelist must include the build machine.

5. General Recommendation

When generating mini program code that touches CloudBase: 1. Read this pitfalls file first. 2. Apply the Change Safety Protocol before any modification. 3. For upload/publish flows, complete the Deployment Gate checklist.

This keeps the skill defensive and reduces repeated correction loops.