school2-taro/CLAUDE.md

CLAUDE.md

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

Build & Development

# WeChat mini-program
npm run dev:weapp          # Watch/dev build → weapp/
npm run build:weapp        # Production build → weapp/

# H5 (web)
npm run dev:h5             # Watch/dev build → build/
npm run build:h5           # Production build → build/

Output directories are determined by TARO_ENV: for H5 it's build/, for all other platforms it matches the platform name (e.g., weapp/).

No test or lint scripts are configured. ESLint (eslint-config-taro) and Stylelint are installed but must be run manually.

Architecture

This is a Taro 3.6 cross-platform app using React 18 (concurrent mode), TypeScript, and Webpack 5. It targets WeChat, Alipay, DingTalk, JD, Kwai, QQ, Baidu, Toutiao mini-programs, and H5 web.

UI Library: @antmjs/vantui

The UI library is @antmjs/vantui (v3), a Taro-compatible port of Vant. Components are imported from @antmjs/vantui directly (e.g., import { Button } from '@antmjs/vantui'). The babel-plugin-import in babel.config.js handles on-demand style imports.

Page Structure

Each page lives in src/pages/<name>/ and consists of three files:

• index.tsx — page component (functional or class)
• index.config.ts — page-level config (title, navigation style, etc.)
• index.less — page styles

Pages must be registered in src/app.config.ts under the pages array.

Path Alias

@ maps to src/ (configured in config/index.js).

Theme & Global Styles

• src/app.less — global app styles (imported in app.ts)
• src/styles/index.less — theme variable overrides for Vant UI. It imports @antmjs/vantui/es/style/var.less and uncomments/redefines Less variables to customize the theme. This file is injected into every .less file via Less modifyVars (configured in config/index.js under both mini.lessLoaderOption and h5.lessLoaderOption).

Webpack Customizations (config/webpack/)

• commonChain.js — Overrides Taro's default script rule exclude so that Babel also processes these node_modules packages: taro, inversify, @antmjs, react-spring, recoil, buffer, qrcode. Do NOT include "taro" in the project name or all node_modules will be recompiled.
• miniChain.js — Applied to mini-program builds. Adds:
  • MiniFixPlugin — fixes path param encoding differences between WeChat/Douyin and Alipay/DingTalk
  • GlobalFixPlugin — polyfills the global variable for Alipay, DingTalk, and Baidu mini-programs
• h5Chain.js — Applied to H5 builds. Adds H5FixPlugin for H5 compatibility fixes.

Build Config Layers

config/index.js exports a function that merges the base config with config/development.js or config/production.js based on NODE_ENV. Environment variables:

Variable	Purpose	Default
TARO_ENV	Target platform (weapp, h5, alipay, etc.)	weapp
NODE_ENV	Build mode	production
API_ENV	API environment selector	real

• designWidth: 750 — all px values are converted to rpx at this ratio
• @tarojs/plugin-framework-react is configured with reactMode: "concurrent" (React 18 concurrent features)
• browserslist targets iOS 9+ for production

App Entry

• src/app.ts — class-based App component, renders this.props.children (the current page)
• src/app.config.ts — defines routes (pages array), window config, and app-level settings
• src/index.html — H5 entry HTML template

VantUI Component API Reference (v3.7)

This project uses @antmjs/vantui v3.7. The official docs: https://antmjs.github.io/vantui/main/

Always check the actual type definitions in node_modules/@antmjs/vantui/types/ when unsure about props. Key API notes for commonly used components:

Search

• shape: 'square' (default) | 'round'
• background: background color string (default #FFFFFF)
• onFocus, onBlur, onChange, onSearch, onClear, onCancel — event callbacks
• leftIcon, rightIcon — icon name or image URL
• showAction + actionText — right-side action button

Swiper (NOT the same as Taro's native Swiper)

• autoPlay — auto-play interval in ms (0 = disabled). Not autoplay
• loop — infinite loop mode. Not circular
• paginationColor — indicator dot color. Not indicatorColor
• paginationVisible — show/hide pagination dots
• duration — animation duration (default 500)
• width / height — card dimensions
• No indicatorActiveColor prop — only one paginationColor
• onChange callback: (currPage: number) => void (not an event object)

SwiperItem

• Minimal component, only className and children. No special props.

Grid / GridItem

• Grid: columnNum, border, gutter, square, clickable, center, iconSize
• GridItem: icon (string), text (ReactNode), iconColor, dot, info/badge, url + linkType

Tabs / Tab (v3.7)

• Tabs:
  • active — current tab index (number | string)
  • sticky — enable sticky mode
  • offsetTop — sticky offset in px. Not stickyOffsetTop
  • color, titleActiveColor, titleInactiveColor — color props
  • type: 'line' | 'card'
  • swipeable — enable swipe gesture switching
  • animated — enable tab switch animation
  • ellipsis — text overflow ellipsis (default true)
  • No lineWidth or lineHeight props
  • onChange: (e: { detail: { index: number; name?: string; title?: string } }) => void
• Tab: title (ReactNode), name (identifier), dot, info, disabled, titleStyle

Image (VantUI Image, not Taro's native Image)

• src, fit ('contain' | 'cover' | 'fill' | 'widthFix' | 'heightFix' | 'none'), width, height, radius
• round — circular image (boolean)
• lazyLoad, showError, showLoading
• renderLoading, renderError — custom render slots

Common VantUI pattern: Taro's native components vs VantUI components

• Use @tarojs/components for: View, Text, ScrollView, Image (native, simpler)
• Use @antmjs/vantui for: styled UI components (Search, Swiper, Tabs, Grid, Button, etc.)
• VantUI component props extend Taro's ViewProps, so onClick/onTap and style props are always available

Custom TabBar (src/custom-tab-bar/)

This project uses Taro's custom tabBar mechanism (tabBar.custom: true in app.config.ts). Key rules:

Component location

• The custom tabBar component MUST be at src/custom-tab-bar/index.tsx — this is a Taro convention, not configurable
• Taro automatically renders this component on every tab page; do NOT import <CustomTabBar /> in individual pages

Do NOT use CoverView

• CoverView / CoverImage have known bugs on real devices: invisible, click events don't bubble
• Use regular <View> with position: fixed; bottom: 0; z-index: 999 instead

Active tab state

• Taro creates a new instance of the tabBar component on each page, so useState resets on every tab switch
• Derive the active tab from Taro.getCurrentPages() at render time — NOT from component state
• Pattern: const route = Taro.getCurrentPages()[last]?.route; const activeKey = TAB_LIST.find(t => route.includes(t.key))

Tab switching

• Use Taro.switchTab({ url: pagePath }) — this matches native tabBar behavior
• The pagePath format must match the tabBar.list[].pagePath in app.config.ts

Center "publish" button

• The publish button is a UI-only element not in tabBar.list
• It triggers a VantUI <Popup> rendered as a sibling of the tabBar, NOT nested inside it
• The popup state can use useState since it's ephemeral and not shared across tabs