taro-documentation（芋头文档）

Taro Documentation Skill

Overview

Taro is a comprehensive multi-platform development framework that enables building applications for multiple platforms from a single codebase. Platforms include WeChat Mini Programs, Alipay Mini Programs, Baidu Smart Programs, ByteDance Mini Apps, QQ Mini Programs, H5 (web), React Native, and Harmony OS.

Key characteristics:

• React-like syntax and component model
• Write once, run on multiple platforms
• Extensive API coverage for platform-specific features
• Rich component library
• Strong TypeScript support
• Active ecosystem with plugins and UI libraries

When to Use This Skill

Use this skill when users are:

• Developing Taro applications or mini programs
• Asking questions about Taro APIs, components, or configuration
• Troubleshooting Taro-related issues
• Seeking guidance on Taro best practices
• Converting or migrating projects to Taro
• Integrating Taro with other frameworks or libraries

Core Concepts

Framework Architecture

Taro follows a React-like architecture:

• Component-based: UI built with reusable components
• JSX syntax: Write UI declaratively using JSX/TSX
• Virtual DOM: Efficient rendering and updates
• Lifecycle methods: Component lifecycle hooks
• State management: Local state and global state solutions

Multi-Platform Compilation

Taro compiles to different platform targets:

• Compilation time: Code transforms to platform-specific syntax
• Runtime adapters: Platform API differences handled by runtime
• Conditional compilation: Platform-specific code when needed
• Unified APIs: Single API surface across platforms

Project Structure

Standard Taro project organization:

taro-project/
├── src/
│   ├── app.config.ts      # Global app configuration
│   ├── app.ts             # App entry point
│   ├── pages/             # Page components
│   │   ├── index/
│   │   │   ├── index.tsx
│   │   │   └── index.config.ts
│   ├── components/        # Reusable components
│   └── assets/            # Static resources
├── config/
│   ├── index.js           # Build configuration
│   ├── dev.js             # Development config
│   └── prod.js            # Production config
└── package.json

Using Taro Documentation

Available Resources

This skill provides access to comprehensive Taro documentation organized into small topic files (all <100 KB). Choose the file prefix that matches the question:

1. API References (files prefixed with apis-)

- Network & routing: apis-network*.md, apis-routing.md - Storage & UI feedback: apis-storage*.md, apis-ui-feedback*.md, apis-ui-navigation.md - Device, sensors, connectivity: apis-device-system.md, apis-device-sensors.md, apis-device-connectivity*.md - Media (image/video/audio): apis-media-image.md, apis-media-video*.md, apis-media-audio*.md - Location & canvas: apis-location*.md, apis-canvas*.md - Cloud & payment: apis-cloud*.md, apis-payment.md - Miscellaneous APIs: apis-other*.md - (Files with -partN suffix continue the same topic.)

1. Component References (files prefixed with components-)

- Containers and layout: components-containers*.md - Basic content: components-basic.md, components-other.md - Forms & inputs: components-form*.md - Navigation: components-navigation.md - Media & graphics: components-media*.md, components-map-canvas.md, components-gesture.md, components-skyline.md - Open capabilities: components-open-capability.md

1. Configuration References

- config-app.md – Global app configuration (app.config.ts) - config-page.md – Page-level configuration - config-build.md – Build/compiler settings and optimization

1. Guide References (files prefixed with guides-)

- Getting started & fundamentals: guides-quickstart*.md, guides-basics*.md - Architecture & routing: guides-routing.md, guides-testing.md - State & UI libraries: guides-state.md, guides-ui-libraries.md - Platform specifics: guides-platform-weapp.md, guides-platform-h5.md, guides-platform-rn.md, guides-platform-harmony*.md - Optimization & troubleshooting: guides-optimization*.md, guides-troubleshooting.md, guides-community.md - Plugin development & advanced topics: guides-plugin-dev*.md

How to Reference Documentation

When users ask Taro-related questions:

1. Identify the topic: Determine which documentation area is relevant (API, component, configuration, or guide)
2. Load appropriate reference: Use the Read tool to access the specific topic file:

Read references/apis-network.md           # Network/API calls (see apis-network-part*.md for continuation)
Read references/components-form.md        # Form components and inputs
Read references/config-app.md             # Global app configuration
Read references/guides-platform-weapp.md  # WeChat Mini Program guides

1. Search within files: Use Grep with wildcards to scan the relevant file family:

Grep pattern:"Taro\.request" path:"references/apis-network*.md"
Grep pattern:"Button component" path:"references/components-form*.md"

1. Provide contextual answers: Combine documentation with understanding of user's context to give relevant, actionable guidance

Common Development Scenarios

API Usage

When users ask about Taro APIs:

• Reference the relevant references/apis-*.md file (for example, apis-network*.md for network calls or apis-device-system.md for device info)
• Provide code examples showing API usage
• Note platform compatibility if relevant
• Mention common gotchas or best practices

Example: For "How do I make a network request?", reference Taro.request API documentation and provide example with error handling.

Component Usage

