shelfmark/src

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 frontend-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 (/api/*)
• WebSocket connection (ws://localhost:8084/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 frontend-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_modules and reinstall: make clean && make install
• Check Node.js version compatibility
• Verify TypeScript configuration