epub.ts (@likecoin/epub-ts)

Drop-in replacement for epubjs — same API, fully typed, 1 runtime dependency, actively maintained.

A complete TypeScript rewrite of epubjs v0.3.93 with strict mode, modern tooling, and ongoing bug fixes — without breaking your existing code.

What you get

• Same API, zero migration cost — change one import line and everything works
• Full TypeScript strict mode — generated .d.ts from source, so autocomplete matches runtime
• 1 runtime dependency (jszip) — smaller bundle, simpler supply chain
• 970+ tests across 40 files — Vitest with robust coverage
• Vite build — ESM, CJS, and UMD outputs out of the box
• Node.js support — @likecoin/epub-ts/node parses EPUBs server-side with linkedom
• Active maintenance — 20+ bug fixes and counting

Note: Built at 3ook.com and provided as-is. Forked from epubjs v0.3.93 by Fred Chasen / FuturePress.

Performance

Head-to-head numbers on two Project Gutenberg fixtures: a small book (Alice in Wonderland #11, 185 KB) and a large book (War and Peace #2600, 1.7 MB). Apple M4 Pro, macOS 26.4, headless Chrome 146, Node 20, median of 10–15 iterations. Run the bench yourself with npm run bench; see bench/README.md for full methodology and caveats.

Metric	epubjs 0.3.93	@likecoin/epub-ts	Δ
Bundle size (gzip, KB)	132.8	57.5	−56.7%
Alice (185 KB)
Cold parse (ms)	2.2	2.2	≈ 0
First display (ms)	96.8	83.4	−13.8%
locations.generate(1000) (ms)	1760.3	10.4	−99.4%
currentLocation() (ms / call)	0.106	0.060	−43.8%
War and Peace (1.7 MB)
Cold parse (ms)	11.7	7.9	−33.1%
First display (ms)	90.1	91.9	≈ 0
locations.generate(1000) (ms)	42903.3	158.9	−99.6%
currentLocation() (ms / call)	0.196	0.153	−22.1%

43 seconds → 159 ms on locations.generate() for a 1.7 MB book: this is the single biggest user-visible win, and it's what the 0.4.9 locations optimization was aimed at. Both libraries produce the same output count (169 locations for Alice, 429 for War and Peace) — the delta is real work, not a short-circuit.

currentLocation() — the pagination / CFI-range query called on every page turn — exercises the 0.6.0 canvas text measurement and 0.6.1 Mapping.findStart/findEnd binary search and is roughly 2× faster as a result. next-page timings are omitted from the table because both libraries converge on a frame-paced ~33 ms, which doesn't differentiate them.

Get started

Install

npm install @likecoin/epub-ts

Migrate from epubjs

Change one line — everything else stays the same:

- import ePub from "epubjs";
+ import ePub from "@likecoin/epub-ts";

Render an EPUB (browser)

import ePub from "@likecoin/epub-ts";

const book = ePub("/path/to/book.epub");
const rendition = book.renderTo("viewer", { width: 600, height: 400 });
rendition.display();

Load from file input

import ePub from "@likecoin/epub-ts";

const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener("change", async (event) => {
	const file = event.target.files[0];
	const data = await file.arrayBuffer();
	const book = ePub(data);
	const rendition = book.renderTo("viewer", { width: 600, height: 400 });
	rendition.display();
});

Use with a <script> tag (UMD / WebView)

For environments without a bundler — a plain HTML page, or a react-native-webview loading local files — use the UMD build. It exposes a global ePub and expects JSZip to be loaded first, mirroring the classic epubjs drop-in:

<script src="jszip.min.js"></script>
<script src="epub.umd.js"></script>
<script>
	const book = ePub("book.epub");
	const rendition = book.renderTo("viewer", { width: 600, height: 400 });
	rendition.display();
</script>

The bundle lives at dist/epub.umd.js — copy it locally, or load it from a CDN via https://unpkg.com/@likecoin/epub-ts/dist/epub.umd.js. In a bundler, prefer the standard entrypoint instead, which resolves to the ES module build: import ePub from "@likecoin/epub-ts".

Loading a book from a file:// URL (e.g. a local .epub bundled into a WebView) is supported: fetch can't read the file: scheme, so such requests fall back to XMLHttpRequest. The host must grant file access (on Android WebView, enable allowFileAccess / allowFileAccessFromFileURLs). Alternatively, read the file yourself and hand epub.ts an ArrayBuffer — ePub(arrayBuffer) skips the network entirely and works everywhere.

Parse on Node.js (no browser needed)

Extract metadata, table of contents, and chapter HTML server-side. Requires linkedom:

npm install linkedom

import { Book } from "@likecoin/epub-ts/node";
import { readFileSync } from "node:fs";

const data = readFileSync("book.epub");
const arrayBuffer = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
const book = new Book(arrayBuffer);
await book.opened;

console.log(book.packaging.metadata.title);
console.log(book.navigation.toc.map(item => item.label));

const section = book.spine.first();
const html = await section.render(book.archive.request.bind(book.archive));

Show page numbers in the table of contents

locations.locationFromHref() maps a navigation href to a generated location index, so a table of contents can show approximate page numbers:

await book.locations.generate(1000); // ~1000 characters per page

const toc = book.navigation.toc.map(item => {
	const index = book.locations.locationFromHref(item.href);
	return { ...item, page: index === -1 ? undefined : index + 1 };
});

Notes:

• The index is 0-based, so add 1 for a page number. It returns -1 when the href cannot be resolved.
• Page numbers depend on the chars value passed to generate() — they are estimates for navigation, not the publisher's printed pages. When a book ships a real page-list, use book.pageList instead.
• Entries are resolved per section, so two entries pointing into the same file (chapter.xhtml#a and chapter.xhtml#b) share a page number.
• Pre-paginated (fixed-layout) books resolve without calling generate() — each section is exactly one page, so the spine index is returned. Once locations exist they take precedence, so the result is always an index into locations.

Named exports

import {
	Book, EpubCFI, Rendition, Contents, Layout,
	Section, Spine, Locations, Navigation, PageList,
	Resources, Packaging, Archive, Store,
	Annotations, Themes, Mapping,
} from "@likecoin/epub-ts";

API reference

Full documentation: likecoin.github.io/epub.ts

Class	What it does
Book	Load, parse, and manipulate an EPUB
Rendition	Render a book into a DOM element
Contents	Manage content inside an iframe
EpubCFI	Parse EPUB Canonical Fragment Identifiers
Locations	Generate and query reading positions
Navigation	Table of contents and landmarks
Annotations	Highlights, underlines, and marks

Supported environments

Environment	Import	Notes
Modern browsers	@likecoin/epub-ts	Chrome 80+, Edge 80+, Firefox 74+, Safari 13.4+ (ES2020, Q1 2020)
Insecure contexts	@likecoin/epub-ts	http:// intranet and file:// deployments supported — runtime APIs gated behind secure contexts (crypto.randomUUID) are feature-detected with fallbacks
Vite / webpack	@likecoin/epub-ts	ESM or CJS
<script> tag / WebView	dist/epub.umd.js	UMD global ePub; load JSZip first. Reads file:// books via XHR fallback
Node.js 18+	@likecoin/epub-ts/node	Parsing only (no rendering); requires linkedom peer dep

Development

git clone https://github.com/likecoin/epub.ts.git
cd epub.ts
npm install

Script	Description
npm run build	Vite library build → dist/
npm test	Run tests (Vitest)
npm run test:watch	Run tests in watch mode
npm run typecheck	tsc --noEmit
npm run lint	ESLint
npm run lint:fix	ESLint with auto-fix
npm run docs	Generate API docs (HTML + Markdown)

Requires Node.js 18+ and npm 9+.

Security

EPUBs are untrusted input. Sections render in a sandboxed iframe with scripts disabled by default; see SECURITY.md for the threat model, the cost of allowScriptedContent: true, and how to report a vulnerability.

Contributing

See PROJECT_STATUS.md for current status and what to work on.

For AI agents contributing to this project, see AGENTS.md.

License

BSD-2-Clause (same as epubjs)

Acknowledgments

• epubjs by Fred Chasen / FuturePress — the original library this is forked from
• jszip — ZIP file handling

Built by 3ook.com

3ook is a Web3 eBook platform where authors publish EPUB ebooks and readers collect them as digital assets.

Related projects

• epubjs — Original EPUB reader library
• epubcheck-ts — TypeScript EPUB validator (also by 3ook.com)