When users ask about Taro components:

• Reference the appropriate references/components-*.md file (for example, components-form*.md or components-media*.md)
• Show component props and event handlers
• Provide JSX usage examples
• Note styling approaches and platform differences

Example: For "How do I create a scrollable list?", reference ScrollView component documentation and demonstrate with sample code.

Configuration

When users ask about project setup or configuration:

• Reference references/config-app.md, config-page.md, or config-build.md depending on scope
• Explain configuration options and their effects
• Show configuration file examples
• Address build and compilation settings

Example: For "How do I configure page routing?", reference app.config.ts page configuration and demonstrate route setup.

Development Guides

When users need broader guidance or best practices:

• Reference the matching references/guides-*.md file (for example, guides-platform-weapp.md or guides-state.md)
• Provide step-by-step guidance for complex tasks
• Share best practices and common patterns
• Link related APIs and components

Example: For "How do I integrate Redux?", reference state management guide and show integration steps.

Platform Considerations

Platform-Specific Features

Taro supports multiple platforms with varying capabilities:

• Some APIs/components are platform-specific
• Check platform support tables in documentation
• Use conditional compilation when needed
• Test on target platforms

Conditional Compilation

For platform-specific code:

// Example of conditional compilation
if (process.env.TARO_ENV === 'weapp') {
  // WeChat Mini Program specific code
}

if (process.env.TARO_ENV === 'h5') {
  // H5 specific code
}

API Compatibility

Check API support across platforms:

• Documentation includes platform support matrices
• Some APIs may have limited support on certain platforms
• Provide fallbacks or alternatives when needed

Best Practices

Code Organization

• Separation of concerns: Separate UI, logic, and data layers
• Reusable components: Create generic components for common UI patterns
• Type safety: Use TypeScript for better development experience
• Configuration externalization: Keep configuration separate from code

Performance Optimization

• List rendering: Use virtual lists for long lists
• Image optimization: Compress images and use lazy loading
• Code splitting: Split code by routes or features
• Avoid unnecessary renders: Use React.memo, useMemo, useCallback appropriately

Development Workflow

• Start with templates: Use official templates for project scaffolding
• Follow conventions: Adhere to Taro naming and structure conventions
• Test on multiple platforms: Regularly test on target platforms during development
• Use developer tools: Leverage Taro DevTools and platform-specific debugging tools

Troubleshooting Approach

When users encounter issues:

1. Identify the problem area: API, component, configuration, or build issue
2. Check documentation: Reference relevant documentation section
3. Verify platform compatibility: Ensure feature is supported on target platform
4. Review configuration: Check if configuration is correct
5. Consult guides: Look for similar issues in troubleshooting guides
6. Provide solutions: Offer concrete fixes or workarounds

Additional Resources

Reference Files

For detailed documentation, consult these topic-specific files (all <100 KB unless noted):

• **API shards (references/apis-*.md)** – 40+ files covering network, routing, storage, device, media, location, canvas, cloud, payment, and miscellaneous APIs. Files with -partN suffix continue the same topic sequentially.
• **Component shards (references/components-*.md)** – Containers, basic content, form controls, gestures, skyline rendering, navigation, media, map/canvas, and open capability components.
• **Configuration files (references/config-*.md)** – config-app.md, config-page.md, and config-build.md for their respective scopes.
• **Guide shards (references/guides-*.md)** – Quickstart, fundamentals, routing, testing, state, UI libraries, platform-specific guides, optimization, troubleshooting, plugin development, and community resources.
• references/taro-docs.xml (3.9 MB, 92,568 lines) – Original Repomix bundle retained as a fallback reference when you need the complete archive.
• ***.original backups** – The previous monolithic files renamed with .original for historical reference; avoid loading them unless necessary.

Search Patterns

When searching within reference files, use glob patterns to cover all shards in a family:

For APIs:

Grep pattern:"Taro\.[APIName]" path:"references/apis-*.md"

For components:

Grep pattern:"<ComponentName" path:"references/components-*.md"

For configuration:

Grep pattern:"config\.(option)" path:"references/config-*.md"

For guides:

Grep pattern:"specific topic" path:"references/guides-*.md"

Working with This Skill

Approach

1. Listen for Taro mentions: Activate when user mentions Taro-related topics
2. Assess question type: Determine if question is about API, component, config, or general guidance
3. Load relevant documentation: Read appropriate reference file or search within it
4. Provide contextual answer: Combine documentation with user's specific context
5. Include code examples: Show practical usage when relevant
6. Note platform considerations: Mention compatibility if relevant

Response Format

Structure responses with:

• Direct answer to user's question
• Relevant code examples
• Links to specific documentation sections (file path and topic)
• Platform considerations if applicable
• Related resources or next steps

Summary

This skill provides comprehensive Taro framework documentation to support development of multi-platform applications. Reference the organized documentation files based on user questions, and combine documentation knowledge with practical guidance to help users build effective Taro applications.

Focus on providing accurate, contextual, and actionable information that helps users solve their specific Taro development challenges.