A PWA Ebook Reader application with OPDS support for apps like Booklore and Calibre Web
  • TypeScript 91.2%
  • Dockerfile 3.6%
  • JavaScript 2.5%
  • CSS 1.5%
  • HTML 1.2%
Find a file
2025-12-15 02:55:33 -05:00
public initial commit 2025-12-15 01:43:36 -05:00
server initial commit 2025-12-15 01:43:36 -05:00
src fixes 2025-12-15 02:55:33 -05:00
.dockerignore initial commit 2025-12-15 01:43:36 -05:00
.env.example initial commit 2025-12-15 01:43:36 -05:00
.gitignore initial commit 2025-12-15 01:43:36 -05:00
docker-compose.yml fixes 2025-12-15 02:03:52 -05:00
Dockerfile fixes 2025-12-15 02:03:52 -05:00
index.html initial commit 2025-12-15 01:43:36 -05:00
nginx.conf fixes 2025-12-15 02:03:52 -05:00
package.json initial commit 2025-12-15 01:43:36 -05:00
postcss.config.js initial commit 2025-12-15 01:43:36 -05:00
QUICKSTART.md initial commit 2025-12-15 01:43:36 -05:00
README.md initial commit 2025-12-15 01:43:36 -05:00
tailwind.config.js initial commit 2025-12-15 01:43:36 -05:00
tsconfig.json initial commit 2025-12-15 01:43:36 -05:00
tsconfig.node.json initial commit 2025-12-15 01:43:36 -05:00
vite.config.ts initial commit 2025-12-15 01:43:36 -05:00

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

  1. Build and run with Docker Compose:
docker-compose up -d
  1. Access the reader at http://localhost:8080

  2. 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

  1. Install dependencies:
npm install
  1. Start the development server:
npm run dev
  1. In a separate terminal, start the backend proxy:
npm run server
  1. Open http://localhost:5173 in 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
docker-compose up -d

Configuration

Connecting to Booklore

  1. Ensure your Booklore instance has OPDS enabled
  2. Get your OPDS URL (typically https://your-booklore-server.com/opds)
  3. On first launch, enter this URL in the setup screen
  4. If authentication is required, enter your username (password support coming soon)

Environment Variables

  • PORT: Backend server port (default: 3000)
  • NODE_ENV: Set to production for 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:

  1. Open the app in Chrome
  2. Tap the menu (three dots)
  3. Select "Install app" or "Add to Home Screen"

On iOS:

  1. Open the app in Safari
  2. Tap the Share button
  3. Select "Add to Home Screen"

On Desktop:

  1. Open the app in Chrome/Edge
  2. Click the install icon in the address bar
  3. 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.