SparksFly
/
YwYMusic
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
YwYMusic/AGENTS.md

3.3 KiB
Raw Blame History

AGENTS.md

This file provides guidance to Codex (Codex.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

# 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():

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.).