Beets Web UI

A web interface for the beets music library manager, built with Backbone.js, Marionette, jQuery, and Bootstrap.

Features

• Search and browse your beets music library
• Playback queue with 5-item limit
• Real-time player controls
• Lyrics display
• Local files support
• Responsive Bootstrap 5 interface

Quick Start

Prerequisites

• Node.js 20.x or later
• A running beets server (default: http://127.0.0.1:8337)

Installation

# Clone the repository
git clone https://github.com/matlads/beets-web-ui.git
cd beets-web-ui

# Install dependencies
npm install

# Configure environment
cp .env.example .env.local
# Edit .env.local with your beets server URL

Development

# Start development server
npm run dev

# Open http://localhost:5173 in your browser

Production Build

# Build for production
npm run build

# The built files will be in the `dist/` directory

Development

Available Scripts

• npm run dev - Start Vite development server
• npm run build - Build for production
• npm run preview - Preview production build locally
• npm test - Run Vitest tests
• npm run test:coverage - Run tests with coverage report
• npm run lint - Run ESLint linting
• npm run format:check - Check Prettier formatting
• npm run format - Format code with Prettier

Testing

The project includes comprehensive tests using Vitest with jsdom environment:

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Watch mode
npm run test:watch

Code Quality

• ESLint: Configured with recommended rules and Prettier integration
• Prettier: Code formatting with consistent style
• Type Checking: No TypeScript - plain JavaScript with ES6 modules

Architecture

Built with classic MVC architecture using:

• Backbone.js - Models, Collections, Router
• Marionette - Views and application structure
• Backbone.Radio - Event-driven communication between components
• jQuery - DOM manipulation
• Bootstrap 5 - UI components and styling
• Vite - Build tool and development server

Key Patterns

• Event-Driven Communication: Components communicate via Backbone.Radio channels
• Template-Driven Views: Underscore templates with inline SVG icons
• MVC with Marionette: Application → Regions → Views → Models
• Collection Management: Custom collection methods for API interaction

CI/CD

Automated testing via GitHub Actions:

• Runs on every push to main and pull requests
• Includes linting, formatting checks, and test coverage
• Coverage reports uploaded as artifacts
• Production build verification

Deployment

The built dist/ directory contains static files that can be deployed to any web server:

• GitHub Pages
• Netlify
• Vercel
• Traditional web server (Apache, nginx)

GitHub Pages Deployment

This repository includes a GitHub Actions workflow for automatic deployment to GitHub Pages:

1. Enable GitHub Pages in repository settings:

   • Go to Settings → Pages
   • Select "GitHub Actions" as the source
   • The workflow will deploy to https://matlads.github.io/beets-web-ui/

2. Configure environment variables (optional):

   • Set repository secrets for production configuration:
     • VITE_API_URL: URL of your beets server (e.g., https://your-beets-server.example.com)
     • VITE_USER_NAME: Default user display name

3. Manual deployment:

   # Build with production settings
   VITE_BASE_PATH=/beets-web-ui/ npm run build
   
   # Deploy the `dist/` directory to your web server

The deployment workflow (deploy.yml) runs on pushes to main branch and includes:

• Automated testing before deployment
• Production build with configurable base path
• Secure deployment using GitHub Pages action

Custom Domain

To use a custom domain with GitHub Pages:

1. Set VITE_BASE_PATH: / in the deployment workflow
2. Configure your custom domain in repository Settings → Pages
3. Update DNS records to point to GitHub Pages

Contributing

See AGENTS.md for detailed development guidelines and code style.

License

MIT © Martin Atukunda