Library / SDK
futurepress/epub.js avatar
futurepress/epub.js

epub.js: Rendering EPUB Documents in the Browser with JavaScript

Enhanced eBooks in the browser.

6,966 stars1,184 forksJavaScriptNOASSERTION

At a glance

What is it?
epub.js is a BSD-2-Clause JavaScript library that parses and renders EPUB files directly in the browser. It suits web readers and annotation tools, though the package.json version is 0.3.93 and the last push was on 2026-03-24.
Who is it for?
Adopt epub.js if you are building a browser-based reader and want pagination, persistence and hooks without writing an EPUB parser. Do not adopt it if you need a fast release cadence, because the package.json version is 0.3.93 and the newest tagged release listed is v0.3.88 from 2020-07-01.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Activity is slowing. The repository last received commits 7 months ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • futurepress/epub.js6,966 ★ · +2
Star history
Repository2026-09-232026-11-15
futurepress/epub.js7k7k

2 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What epub.js Solves, and Who It Is For

An EPUB file is a ZIP archive of HTML5, CSS, images and a manifest. A browser cannot open that archive as a document on its own. epub.js exists to close that gap: it parses the EPUB container, reads the package document (the .opf file), and renders sections into an element on your page. The README describes it as providing "an interface for common ebook functions (such as rendering, persistence and pagination) without the need to develop a dedicated application or plugin."

The audience is web developers building reading experiences. That includes a bookstore preview widget, a documentation reader for EPUB-based manuals, an annotation tool, or a research interface that needs to jump between locations in a text. The library is not a reader application. The README states that the reader has moved to its own repository at futurepress/epubjs-reader, so if you want a finished product rather than a library, that is where to look.

The licence is a practical part of the pitch. The README calls it "an incredibly permissive Free BSD license," and package.json declares "BSD-2-Clause." That is more permissive than a copyleft licence would be for a commercial reading product.

How epub.js Parses and Renders a Book

The data flow starts with the archive. For archived .epub files the README says to include JSZip before epub.js, because the library needs to unzip the container in the browser. The package.json declares "main": "lib/index.js" and "module": "src/index.js", so bundlers can pull in the ES module source while CommonJS consumers get the compiled lib output.

Once the book is unzipped, the library reads the manifest and spine. The README explains that the EPUB schema "standardizes the table of contents, provides a manifest that enables the caching of the entire book, and separates the storage of the content from how it's displayed." That separation is what makes pagination possible: the content is HTML, and the rendition decides how much of it appears at once.

Rendering happens through a manager and a flow. The default manager shows a single section at a time. The continuous manager fills the screen with as many sections as fit and preloads the next one offscreen; the README says this enables swiping and scrolling but is "less performant than the default method." Flow controls the axis: auto follows the OPF settings and defaults to paginated, paginated lays out spreads, and scrolled-doc scrolls a single document.

Hooks are the extension point. The README describes them as similar to plugins and lists the registration points: book.spine.hooks.serialize, book.spine.hooks.content, rendition.hooks.render, rendition.hooks.content and rendition.hooks.unloaded. A hook can return a promise, which blocks the pipeline until it resolves. That is how you would inject annotation layers or replace a media element before a chapter is shown.

Installing epub.js and Rendering a First Book

The README's getting started path is script tags, not a package manager. It says to include JSZip first, then the minified build from the dist folder, then a container element. The following is the README's own example with the paths it gives.

html
<script src="https://cdnjs.cloudflare.com/ajax/libs/jszip/3.1.5/jszip.min.js"></script>
<script src="../dist/epub.min.js"></script>
<div id="area"></div>

With those in place, create the book from a package document and render it. The README passes a URL to a package.opf file and a size to renderTo.

html
<script>
  var book = ePub("url/to/book/package.opf");
  var rendition = book.renderTo("area", {width: 600, height: 400});
  var displayed = rendition.display();
</script>

If you are working from the repository rather than a CDN build, the README says to install Node.js and then run npm install, followed by npm start to run the reader locally. The package.json scripts confirm this: "start" runs webpack-dev-server, "test" runs Karma with ChromeHeadlessNoSandbox, and "prepare" chains compile, build, minify and two legacy builds. To produce a distribution build yourself, the README gives npm run prepare for a one-off and npm run watch for continuous builds.

bash
npm install
npm start

