Skip to content

CLAUDE.md

Latest commit

 

History

History
181 lines (149 loc) · 5.97 KB

CLAUDE.md

File metadata and controls

181 lines (149 loc) · 5.97 KB

CLAUDE.md

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

Project Overview

KolaBiliHelper is an Electron + Vue 3 desktop music player application for Bilibili.

Tech Stack

  • Frontend: Vue 3 + TypeScript + Composition API
  • Desktop: Electron + electron-vite
  • State: Pinia + pinia-plugin-persistedstate
  • UI: Naive UI + Tailwind CSS 4 + SCSS
  • Build: Vite + electron-vite
  • Lint: ESLint 9 + @antfu/eslint-config

Commands

# Development
pnpm dev                    # Start dev environment

# Build
pnpm build                  # Type-check + electron-vite build
pnpm build:nocheck          # Build without type checking
pnpm build:win/mac/linux    # Platform-specific builds

# Type checking
pnpm typecheck              # Both node and web
pnpm typecheck:node         # Electron main process
pnpm typecheck:web          # Vue renderer

# Linting
pnpm lint                   # Run ESLint
pnpm lint:fix               # Auto-fix issues

Architecture

kolaBiliHelper/
├── electron/               # Electron main process
│   ├── main/               # Main process (Node.js): index, tray, ipcMain, utils
│   ├── preload/            # Preload scripts
│   └── server/             # Embedded HTTP server
├── src/                    # Renderer (Vue 3)
│   ├── api/                # API modules (bilibili, search, wbi)
│   ├── assets/             # Static assets (CSS, SVG)
│   ├── components/         # Vue components
│   │   ├── card/           # SongCard
│   │   ├── common/         # TextContainer
│   │   ├── control/        # PlayerControl, Volume, Progress
│   │   ├── global/         # AppProvider, Loading, Like
│   │   ├── layout/         # Header, Sidebar
│   │   ├── list/           # SongList, SearchList
│   │   ├── menus/          # Context menus
│   │   └── modals/         # LoginModal, PlaylistModal, CloseAppModal
│   ├── hooks/              # Composables
│   ├── plugins/            # Plugins (store setup)
│   ├── router/             # Vue Router
│   ├── stores/             # Pinia stores (play, search, system, user)
│   ├── types/              # TypeScript definitions (app.d.ts)
│   └── utils/              # Utilities (request, adapter, player, helper, time)
├── constants/              # Constants
│   ├── ipcChannels.ts      # IPC channel definitions
│   ├── pageId.ts           # Page identifiers
│   ├── playStatus.ts       # Play status constants
│   ├── renderer.ts         # Renderer constants
│   ├── urls.ts             # URL constants
│   └── browserExtension.ts # Browser extension constants
└── index.html

Path Aliases

  • @/* → src/*
  • @constants/* → constants/*

Naming Conventions

Type Convention Examples
Variables, functions, refs, props, hooks camelCase currentSong, usePlayStore
Components, component files PascalCase SongCard.vue, PlayerControl
Constants UPPER_SNAKE_CASE HISTORY_MAX, PLAY_MODE
Folders, HTML classes, slots, props in templates kebab-case player-control, class="flex gap-2"
Interfaces, types I prefix + PascalCase ISong, IPlaylist
Enums E prefix + PascalCase EPlayState
API functions api prefix apiGetUser, apiSearchSongs
Global state instances store prefix storeUser, storePlay
Data transformers (global only) transform prefix transformDate

Code Conventions

Vue Components

  • Use <script setup lang="ts"> with Composition API
  • File names: PascalCase.vue
  • Template access: props.xx explicitly (no destructuring)
  • Structure order: script → template → style
  • Props ordering: visible → model → emit → setup

Pinia Stores

  • Composition API style: defineStore('name', () => {...})
  • Use storeToRefs for reactive destructuring
  • Store files: src/stores/{name}Store.ts
  • Export type: PlaySongMode in playStore.ts

Constants Structure

  • ipcChannels.ts: IPC channel strings (DATA_FROM_PLUGIN, PLAY_STATUS_CHANGE, WINDOW_*, etc.)
  • pageId.ts: Page identifiers (HISTORY_PAGE, LIKED_PAGE, PLUGIN_PAGE)
  • playStatus.ts: Playback status constants
  • renderer.ts: Renderer constants (HISTORY_MAX)

API Layer

  • HTTP requests via axios request instance in utils/request.ts
  • Bilibili APIs in api/bilibili.ts, api/search.ts, api/wbi.ts
  • WBI signature for authenticated requests

TypeScript

  • Strict type checking, avoid any
  • Global types in types/app.d.ts
  • Use interfaces for data structures
  • Path aliases for imports

Styling

  • Tailwind CSS for utility classes
  • SCSS + scoped for custom styles
  • Theme colors via CSS variables

Electron

  • Main process: electron/main/
  • Preload scripts: electron/preload/
  • IPC communication for renderer ↔ main
  • Tray functionality in electron/main/tray.ts
  • IPC channels defined in constants/ipcChannels.ts

Module Exports

  • Follow @antfu/eslint-config module ordering
  • No inline exports
  • All named exports at file end
  • JSDoc/TSDoc comments for functions

ESLint Style

  • No semicolons
  • Single quotes
  • Trailing commas

Data Structures

ISong Interface

interface ISong {
  id: string
  bvid: string
  title: string
  artist: string
  pic: string
  duration: number | string
  url?: string
  custom?: {
    source?: 'browser-extension' | 'client-search'
  }
}

Default Playlists (computed)

  • HISTORY_PAGE: Recently played
  • LIKED_PAGE: Liked songs
  • PLUGIN_PAGE: Songs from browser extension

Git Commit Convention

Format: feat(模块名): 描述、fix(模块名): 描述、test(模块名): 描述

Examples:

feat(player): 添加播放进度同步
fix(search): 修复搜索结果排序
refactor(api): 重构 WBI 签名逻辑