miniprogram-implement
Implement miniprogram application with best practices, start's with "miniprogram" template, built with a fixed technology stack Taro, express, scss, typescript, TCB PostgreSQL, and DOES NOT support fr
SKILL.md.codebuddy/skills/miniprogram-implement/SKILL.md
GitHubPrerequisites
Initialize Project (if needed):
REPO_ROOT/.genie/scripts/bash/setup-project.sh miniprogram
Generate docs/product/features.md before writing any code — product overview, core features, user stories, page structure, data models, API endpoints.
Validation: If docs/product/features.md does not exist, STOP and create it first.
Keep docs/product/features.md updated as requirements evolve during development.
Core Principles
Carefully consider what the user wants, fully utilize your skills, find the right skills, and plan it.
- Leverage the best design by SKILL:
ui-ux-pro-max - Use SKILL
text-to-imagefor generating images, icons, or illustrations when needed. - Use the SKILL
*-integratorto fully realize the user's needs.
Best Practices
General Principles
- Perfect Architecture: Refactor when needed, eliminate duplication, maintain clean separation
- Less is More: Quality over quantity unless enterprise landing page requested
- Leverage Existing Dependencies: Prefer existing libraries over new ones
MiniProgram-Specific (Automatic for All Pages)
- Chinese UI text for all user-facing content
- Mobile-first design (750px design width)
- Use px unit (28px body text, 88px button height) - auto-converted to rpx/rem
- Touch targets minimum 88px (44px physical)
- WeChat Green (#07C160) for primary actions
- Card-based layout with vertical scroll
MiniProgram Template Architecture
/
├── backend/ # Express.js + TypeScript
│ ├── package.json
│ ├── tsconfig.json
│ ├── jest.config.js
│ ├── .env.example / .env
│ └── src/
│ ├── index.ts # Server entry point
│ ├── app.ts # Express configuration
│ ├── config/
│ │ ├── env.ts # Environment validation (Zod)
│ │ └── logger.ts # Pino logger factory
│ ├── modules/ # Feature modules (routes + handlers)
│ │ └── [resource].ts
│ ├── types/
│ │ └── [resource].types.ts # Zod schemas
│ ├── middleware/
│ │ ├── errorHandler.ts
│ │ ├── validation.ts
│ │ └── logger.ts
│ └── __tests__/
│
└── frontend/ # Taro 4.x + React 18
├── package.json
├── tsconfig.json
├── project.config.json # WeChat miniprogram config
├── babel.config.js
├── config/ # Taro build configuration
│ ├── index.ts # Base config (esnextModules: ['taro-ui'])
│ ├── dev.ts
│ └── prod.ts
└── src/
├── app.tsx # Root component (Taro UI styles import)
├── app.config.ts # App config (pages, window, tabBar)
├── app.scss # Global styles
├── pages/
│ └── [page]/
│ ├── index.tsx
│ ├── index.scss
│ └── index.config.ts
├── components/ # Reusable components
├── services/
│ └── api-client.ts # Taro.request wrapper
├── assets/
│ ├── images/
│ └── tabbar/ # TabBar icons (PNG)
└── types/
Technical References
Detailed implementation patterns in references/:
- api-protocol.md: JSON-based API standard (CRITICAL - no URL parameters for data operations)
- frontend-patterns.md: Taro component mapping, navigation, storage, styling
- architecture.md: Complete monorepo structure, key files, commands
- publish-guide.md: 小程序发布流程指引(AppID/密钥获取、体验版、审核上架)
Quick Reference
Adding New Resources
Frontend:
- Define types in
src/types/[resource].ts - Create API functions in
src/services/[resource].tsusing JSON-based calls - Build Page/Components using Taro UI components
Backend:
- Create types in
src/types/[resource].types.ts - Create module in
src/modules/[resource].ts - Register router in
src/app.ts
Key Commands
# Frontend
npm run dev:h5 # H5 development (browser testing)
npm run dev:weapp # WeChat MiniProgram development
# Debugging
python3 "$PROJECT_ROOT/.genie/scripts/python/fetch_monitor_errors.py"
Critical Rules
- ⚠️ NO
*Selector: WeChat WXSS does NOT support the*universal selector. NEVER use Tailwind CSS in miniprogram — it injects* { ... }base styles that causeunexpected token '*'compile errors. Use SCSS with Taro UI instead - JSON Protocol: All data operations use POST with JSON body, not URL parameters
- Component Mapping: Use Taro components (
View,Text,Image), NOT HTML elements - Navigation: Use Taro APIs (
Taro.navigateTo,Taro.switchTab), NOT React Router - Storage: Use
Taro.setStorageSync/getStorageSync, NOT localStorage - Taro UI Components: Use existing components, DO NOT create custom versions
- AtInput onChange: Receives value directly, NOT event object
- ⚠️ NEVER USE process.env: Causes "ReferenceError: process is not defined". Use
Taro.getEnv()for environment detection - ScrollView Padding: Wrap content in View container, padding on ScrollView doesn't work
- Fixed Bottom: Use
bottom: 100pxdirectly, SCSS conditional compilation doesn't work - ⚠️ 750px Design Width: Use px unit based on 750px design (28px=14px physical, 88px=44px physical). Taro auto-converts to rpx/rem
- ⚠️ API Client Import: Use
apiClient.post()NOT{ post }- see below - ⚠️ Zod Schema Structure: Validation middleware expects
{ body, query, params }wrapper - see below - ⚠️ LOCAL IMAGES IN CSS: NEVER use
background-image: url(...)with local paths in SCSS/CSS. WeChat error: "本地资源图片无法通过 WXSS 获取". Use<Image>component instead - see below
⚠️ Common Runtime Errors - MUST AVOID
Error 1: process is not defined
ReferenceError: process is not defined
Cause: Using process.env.XXX anywhere in frontend code
Solution: Use Taro.getEnv() instead. Use existing src/services/api-client.ts.
Error 2: post is not a function
TypeError: (0 , _api_client__WEBPACK_IMPORTED_MODULE_2__.post) is not a function
Cause: Wrong import - trying to destructure non-existent named exports Solution:
// ✅ CORRECT - use instance methods
import { apiClient } from '@/services/api-client';
// or
import apiClient from '@/services/api-client';
// Use full path with /api prefix
const data = await apiClient.post<ResponseType>('/api/users/list', body);
const data = await apiClient.get<ResponseType>('/api/health');
// ❌ WRONG - no named exports exist
import { post, get } from '@/services/api-client'; // ERROR!
Error 3: Zod validation fails (400 Bad Request)
400 Bad Request - Validation failed
Cause: Zod schema missing body wrapper
Solution:
// ❌ WRONG - flat structure
export const createUserSchema = z.object({
name: z.string(),
phone: z.string()
});
// ✅ CORRECT - must wrap with body
export const createUserSchema = z.object({
body: z.object({
name: z.string(),
phone: z.string()
})
});
Error 4: 本地资源图片无法通过 WXSS 获取
[渲染层网络层错误] pages/xxx/index.wxss 中的本地资源图片无法通过 WXSS 获取
Cause: Using background-image: url(./local-path) in SCSS/CSS.
Solution: Use <Image> component instead. background-color and linear-gradient() are fine — only url() with local paths is blocked.
Launch Configuration
.cloudstudio file defines startup - DO NOT modify. Always use unified process script.