Storyteller releases EPUB library v1 with browser support and EPUB 2 upgrades

Why it matters

Storyteller is making part of its book-processing infrastructure available to developers building EPUB tools. The release lets developers read EPUB contents in browsers and convert EPUB 2 publications to EPUB 3, while adoption beyond Storyteller's own use remains unproven.

On October 1st, Storyteller creator Shane Friedman released version 1.0.0 of @storyteller-platform/epub, the publishing library he first built to solve a problem inside Storyteller, his audiobook-and-ebook product: changing EPUB files without breaking their existing structure. Storyteller's release post details browser support, an EPUB 2-to-EPUB 3 upgrade path, and a move from its earlier XML interface to a namespace-aware DOM.

The package has been public before. Friedman first extracted Storyteller's internal library as @smoores/epub in December 2024, after a colleague asked him how to generate EPUBs programmatically. Version 1.0.0 is the next step in that path: features that served Storyteller's own books are being packaged for developers building other tools around the format.

A product need becomes a library

Storyteller is a self-hosted platform that aligns audiobooks with ebooks, so a reader can move between listening and reading without losing their place. It writes audio timing and text markup into EPUB 3 files. Friedman described the EPUB library's origin in his 2024 announcement: Storyteller needed to modify existing books, add sentence-level markup and link chapters to media overlays. He found the available libraries too limited or inflexible for that work, so he built the capability into the product.

That origin still shapes the package. It is built for inspecting and modifying the parts of an EPUB - its metadata, reading order, text and associated files - as well as creating publications. This is lower-level work than displaying pages in an ebook reader. The package's documentation expects developers to understand at least some of the EPUB specification, while offering higher-level methods for common changes.

RuntimeWire reported in August on the alignment engine behind Storyteller's immersive reading experience. The library is another layer of that system made available outside Storyteller: the machinery that edits the book file can now be used independently of the full self-hosted platform.

The work behind v1

The release introduces two storage modes. MemoryAdapter reads EPUB contents lazily into memory and is read-only. TmpFsAdapter, the default, unpacks the book into a temporary directory and permits changes. For Node.js 24 and later, the announcement recommends JavaScript's using syntax to clean up that temporary directory when the EPUB object leaves scope.

Browser support currently works with MemoryAdapter only. Storyteller's example uses a browser File to open a book and retrieve its cover image; the library cannot write changes to the book in that mode. The post also notes a compatibility wrinkle: Safari does not support the using syntax shown in the example, so the code explicitly closes the EPUB resource.

The XML changes address a structural problem. EPUB files rely heavily on XML namespaces, and Friedman's earlier package had used fast-xml-parser, with helper methods to make its parsed data easier to navigate. Version 1 instead uses @xmldom/xmldom and exposes familiar DOM methods, including namespace-aware queries such as getAttributeNS(). Developers can also construct XML trees with a hyperscript-style x interface or write them as JSX. That could make the routine task of creating or adjusting EPUB metadata and chapter markup less dependent on string templates and custom parser helpers.

For older books, Epub.upgrade converts EPUB 2 publications to EPUB 3, either in place or at a new output path. The library operates on EPUB 3 files; EPUB 2 publications must be converted before they can be edited. Storyteller credits Thomas F. K. Jorna with implementing that upgrade path, browser support and the storage adapters.

A wider audience, with limits

Storyteller says users have load-tested the library with "hundreds of thousands" of EPUB publications. That is a company-reported cumulative figure, not a measure of independent package adoption or a performance benchmark. The first release under the new package name is available on npm, where its documented scope includes reading, modifying and creating EPUB 3 publications.

The package is for working with the structure inside book files. Developers looking for a full reader, page-rendering engine or general ebook-management system will need a different category of software. Storyteller's own platform handles audio-text alignment and reading workflows; this package supplies tools for the publication files underneath.

Version 1 broadens where developers can run the library and how they can work with XML. Adoption beyond Storyteller's own users remains to be seen.