# CLAUDE.md

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

## Project Overview

YwYMusic is a desktop music player built with Tauri 2 + Vue 3 + TypeScript. The app uses Tauri's Rust backend for native OS integration while the UI is built with Vue 3 and Naive UI components.

## Development Commands

```bash
# Install dependencies (uses pnpm workspaces)
pnpm install

# Run frontend dev server only (Vite on port 1420)
pnpm dev

# Run Tauri desktop app in dev mode (recommended)
pnpm tauri dev

# Build frontend (with TypeScript checking)
pnpm build

# Build Tauri desktop app for production
pnpm tauri build

# Preview production build
pnpm preview
```

## Architecture

### Frontend (Vue 3 + TypeScript)

- **Router**: Uses `createWebHashHistory` (required for Tauri file:// protocol)
- **State**: Lightweight reactive store pattern in `/src/stores/player.ts` (not Pinia)
- **UI Library**: Naive UI with auto-import resolver
- **Path Alias**: `@` maps to `./src`

### Backend (Tauri/Rust)

- Minimal Rust code in `/src-tauri/src/`
- Tauri handles native OS integration, window management, and system APIs

### Auto-Import Setup

**Critical**: This project uses unplugin-auto-import and unplugin-vue-components:

- Vue APIs (`ref`, `reactive`, `computed`, etc.) are auto-imported—no need to import from "vue"
- Naive UI hooks (`useMessage`, `useDialog`, etc.) are auto-imported
- Naive UI components are auto-imported—no need to register or import them
- TypeScript declarations are auto-generated in `src/types/auto-imports.d.ts` and `src/types/components.d.ts`

When writing Vue components, do not add manual imports for these APIs/components unless the auto-import fails.

### API Request Pattern

Centralized in `src/utils/request.ts`:

- Base URL from `VITE_BASE_API_URL` environment variable (see `.env`)
- Token stored in localStorage with key `"token"`
- Request interceptor adds `Authorization: Bearer <token>` header
- Response interceptor handles success (200) and unauthorized (401) codes
- Use exported functions: `get()`, `post()`, `put()`, `del()`, or generic `request()`
- All responses follow `ApiResponse<T>` type: `{ code: number, msg: string, data: T }`

### State Management

Player state lives in `src/stores/player.ts` using Vue's `reactive()`:

```typescript
playerState.current // Current song
playerState.queue // Play queue
playerState.isPlaying // Playing state
playerState.currentTime // Current playback position
playerState.volume // Volume level (0-100)
```

Use `playSong(song, queue?)` to update current song and queue.

## Key Files

- `vite.config.ts` - Vite configuration with auto-import plugins
- `src/main.ts` - Vue app entry point
- `src/router/index.ts` - Route definitions
- `src/utils/request.ts` - Axios instance with interceptors
- `src/types/global.ts` - Global TypeScript types
- `src-tauri/tauri.conf.json` - Tauri app configuration
- `src-tauri/src/lib.rs` - Tauri backend entry point

## TypeScript

- Base config: `tsconfig.json`
- Node config: `tsconfig.node.json`
- Auto-generated types in `src/types/` should not be manually edited
- Use type imports from `@/types/global.ts` for API responses

## Testing Frontend Changes

Always run `pnpm tauri dev` to test in the actual desktop environment, as Tauri apps behave differently from web apps (file protocol, window APIs, etc.).