- TypeScript 91.2%
- Dockerfile 3.6%
- JavaScript 2.5%
- CSS 1.5%
- HTML 1.2%
| public | ||
| server | ||
| src | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| docker-compose.yml | ||
| Dockerfile | ||
| index.html | ||
| nginx.conf | ||
| package.json | ||
| postcss.config.js | ||
| QUICKSTART.md | ||
| README.md | ||
| tailwind.config.js | ||
| tsconfig.json | ||
| tsconfig.node.json | ||
| vite.config.ts | ||
Booklore Reader
A beautiful, feature-rich Progressive Web App (PWA) ebook reader with OPDS support, optimized for mobile devices including foldable phones.
Features
- OPDS Integration: Connect directly to your Booklore library or any OPDS-compliant server
- Offline Reading: Download books for offline access with IndexedDB storage
- Progressive Web App: Install as a native-like app on any device
- Foldable Display Support: Optimized for devices like the Pixel Fold
- Customizable Reading Experience:
- Multiple themes (Light, Dark, Sepia, Black)
- Adjustable font size, family, line height, and margins
- Left-aligned or justified text
- Support for both serif and sans-serif fonts
- Touch-Optimized Navigation:
- Swipe left/right to turn pages
- Tap left/right thirds of screen to navigate
- Auto-hiding controls for immersive reading
- Reading Progress Sync: Automatically saves your position in each book
- Bookmarks: Save and return to important passages
- Responsive Design: Works seamlessly on phones, tablets, and desktops
Quick Start with Docker
- Build and run with Docker Compose:
docker-compose up -d
-
Access the reader at
http://localhost:8080 -
On first launch, enter your Booklore OPDS server URL (e.g.,
https://your-server.com/opds)
Manual Setup (Development)
Prerequisites
- Node.js 20+
- npm or yarn
Installation
- Install dependencies:
npm install
- Start the development server:
npm run dev
- In a separate terminal, start the backend proxy:
npm run server
- Open
http://localhost:5173in your browser
Building for Production
npm run build
The built files will be in the dist directory.
Docker Deployment
Build the image:
docker build -t booklore-reader .
Run the container:
docker run -d -p 8080:80 -p 3000:3000 booklore-reader
Using Docker Compose (recommended):
docker-compose up -d
Configuration
Connecting to Booklore
- Ensure your Booklore instance has OPDS enabled
- Get your OPDS URL (typically
https://your-booklore-server.com/opds) - On first launch, enter this URL in the setup screen
- If authentication is required, enter your username (password support coming soon)
Environment Variables
PORT: Backend server port (default: 3000)NODE_ENV: Set toproductionfor production builds
Usage
Browsing Your Library
- Browse your OPDS catalog by tapping on collections
- Use the Back button to navigate up the catalog hierarchy
- Switch between Online and Offline tabs to see downloaded books
Reading Books
- Tap a book to download and open it
- Swipe left/right or tap the sides of the screen to turn pages
- Move your finger/mouse to reveal the controls
- Tap the settings icon to customize your reading experience
- Your reading position is automatically saved
Offline Access
- Downloaded books are stored locally in IndexedDB
- Access them from the "Offline" tab even without internet
- Books remain available until manually deleted
PWA Installation
On Android:
- Open the app in Chrome
- Tap the menu (three dots)
- Select "Install app" or "Add to Home Screen"
On iOS:
- Open the app in Safari
- Tap the Share button
- Select "Add to Home Screen"
On Desktop:
- Open the app in Chrome/Edge
- Click the install icon in the address bar
- Or use the menu: "Install Booklore Reader"
Foldable Device Optimization
The reader is specifically optimized for foldable devices like the Pixel Fold:
- Responsive layouts that adapt to fold/unfold states
- Touch gestures optimized for large screens
- Customizable column counts for wide screens (future feature)
- Full viewport utilization with safe-area support
Technology Stack
- Frontend: React 18 + TypeScript + Vite
- EPUB Rendering: ePub.js
- State Management: Zustand with persistence
- Styling: Tailwind CSS
- Offline Storage: IndexedDB (via idb)
- PWA: Vite PWA Plugin with Workbox
- Backend: Express.js (CORS proxy)
- Containerization: Docker
Browser Support
- Chrome/Edge 90+
- Safari 14+
- Firefox 90+
Known Limitations
- Currently supports EPUB format only (PDF and CBZ support planned)
- Basic authentication only (OAuth/OIDC support planned)
- Single-column layout on mobile (dual-column for tablets/desktop planned)
Roadmap
- PDF support
- CBZ/CBR comic support
- OAuth/OIDC authentication
- Cloud sync for reading progress and bookmarks
- Highlights and notes
- Text-to-speech
- Dictionary integration
- Social features (reading lists, recommendations)
License
MIT
Contributing
Contributions are welcome! Please open an issue or submit a pull request.
Troubleshooting
CORS Issues
If you encounter CORS errors when connecting to your OPDS server, ensure the backend proxy is running on port 3000.
Books Won't Download
Check that your OPDS server is accessible and that the download URLs are publicly reachable.
PWA Won't Install
Ensure you're accessing the app via HTTPS (or localhost for development). PWAs require a secure context.
Reading Progress Not Saving
Check browser storage settings. IndexedDB and localStorage must be enabled.
Support
For issues and questions, please open an issue on GitHub.