pacexy/flow: A Self-Hosted Browser-Based ePub Reader Built on Next.js

Browser-Based ePub Reading Without a Native App

Dedicated e-reader apps like Calibre or Apple Books install locally on a device and store their libraries on that device. Flow takes a different position: it is a web application that serves ePub files from a central host and makes them accessible through any browser, with no native installation required on the reader's device. This makes it practical for households or small teams where one person manages the library while others read across different devices.

The README describes Flow as a free, open-source, browser-based ePub reader. The target audience is users who want control over their library data and reading experience and are willing to run a server to get it. The hosted version at flowoss.com demonstrates the interface, but the self-hosted path is the primary use case for anyone who wants to avoid putting books on an external service.

Flow is built on Epub.js, a JavaScript library for rendering ePub files in the browser, combined with React and Next.js for the application layer. TypeScript is used throughout. Turborepo ties the monorepo together so the reader app and any shared packages build in the correct order.

Architecture: Next.js Monorepo with Turborepo

The repository is a pnpm monorepo managed with Turborepo. The top-level package.json names the workspace @flow/monorepo and specifies Node.js 18 or later. The package manager is pinned to pnpm 10.6.4. Build, dev, lint, and release scripts are all delegated to Turbo, which runs them across the workspace's apps and packages in parallel where dependencies allow.

The repository structure includes an apps/ directory for the main reader application and a packages/ directory for shared code. The Dockerfile produces a final runner image using Next.js output file tracing to reduce the image size, copying only the necessary files from the build stage. The runner image creates a non-root nextjs user and group and runs the server process as that user.

The docker-compose.yml defines a single service named reader that builds from the project Dockerfile, restarts always, maps port 3000 on the host to port 3000 in the container, and reads environment variables from apps/reader/.env.local. This is the minimal self-hosting configuration described in the README.

Running Flow Locally and Self-Hosting with Docker

Local development requires Node.js, pnpm, and Git. Clone the repository, copy any .env.local.example files to .env.local and fill in the required variables, then install dependencies:

git clone https://github.com/pacexy/flow

pnpm i

pnpm dev

For self-hosting, the README provides two Docker paths. The simpler option uses the included docker-compose.yml:

docker compose up -d

The manual option builds the image directly and runs it with the environment file:

docker build -t flow .
docker run -p 3000:3000 --env-file apps/reader/.env.local flow

Both paths require the environment variables to be set before starting. The README links to the environment variables setup section but does not list all required keys in the main README itself: you need to look at each .env.local.example file within the apps/ directory to find what must be configured. This is a practical friction point for first-time deployers.

Reading Features: Annotation, Typography, and Sharing

The README lists the implemented features: grid layout for the library view, in-book search, image preview, custom typography settings, highlight and annotation, theme switching, share and download via link, data export, and cloud storage. The annotation and highlight system is one of the stronger differentiators from a plain file server, as it lets readers mark passages and return to them later.

Theme support covers automatic (follows system preference), light, and dark modes. The cloud storage feature implies books are stored server-side, accessible from any device that can reach the deployment, rather than uploaded per session. Data export allows readers to take their annotations and highlights out of the system.

The share-and-download-by-link feature generates a URL that can be used to access a specific book. The README does not describe whether these links are protected by authentication or publicly accessible, which matters for deployments where library access should be restricted to specific users.

AGPL-3.0 License and Its Implications for Deployers

Flow is released under the GNU Affero General Public License version 3.0. AGPL-3.0 is a copyleft license with a network use clause: if you modify Flow and make it available to users over a network, you are required to make the modified source code available to those users under the same license. This clause captures what the GPL's distribution requirement misses for server-side applications.

For a typical self-hosted personal deployment where you run Flow unmodified on your home server for your own use, AGPL-3.0 imposes no additional obligations. If you modify Flow and offer it as a service to other people, even over an internal corporate network, you must publish the source of your modifications under AGPL-3.0.

This license choice makes Flow unsuitable as a base for any commercial product or any proprietary internal deployment where the organization modifies the software but does not want to open-source those modifications. Teams evaluating it for a company intranet library should involve their legal team in the license review before investing in customization.

Maintenance Status and a Comparison to Calibre-Web

The last push to the main branch was on 2026-03-28. The repository has no GitHub releases. The roadmap is hosted on Notion rather than in the repository itself, which means planned features can change without a record in the repository history.

A widely-used alternative in the same self-hosted ebook space is Calibre-Web, a web application built on top of the Calibre library database. Calibre-Web supports many ebook formats beyond ePub, provides library management with metadata editing, and can serve as an OPDS catalog for dedicated reading apps. The key difference is scope: Calibre-Web is a full library management and multi-format reading system, while Flow focuses specifically on the browser-native ePub reading experience built around a modern React interface. If your library contains formats other than ePub, or you need a single system to manage metadata and cover art, Calibre-Web is the broader tool. If ePub browser reading with annotation is the specific need and you want a lighter, more focused stack, Flow is the narrower fit.

Running Flow on a path that has spaces will likely cause issues because debootstrap-style build tools have historically not handled spaces in paths. The README for pacexy/flow does not explicitly warn about this, but it is worth keeping in mind when choosing a deployment directory.

Editorial conclusion

Flow suits engineers and self-hosters who want a browser-native ePub experience on their own infrastructure and are comfortable with Node.js and Docker deployments. It is the wrong choice for teams that need to package the reader commercially or run it inside a proprietary product, because AGPL-3.0 requires releasing all modifications under the same license. Before deploying it in an organization, read the AGPL-3.0 terms carefully: any network-facing deployment of a modified version requires publishing the source. The last push to the main branch was on 2026-03-28, so verify that open issues and pull requests are being addressed before relying on it for a production deployment.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. pacexy/flow on GitHub
4. Project website
5. README