{"id":27720,"library":"epub-parser","title":"epub-parser","description":"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.","status":"abandoned","version":"0.2.5","language":"javascript","source_language":"en","source_url":"git://github.com/Vaporbook/epub-parser","tags":["javascript","epub"],"install":[{"cmd":"npm install epub-parser","lang":"bash","label":"npm"},{"cmd":"yarn add epub-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add epub-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"XML-to-JSON conversion for EPUB metadata and NCX files","package":"xml2js","optional":false},{"reason":"Unzipping EPUB archive to access internal files","package":"node-zip","optional":false},{"reason":"Inspector for debugging data structures (optional, can be replaced with console)","package":"eyes","optional":true}],"imports":[{"note":"Library uses CommonJS and does not support ESM import. The open function takes a path (not a buffer) and a callback.","wrong":"import epubParser from 'epub-parser';\nepubParser.open(...);","symbol":"open","correct":"var epubParser = require('epub-parser');\nepubParser.open('path/to/book.epub', function(err, data) { ... });"},{"note":"The 'easy' namespace is only available after opening an EPUB file, not as a static export.","wrong":"var easy = require('epub-parser').easy;","symbol":"easy","correct":"var epubParser = require('epub-parser');\nepubParser.open(path, function(err, data) { console.log(data.easy); });"},{"note":"Same pattern: 'raw' is a property of the object passed to the callback, not a top-level export.","wrong":"var raw = require('epub-parser').raw;","symbol":"raw","correct":"var epubParser = require('epub-parser');\nepubParser.open(path, function(err, data) { console.log(data.raw.json.ncx); });"}],"quickstart":{"code":"var epubParser = require('epub-parser');\nvar path = '/path/to/book.epub';\nepubParser.open(path, function(err, data) {\n  if (err) {\n    console.error('Error:', err);\n    return;\n  }\n  console.log('Easy namespace:', data.easy);\n  console.log('Raw NCX:', data.raw.json.ncx);\n  console.log('NavMap HTML:', data.easy.navMapHTML);\n});","lang":"javascript","description":"Shows basic usage of opening an EPUB file and accessing both the simplified 'easy' and detailed 'raw' namespaces from the callback."},"warnings":[{"fix":"Consider migrating to active alternatives like epub.js (browser) or epub2 (Node).","message":"Library is unmaintained since 2014. Expect no bug fixes or updates for modern Node.js versions (10+).","severity":"deprecated","affected_versions":">=0.2.0"},{"fix":"Ensure the argument is a valid file path to an existing .epub file on disk.","message":"The open function expects a file path string, but does not validate the input. Passing a buffer or URL will cause silent failures.","severity":"gotcha","affected_versions":"*"},{"fix":"Always handle the 'err' parameter in the callback. Use a promise wrapper if needed.","message":"Callback style only; no Promise or async/await support. Error handling is mandatory as errors may be thrown if the file is corrupt.","severity":"gotcha","affected_versions":"*"},{"fix":"Replace with a modern zip library like adm-zip or yauzl if forking.","message":"Dependency 'node-zip' is obsolete and uses a non-standard compression library. Unzipping may fail on large files or with special characters.","severity":"deprecated","affected_versions":"0.2.x"},{"fix":"Sanitize the HTML output with a library like DOMPurify before rendering.","message":"The 'easy.navMapHTML' property may contain invalid HTML or missing closing tags. It is not sanitized for XSS.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Run 'npm install node-zip' or add it to your package.json.","cause":"Missing dependency node-zip, which is required for unzipping EPUB files.","error":"Error: Cannot find module 'node-zip'"},{"fix":"Use const epubParser = require('epub-parser') instead of import.","cause":"Using ES module import syntax (import) on a CommonJS-only module that does not export a default.","error":"TypeError: epubParser.open is not a function"},{"fix":"Double-check the file path and ensure the file exists.","cause":"The provided path does not point to an existing EPUB file.","error":"Error: ENOENT: no such file or directory, open 'path/to/file.epub'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}