mirror of
https://github.com/calibrain/shelfmark.git
synced 2026-09-24 22:05:20 +01:00
742da1c43a
This PR was coauthored by alexhb1 and davidemarcoli. It builds on the FE rework created by alex, but adds a myriad of additional tweaks and optimizations to make the frontend feel modern, fast, and responsive. The summary of the changes is as follows: ### Architecture Changes React/TypeScript Migration: Refactored frontend from template/JS structure to React/TypeScript application for better maintainability and scalability WebSocket Integration: Implemented real-time updates for download status and progress with automatic fallback to polling Gevent Worker: Configured production WebSocket support ### UI/UX Improvements <img width="1502" height="890" alt="Screenshot 2025-11-10 at 10 02 59 AM" src="https://github.com/user-attachments/assets/86bf8649-623f-413c-b8e5-656e687e55a8" /> Downloads Sidebar: Replaced bottom downloads section with sidebar interface for better organization <img width="201" height="450" alt="Screenshot 2025-11-10 at 10 07 52 AM" src="https://github.com/user-attachments/assets/92b98e7c-c3bc-4b7e-80f1-252c3a760e33" /> Status Badges: Color-coded download status indicators instead of plain text Pinned Header: Fixed header position for consistent navigation Enhanced Book Cards: Improved layout and hover states with info modal button <img width="1474" height="899" alt="Screenshot 2025-11-10 at 10 08 18 AM" src="https://github.com/user-attachments/assets/9216d8a3-f662-434d-80e6-2a69b96abc31" /> Download Progress: Circular progress indicator on download buttons Toast Notifications: Added user feedback for actions Spinner Feedback: Loading indicators on search and download buttons Animations: Smooth transitions and fluid progress updates ### Mobile & Responsive Design Mobile-friendly Layouts: Optimized book cards and search interface for mobile <img width="225" height="450" alt="Screenshot 2025-11-10 at 10 05 49 AM" src="https://github.com/user-attachments/assets/c8236c1c-5837-4309-9577-46db7292a54b" /> Keyboard Handling: Improved mobile keyboard behavior with proper input types PWA Improvements: Enhanced progressive web app functionality Responsive Search: Better search box width and positioning across devices ### Developer Experience Development Mode: Separate frontend dev server that works with existing backend container Makefile: Added build automation and development commands Documentation: Updated README with frontend architecture details ### Bug Fixes Fixed "Clear completed" functionality Fixed dark mode toggle text Fixed sticky header behavior Fixed mobile search box positioning Removed active downloads requirement for initial state view ### Additional Features ESC Key: Close downloads sidebar with ESC key Calibre-Web Button: Direct link to Calibre-Web instance <img width="282" height="83" alt="Screenshot 2025-11-11 at 9 38 05 AM" src="https://github.com/user-attachments/assets/273075be-9743-4e13-9e48-5bf498f6c067" /> Granular Status Tracking: More detailed download progress information obtained via websockets --------- Co-authored-by: Alex <alex.bilbie1@gmail.com> Co-authored-by: Zack Yancey <yanceyz@proton.me> Co-authored-by: davidemarcoli <davide@marcoli.ch>
Source Code Documentation
This directory contains the frontend application for Calibre-Web Automated Book Downloader.
Structure
src/
└── frontend/ # React + TypeScript frontend application
├── public/ # Static assets (logo, favicon)
├── src/ # Source code
│ ├── components/ # React components
│ ├── App.tsx # Main application component
│ └── styles.css # Global styles
├── package.json # Dependencies and scripts
├── vite.config.ts # Vite configuration
└── tsconfig.json # TypeScript configuration
Frontend Development
Prerequisites
- Node.js (v16 or higher)
- npm or yarn
Quick Start
From the project root:
# Install dependencies
make install
# Start development server (http://localhost:5173)
make dev
# Build for production
make build
# Preview production build
make preview
# Run type checking
make typecheck
Alternatively, from src/frontend:
npm install
npm run dev
npm run build
Technology Stack
- Framework: React 18 with TypeScript
- Build Tool: Vite 5
- Styling: TailwindCSS 3
- Communication: WebSocket for real-time updates
Key Features
- Search Interface: Real-time book search with filtering
- Download Queue: Live status updates via WebSocket
- Details Modal: Rich book information display
- Responsive Design: Mobile-first approach
Development Tips
Hot Module Replacement (HMR)
The development server supports HMR for instant feedback during development.
API Integration
The frontend communicates with the Flask backend via:
- REST API endpoints (
/request/api/*) - WebSocket connection (
ws://localhost:8084/request/ws)
Building for Production
The production build is optimized and minified:
make build
Output is generated in src/frontend/dist/
Type Safety
Run TypeScript checks without building:
make typecheck
Debugging
Development Server Issues
- Ensure port 5173 is available
- Check that the backend is running on port 8084
- Verify WebSocket connection in browser console
Build Issues
- Clear
node_modulesand reinstall:make clean && make install - Check Node.js version compatibility
- Verify TypeScript configuration