assistant/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a uni-app x project — DCloud's cross-platform app framework that compiles to native Android, iOS, HarmonyOS, H5, and various mini-programs. The assistant directory is the project root.

• Language: UTS (uni-app TypeScript) — a TypeScript superset that compiles to platform-native code
• UI Framework: Vue 3 with Composition API (<script setup> pattern)
• Current target: Android (platformConfig.json targets APP-ANDROID)
• Template files: .uvue (uni-app Vue single-file components)

Build & Development

This project is designed for HBuilderX IDE (DCloud's IDE). Development, building, and debugging are done through the IDE rather than CLI commands.

• Open the assistant directory in HBuilderX
• Use HBuilderX's Run menu to launch on a device/emulator (Android, iOS, H5, or mini-program)
• Build outputs go to the unpackage/ directory (gitignored)
• HBuilderX handles the UTS → platform-native compilation pipeline

Architecture

Entry Flow

index.html → main.uts → App.uvue → pages/index/index.uvue

1. index.html — H5/web entry point; for native apps this is largely a bootstrap shell
2. main.uts — Creates the Vue 3 app instance via createSSRApp(App) and exports createApp(). This SSR pattern is standard for uni-app x — the framework calls createApp() to instantiate the app on each platform.
3. App.uvue — Root component. Contains app-level lifecycle hooks (onLaunch, onAppShow, onAppHide, onLastPageBackPress, onExit) and global CSS classes (.uni-row, .uni-column).
4. pages/index/index.uvue — The single page of this app; defined in pages.json.

Key Configuration Files

• pages.json — Page routing (the pages array), global navigation bar style, and uniIdRouter (for uni-id authentication routing). The first entry in pages is the launch page.
• manifest.json — App identity (appid, name, version), cross-platform config (WeChat/Alipay/Baidu/Toutiao mini-program settings), and Vue version ("vueVersion": "3"). The uni-app-x key enables uni-app x mode.
• platformConfig.json — Declares which native platforms to build for (currently Android only).
• uni.scss — SCSS design tokens (colors, font sizes, spacing, border radius, opacity). These variables are automatically available in all .uvue components without importing. Use these variables to maintain visual consistency.

Platform-Specific Code

Use preprocessor directives in .uts/.uvue files to gate platform-specific logic:

// #ifdef APP-ANDROID || APP-HARMONY
// Android/HarmonyOS-only code
// #endif

// #ifdef MP-WEIXIN
// WeChat mini-program-only code
// #endif

See App.uvue for an example — the back-press double-tap-to-exit logic is Android-only.

Static Assets

Place static files in static/. Reference them in templates with /static/... paths (e.g., /static/logo.png).

UTS Notes

• UTS is structurally like TypeScript but compiles differently per platform target
• uni.* APIs (e.g., uni.showToast(), uni.exit()) are the cross-platform API surface — see uni-app x API docs
• ref() and other Vue 3 Composition API functions are available globally in <script setup> blocks