One setting deserves attention before you ship. Scripted content inside EPUB HTML is disabled by default, and the README explains this is because of "the potential for executing malicious content," handled by sandboxing the iframe. If you pass allowScriptedContent: true to the rendition settings, scripts run, but the README warns this "currently makes the sandbox insecure." It also recommends sanitizing EPUB content server-side regardless.

Where epub.js Falls Short

The clearest limitation is release cadence. The package.json version is 0.3.93, while the most recent GitHub release is v0.3.88 from 2020-07-01. The repository is not archived and the last push was on 2026-03-24, so work is happening on the branch, but anyone pinning to a published version is pinning to something old. If your project requires semantic-versioned releases with changelogs, this is a poor match.

Performance is a stated trade-off rather than a bug. The continuous manager is described in the README as less performant than the default, and it preloads the next section offscreen. On a long book with heavy CSS, that preloading is the thing to watch.

The sandbox warning is the third constraint, and it cuts both ways. Leaving scripts disabled protects you but breaks any EPUB that relies on interactivity. Enabling them makes the iframe sandbox insecure by the README's own admission. There is no documented middle setting in the README.

Finally, epub.js is the wrong tool if you are not in a browser. It renders into DOM elements and depends on iframes for content isolation. A server-side EPUB-to-text pipeline, or a native mobile reader, has no use for the rendition layer, and the README does not present the parser as a standalone Node API.

Alternatives and How They Differ

epub.js gives you a book object, a rendition and hooks, and expects you to build the interface around them.

If you only need to extract text or metadata rather than display a book, a parsing library is the better fit. epub.js is oriented around rendering and pagination, and the README's own framing is about display: "renders a book and its parts based on a controlled vocabulary." Pulling it in to read a table of contents is a large dependency for a small job.

For a finished reader product rather than a library, the README points to futurepress/epubjs-reader, which has moved to its own repository. That is not a competitor so much as the same project's application layer, and it is the honest starting point if you do not want to write the UI yourself.

Maintenance, Licence and Upgrade Cost

The version in package.json is 0.3.93, and the newest GitHub release is v0.3.88 from 2020-07-01. That gap is the main upgrade risk: fixes on the branch may not correspond to a tagged release you can depend on, so a team that wants released versions should plan to build from source with npm run prepare or track the branch directly.

Building from source is not free. The prepare script runs compile, build, minify, legacy and productionLegacy in sequence, which means Babel, Webpack and the legacy toolchain all need to work in your environment. The devDependencies include Karma, Mocha, ESLint and the documentation generator, so a full checkout is a heavier install than a single runtime dependency.

The licence is declared as BSD-2-Clause in package.json, and the README calls it a Free BSD license. That permits commercial use and modification, but the repository entry for the licence file is listed as "license" with no extension, and the top-level metadata reports the licence as NOASSERTION. If your legal review depends on the exact text, read the license file in the repository rather than relying on the package metadata. This is a description of what the files say, not legal advice.

On types: package.json declares "types": "types/index.d.ts" and the repository has a types/ directory. TypeScript consumers get declarations, but the README does not state how closely they track the current source.

Editorial conclusion

Adopt epub.js if you are building a browser-based reader and want pagination, persistence and hooks without writing an EPUB parser. Do not adopt it if you need a fast release cadence, because the package.json version is 0.3.93 and the newest tagged release listed is v0.3.88 from 2020-07-01. Before committing, verify that your EPUB files render acceptably under the default manager and check the types/ directory against your TypeScript version.

Frequently asked questions

How do you use epub.js to render a book?

Create a book from a package document with ePub("url/to/book/package.opf"), call book.renderTo with a container id and dimensions, then call rendition.display() to show it. The README's example uses a div with id "area" and a 600 by 400 rendition.

What is epub.js?

It is a JavaScript library for rendering EPUB documents in the browser across many devices. The README describes it as providing rendering, persistence and pagination without requiring a dedicated application or plugin.

Is an EPUB file safe to open?

epub.js disables scripted content by default because of the potential for executing malicious content, and sandboxes the iframe the content renders into. The README still recommends sanitizing EPUB content server-side as well.

What are the disadvantages of EPUB?

The README does not discuss EPUB's disadvantages as a format. It does note that enabling scripted content in epub.js makes the sandbox insecure, and that the continuous render manager is less performant than the default.

Official sources

  1. futurepress/epub.js on GitHub
  2. Issues
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/futurepress-epub-js.svg)](https://hysenlabs.com/projects/futurepress-epub-js)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/futurepress-epub-js.svg)](https://hysenlabs.com/projects/futurepress-epub-js)

Was this useful?