epub-parser

0.2.5 verified Sat May 09 auth: no javascript abandoned

A library for parsing EPUB files into JSON, simplifying access to metadata, table of contents, and structural elements. Version 0.2.5 (last updated 2014) is a stable but archaic release with low maintenance. It depends on xml2js, node-zip, and eyes for logging. Unlike modern alternatives (e.g., epub.js), it runs only in Node.js and converts EPUB's internal XML (NCX, OPF) into nested JSON objects, providing both an 'easy' simplified namespace and a 'raw' direct mapping. No longer actively developed; consider for parsing older EPUB2 files, but lacks support for EPUB3, async/await, and streaming.

Common errors

error Error: Cannot find module 'node-zip' ↓

cause Missing dependency node-zip, which is required for unzipping EPUB files.

fix

Run 'npm install node-zip' or add it to your package.json.

error TypeError: epubParser.open is not a function ↓

cause Using ES module import syntax (import) on a CommonJS-only module that does not export a default.

fix

Use const epubParser = require('epub-parser') instead of import.

error Error: ENOENT: no such file or directory, open 'path/to/file.epub' ↓

cause The provided path does not point to an existing EPUB file.

fix

Double-check the file path and ensure the file exists.

Warnings

deprecated Library is unmaintained since 2014. Expect no bug fixes or updates for modern Node.js versions (10+). ↓

fix Consider migrating to active alternatives like epub.js (browser) or epub2 (Node).

gotcha The open function expects a file path string, but does not validate the input. Passing a buffer or URL will cause silent failures. ↓

fix Ensure the argument is a valid file path to an existing .epub file on disk.

gotcha Callback style only; no Promise or async/await support. Error handling is mandatory as errors may be thrown if the file is corrupt. ↓

fix Always handle the 'err' parameter in the callback. Use a promise wrapper if needed.

deprecated Dependency 'node-zip' is obsolete and uses a non-standard compression library. Unzipping may fail on large files or with special characters. ↓

fix Replace with a modern zip library like adm-zip or yauzl if forking.

gotcha The 'easy.navMapHTML' property may contain invalid HTML or missing closing tags. It is not sanitized for XSS. ↓

fix Sanitize the HTML output with a library like DOMPurify before rendering.

Install

npm install epub-parser

yarn add epub-parser

pnpm add epub-parser

Imports

open

wrong

import epubParser from 'epub-parser';
epubParser.open(...);

correct

var epubParser = require('epub-parser');
epubParser.open('path/to/book.epub', function(err, data) { ... });

Library uses CommonJS and does not support ESM import. The open function takes a path (not a buffer) and a callback.

easy

wrong

var easy = require('epub-parser').easy;

correct

var epubParser = require('epub-parser');
epubParser.open(path, function(err, data) { console.log(data.easy); });

The 'easy' namespace is only available after opening an EPUB file, not as a static export.

raw

wrong

var raw = require('epub-parser').raw;

correct

var epubParser = require('epub-parser');
epubParser.open(path, function(err, data) { console.log(data.raw.json.ncx); });

Same pattern: 'raw' is a property of the object passed to the callback, not a top-level export.

Quickstart

Shows basic usage of opening an EPUB file and accessing both the simplified 'easy' and detailed 'raw' namespaces from the callback.

var epubParser = require('epub-parser');
var path = '/path/to/book.epub';
epubParser.open(path, function(err, data) {
  if (err) {
    console.error('Error:', err);
    return;
  }
  console.log('Easy namespace:', data.easy);
  console.log('Raw NCX:', data.raw.json.ncx);
  console.log('NavMap HTML:', data.easy.navMapHTML);
});