From 4b75df286a8d03b4b8ef98d71c7148ffae3b0c06 Mon Sep 17 00:00:00 2001 From: Harvey Zhao Date: Fri, 3 Apr 2026 23:27:55 +0800 Subject: [PATCH] feat: add CLAUDE.md for project guidance and documentation structure --- CLAUDE.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..7f628c9d4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,202 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +ArtPlayer.js is a modern, full-featured HTML5 video player. It's organized as a monorepo using Lerna with independent versioning. + +- **Homepage**: https://artplayer.org +- **Online Editor**: https://artplayer.org (for testing examples) +- **API Docs**: https://artplayer.org/document + +## Repository Structure + +``` +packages/ + artplayer/ # Core player package + artplayer-plugin-*/ # 17+ plugins (danmuku, ads, chromecast, etc.) + artplayer-proxy-*/ # Canvas, Mediabunny proxies + artplayer-tool-*/ # iframe, thumbnail tools + artplayer-vitepress/ # Documentation site + +docs/ # Documentation and demo site + assets/ # Example assets and TypeScript demos + compiled/ # Built packages output + document/ # Generated API documentation + uncompiled/ # Development build output + test/ # Browser test files + +scripts/ # Build tooling + build.js # Production build + dev.js # Development server + build-i18n.js # I18n bundle builder + build-docs.js # Documentation generator + build-llm.js # LLMs.txt generator + plugin/create.js # New plugin scaffolding +``` + +## Common Commands + +### Development +```bash +# Start dev server on port 8082 with hot reload +npm run dev + +# Build for production (interactive prompt to select package) +npm run build + +# Build all packages +npm run build all + +# Build everything (packages, i18n, types, docs) + lint +npm run build:all +``` + +### Code Quality +```bash +# Lint with auto-fix (covers packages, scripts, tests, docs assets) +npm run lint +``` + +### Plugin Development +```bash +# Create new plugin from template +npm run create:plugin + +# Example: +npm run create:plugin my-feature +``` + +### I18n +```bash +# Build i18n bundles for all languages +npm run build:i18n +``` + +### TypeScript +```bash +# Generate TypeScript declaration files +npm run build:ts +``` + +## Architecture + +### Core Player (`packages/artplayer`) + +The main `Artplayer` class extends `Emitter` and initializes sub-components: + +```javascript +// Key components instantiated in constructor: +this.template = new Template(this) // DOM structure +this.events = new Events(this) // Event handling +this.player = new Player(this) // Video playback +this.controls = new Control(this) // Control bar +this.layers = new Layer(this) // Custom layers +this.contextmenu = new Contextmenu(this) +this.subtitle = new Subtitle(this) +this.setting = new Setting(this) +this.plugins = new Plugins(this) // Plugin manager +// ... and more +``` + +Source organization in `src/`: +- `config/` - Default configuration values +- `control/` - UI controls (play, progress, volume, etc.) +- `events/` - Event handling (click, hover, resize, etc.) +- `i18n/` - Localization files +- `icons/` - SVG icons +- `player/` - Video playback logic (hls, flv, dash, etc.) +- `plugins/` - Built-in plugins +- `setting/` - Settings panel components +- `style/` - LESS stylesheets +- `template.js` - HTML template generation +- `utils/` - Utility functions + +### Plugin Architecture + +Plugins are functions that receive the player instance and options: + +```javascript +// Template from scripts/plugin/template/src/index.js +export default function artplayerPluginTemplate(option = {}) { + return (art) => { + // Plugin initialization + // Access: art.player, art.controls, art.template, etc. + + return { + name: 'artplayerPluginTemplate', + // Expose methods to art.plugins['artplayerPluginTemplate'] + } + } +} +``` + +Plugin naming convention: +- Package: `artplayer-plugin-` +- Global variable: `artplayerPlugin` (camelCase) +- Exported function uses same name as global + +### Styling + +Uses LESS with inline imports: +```javascript +import style from './style/index.less?inline' +``` + +Styles are injected at runtime via `utils.setStyleText()`. + +### Build System + +Uses Vite via custom Node.js scripts: + +**Development** (`scripts/dev.js`): +- Builds IIFE bundle to `docs/uncompiled//` +- Serves `docs/` directory on port 8082 +- Watches source files for changes + +**Production** (`scripts/build.js`): +- Builds 3 formats: UMD (`.js`), UMD legacy (`.legacy.js`), ESM (`.mjs`) +- Outputs to `packages//dist/` +- Copies to `docs/compiled/` + +### I18n System + +Language files in `packages/artplayer/src/i18n/`: +- Base language: `zh-cn.js` +- Additional languages: `en.js`, `fr.js`, etc. +- Built as separate UMD/ESM bundles via `build-i18n.js` +- Global naming: `artplayerI18n` (e.g., `artplayerI18nEn`) + +### Creating New Plugins + +The `npm run create:plugin ` command: +1. Copies `scripts/plugin/template/` to `packages/artplayer-plugin-/` +2. Replaces placeholders in filenames and content +3. Creates example file at `docs/assets/example/.js` + +Plugin template structure: +``` +src/ + index.js # Main plugin code + style.less # Plugin styles +package.json +README.md +types/ + .d.ts # TypeScript declarations (optional) +``` + +### Utility Functions + +Core utilities in `packages/artplayer/src/utils/`: +- `utils.js` - Common helpers (isMobile, isSafari, query, etc.) +- `emitter.js` - Event emitter base class +- `scheme.js` - Option validation schema + +## Development Notes + +- **Package manager**: Uses Yarn with Lerna +- **Node version**: >= 20.0.0 +- **ESLint**: Uses @antfu/eslint-config +- **Browser support**: Last 1 Chrome version (ES2020), legacy builds target ES2015 +- **UMD builds**: Always expose global even in AMD/RequireJS environments