WebAgent/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 mobile web app template built with Vue 3 ecosystem, using Vite as the build tool. The template is designed for rapid development of mobile web applications with TypeScript support and modern tooling.

Development Commands

Core Development

# Start development server with hot reload
pnpm dev

# Build for development environment
pnpm build:dev

# Build for production environment
pnpm build:pro

# Preview production build locally
pnpm preview

Code Quality

# Run ESLint checks
pnpm lint

# Fix ESLint issues automatically
pnpm lint:fix

# TypeScript type checking
pnpm typecheck

Release Management

# Version bump with git commit and tag
pnpm release

Git Hooks

• pre-commit: Runs ESLint on staged files via pnpm lint-staged

Architecture

Directory Structure

src/
├── api/               # API endpoint definitions and services
├── assets/            # Static assets (images, icons, fonts)
├── components/        # Global reusable components (auto-imported)
├── composables/       # Vue 3 composables (auto-imported)
├── config/            # Application configuration
├── constants/         # Application constants
├── locales/           # i18n translation files
├── pages/             # Route pages with file-based routing
├── router/            # Vue Router configuration
├── stores/            # Pinia state stores
├── styles/            # Global styles and UnoCSS configuration
├── types/             # TypeScript type definitions
├── utils/             # Utility functions

Key Architectural Patterns

1. File-Based Routing: Uses unplugin-vue-router for automatic route generation from src/pages/ directory. Routes are defined using <route> custom blocks in SFC files.

2. Auto-Imports:

   • Components from src/components/ are auto-imported via unplugin-vue-components
   • Vue 3 Composition API and other utilities are auto-imported via unplugin-auto-import
   • Generated type definitions in src/types/auto-imports.d.ts

3. State Management: Uses Pinia with pinia-plugin-persistedstate for persistent storage. Stores are in src/stores/.

4. Styling: Uses UnoCSS for atomic CSS with Vant UI component library integration. Global styles in src/styles/.

5. Internationalization: Vue I18n configured with unplugin-vue-i18n. Translation files in src/locales/.

Configuration Files

• vite.config.ts: Vite configuration with plugins for Vue, UnoCSS, auto-imports, mock server, PWA, etc.
• tsconfig.json: TypeScript configuration with path aliases (@/*, ~root/*)
• uno.config.ts: UnoCSS configuration with Vant presets
• eslint.config.ts: ESLint configuration using @antfu/eslint-config

Development Workflow

1. Mock Server: Development server runs on port 3000 with optional mock server on port 8086 (MOCK_SERVER_PORT=8086)

2. Type Safety: TypeScript with vue-tsc for Vue SFC type checking

3. Mobile Optimization:

   • Vant UI library for mobile components
   • vant-touch-emulator for desktop touch simulation
   • postcss-mobile-forever for viewport adaptation
   • vite-plugin-vconsole for mobile debugging

4. PWA Support: Service worker generation via vite-plugin-pwa

Important Conventions

File-Based Routing

• Pages go in src/pages/ directory
• Use <route> custom block in SFC files for route metadata:

  <route>
  {
    "name": "home",
    "meta": {
      "title": "Home"
    }
  }
  </route>
  

Component Organization

• Global components in src/components/ are auto-imported
• Use PascalCase for component file names
• Local components should be colocated with their parent components

State Management

• Pinia stores in src/stores/ use defineStore() with TypeScript
• Stores automatically persist to localStorage via pinia-plugin-persistedstate

API Layer

• API services in src/api/ use Axios with interceptors
• Mock data in mock/ directory with vite-plugin-mock-dev-server

Styling

• Use UnoCSS utility classes primarily
• Global styles in src/styles/
• Vant component theming via CSS custom properties

TypeScript

• Path aliases: @/* maps to src/*, ~root/* maps to project root
• Auto-generated type definitions in src/types/

Deployment

• Netlify: Zero-config deployment via netlify.toml
• Build Modes: Separate development (build:dev) and production (build:pro) builds
• Environment Variables: .env, .env.development, .env.production files

Tools Integration

VS Code Extensions

• Volar for Vue 3 support
• UnoCSS for CSS utilities
• i18n Ally for translation management
• ESLint for code quality

Git Hooks

• Pre-commit linting via simple-git-hooks