[![npm version](https://badge.fury.io/js/@publiwrite%2Fhtml-to-epub.svg)](https://badge.fury.io/js/@publiwrite%2Fhtml-to-epub)

# @publiwrite/html-to-epub

Generate EPUB books from HTML with a simple API in Node.js. Originally
inspired by [cyrilis/epub-gen](https://github.com/cyrilis/epub-gen/),
hard-forked by PubliWrite to target Node 22+ exclusively, add EPUB 3.3
compliance, parallel I/O, and a permanent W3C epubcheck gate.

## Why this fork

The original `epub-gen` is unmaintained (last commit 2022) and was
written against Node 14 conventions: serial image downloads, sync
fs ops, no security guards, no validation gate. PubliWrite needed an
EPUB generator that:

1. Produces output that **passes W3C epubcheck 5.3.0 cleanly** as a
   blocking gate, not a "best effort" target.
2. Generates EPUBs that **render correctly in epub.js** (the engine
   PubliWrite's reader app uses), **Kindle Previewer 3** (Amazon's
   official tool), **Calibre**, and **Apple Books**.
3. Handles the throughput of a Lambda render pipeline: 30+ chapters,
   100+ images per book, sub-30s wall-clock budgets.
4. Refuses to ship unsafe content silently (`file://` reads, inline
   `<script>`, oversized image bodies, etc.).

The fork started as a perf rewrite and grew an EPUB 3.3 spec-compliance
pass + a security pass + a JAR-gated test matrix.

## What changed vs upstream

### EPUB 3.3 spec compliance fixes (PR #3)

| Bug | epubcheck rule | Fix |
|---|---|---|
| `cover.xhtml` declared twice in OPF manifest | `OPF-074` | Added `isCover` marker on the cover entry, skipped in the content forEach |
| Inline SVG cover missing manifest property | `OPF-014` | `<item id="cover" ... properties="svg"/>` in epub3 template |
| Broken cover URL in warn mode left dangling manifest reference | `RSC-001` | `makeCover` catch nulls cover state + filters the cover entry from `this.content` |
| EPUB 2 cover used HTML5 `<meta charset>`, `epub:type` without xmlns, SVG 2 bare `href` | `RSC-005`, `RSC-016` | Three tags now conditional on `version === 3` in the cover template |
| Empty chapter title produced `<title></title>` in chapter head | `RSC-005` | Fall back to `bookTitle`, then to "Untitled" |

### Perf + security

- Parallel image download via `p-limit` semaphore (was a serial loop)
- HTTP keep-alive socket pool (was per-request socket)
- ZIP compression default `9 -> 6` (10x faster, 2-5% larger output)
- `stream/promises.pipeline` for cover + image writes (was racy `pipe()`)
- Optional `assetFailureMode: 'throw'` (default `'warn'` for back-compat)
- Strip 53 `on*` event-handler attributes from sanitiser allowlist
- Strip `<script>`, `<iframe>`, `<object>`, `<embed>`, `<applet>`
- Reject `file://` image / cover URLs by default (`allowFileUrls: true` to opt in)
- Hard 30s fetch timeout, 100 MB per-image size cap

### Stack

- Node 22+ required (was Node 14+); ESM only
- `slugify` replaced `uslug + diacritics`
- `image-size` v1 -> v2 (sync Buffer API)
- `p-limit` v6 -> v7
- `vitest` replaces `mocha + ts-node`
- `yarn.lock` now committed (was gitignored)

## Usage

```bash
npm install @publiwrite/html-to-epub
```

```javascript
import { EPub } from "@publiwrite/html-to-epub";

const epub = new EPub(options, outputPath);
await epub.render();
```

### Options

The legacy fields (`title`, `author`, `cover`, `content`, etc.) work
identically to upstream. New fields:

- `assetFailureMode`: `'warn'` (default, back-compat) or `'throw'`.
  Production callers should use `'throw'` so a dead cover URL or
  missing inline image rejects `render()` instead of silently
  shipping a broken manifest reference.
- `allowFileUrls`: default `false`. Reject `file://` URLs (an
  arbitrary-file-read vector when chapter HTML is user-controlled).
  Set to `true` for trusted offline tooling and tests.
- `imageDownloadConcurrency`: default `8`. Max concurrent image
  fetches across the whole book.
- `zipCompressionLevel`: default `6`. `0`-`9`. Lower is faster, EPUB
  payloads are mostly fonts and already-compressed images so the
  marginal saving from `9` is tiny.

See `src/index.ts` for the full `EpubOptions` interface and inline
comments on every option.

## Validation toolchain

The fork ships a real W3C epubcheck gate in the test suite. CI and
local `yarn test` both refuse to pass unless the canonical Amazon
toolchain accepts every fixture.

### How the gate works

`tests/epub.spec.ts` contains 50+ vitest cases. The last describe block
(`epubcheck compliance`) spawns the **canonical W3C epubcheck 5.3.0
JAR** via `java -jar` on a matrix of production-shaped fixtures:

- minimal EPUB 3
- multi-chapter
- with cover
- with data URI image
- mixed data URI + HTTP image
- broken cover (warn mode) — graceful degradation
- EPUB 2 minimal
- EPUB 2 with cover
- chapter with `ornamentalBreakElement` inline SVG (via custom template)
- `beforeToc` / `excludeFromToc` spine ordering
- realistic Plate-shaped chapter (headings + lists + blockquote + footnote)
- empty chapter title fallback

Each fixture must emit `Messages: 0 fatals / 0 errors` from epubcheck
or the test fails.

### Running the gate locally

```bash
yarn test                # runs the install script first, then vitest
yarn test:no-jar         # skip the JAR-gated tests (no Java required)
yarn install:epubcheck   # one-shot JAR install only
```

Requires Java on `PATH`. The JAR is downloaded once into
`.epubcheck/epubcheck-5.3.0/epubcheck.jar` (gitignored). Re-runs are
near-zero cost because the install script short-circuits when the JAR
already exists.

### Why this gate is non-skippable

An earlier iteration of the gate skipped silently when Java or the JAR
was missing — turning the test suite into a structural rubber stamp. The
fix made the install part of `yarn test`, so a CI runner without epubcheck
fails loud instead of green-by-accident. Cross-engine review (Codex +
Sonnet) consensus-flagged this as the highest-priority gap on the first
landing of the matrix.

### Beyond the library: PubliWrite-side validation

PubliWrite's manuscript-render lambda ships its own validation harness
that takes real prod Yjs manuscripts through the **lambda's full
pipeline** (Plate render + bundled fonts + plate.css + cover) and runs
**five reader engines** against each output:

1. W3C epubcheck 5.3.0 (same JAR as this fork)
2. epub.js (futurepress) — the engine the FE reader app + the
   location-extraction lambda both use
3. Calibre EPUB→AZW3 (Kindle binary compat proxy)
4. **Kindle Previewer 3** (Amazon's canonical KDP validator)
5. Apple Books (`open -a Books`)

That harness lives in
`pw-lambda-functions/lambdas/manuscript-render/scripts/`. See:

- `setup-validators.sh` — idempotent installer (brew + cask)
- `run-all-validators.sh` — one-shot N-manuscript sweep
- `validate-prod-epubcheck.ts` — epubcheck + epub.js gate
- `cross-reader-check.ts` — Calibre + KP3 batch + Books gate

Verified result on N=100 prod manuscripts (latest sweep):
- 100/100 pass W3C epubcheck 3.3
- 100/100 pass epub.js (non-empty CFI locations)
- 100/100 pass Calibre EPUB→AZW3
- 100/100 pass Kindle Previewer 3 (Enhanced Typesetting supported)

(Lambda repo private; cross-reference for PubliWrite contributors.)

## Local development

```bash
git clone https://github.com/publiwrite/html-to-epub
cd html-to-epub
yarn install
yarn install:epubcheck    # one-time
yarn test                 # ~90s on M-series Mac
yarn build                # tsc to lib/
```

Engines: Node 20 or 22 only. Node 18 is dropped (was upstream's
target; we use `Promise.any`, top-level await, and `image-size` v2
which all require ≥ 20).

For ad-hoc smokes against a single Yjs blob, see the lambda repo's
`scripts/build-one.mts` helper.

## Original API reference

Everything below is the original `epub-gen` API documentation. All
fields work as documented; the new fields are the ones listed in the
"Options" section above.

### Options

-   `title`:
    Title of the book
-   `author`:
    Name of the author for the book, string or array, eg. `"Alice"` or `["Alice", "Bob"]`
-   `publisher`:
    Publisher name (optional)
-   `cover`:
    Book cover image (optional), File path (absolute path) or web url, eg. `"http://abc.com/book-cover.jpg"` or `"/User/Alice/images/book-cover.jpg"`
-   `output`
    Out put path (absolute path), you can also path output as the second argument when use `new` , eg: `new Epub(options, output)`
-   `version`:
    You can specify the version of the generated EPUB, `3` the latest version (http://idpf.org/epub/30) or `2` the previous version (http://idpf.org/epub/201, for better compatibility with older readers). If not specified, will fallback to `3`.
-   `css`:
    If you really hate our css, you can pass css string to replace our default style. eg: `"body{background: #000}"`
-   `fonts`:
    Array of (absolute) paths to custom fonts to include on the book so they can be used on custom css. Ex: if you configure the array to `fonts: ['/path/to/Merriweather.ttf']` you can use the following on the custom CSS:

    ```
    @font-face {
        font-family: "Merriweather";
        font-style: normal;
        font-weight: normal;
        src : url("./fonts/Merriweather.ttf");
    }
    ```

-   `lang`:
    Language of the book in 2 letters code (optional). If not specified, will fallback to `en`.
-   `tocTitle`:
    Title of the table of contents. If not specified, will fallback to `Table Of Contents`.
-   `includeToc`:
    Generate and include a table of contents page in the book. If set to `false`, the TOC page will not appear in the generated EPUB. Default: `true`.
-   `appendChapterTitles`:
    Automatically append the chapter title at the beginning of each contents. You can disable that by specifying `false`.
-   `customOpfTemplatePath`:
    Optional. For advanced customizations: absolute path to an OPF template.
-   `customNcxTocTemplatePath`:
    Optional. For advanced customizations: absolute path to a NCX toc template.
-   `customHtmlTocTemplatePath`:
    Optional. For advanced customizations: absolute path to a HTML toc template.
-   `content`:
    Book Chapters content. It's should be an array of objects. eg. `[{title: "Chapter 1",data: "<div>..."}, {data: ""},...]`

    **Within each chapter object:**

    -   `title`:
        optional, Chapter title
    -   `author`:
        optional, if each book author is different, you can fill it.
    -   `data`:
        required, HTML String of the chapter content. image paths should be absolute path (should start with "http" or "https"), so that they could be downloaded. With the upgrade is possible to use local images (for this the path must start with file: //)
    -   `excludeFromToc`:
        optional, if is not shown on Table of content, default: false;
    -   `beforeToc`:
        optional, if is shown before Table of content, such like copyright pages. default: false;
    -   `filename`:
        optional, specify filename for each chapter, default: undefined;

-   `verbose`:
    specify whether or not to console.log progress messages, default: false.

#### Output

If you don't want pass the output pass the output path as the second argument, you should specify output path as `option.output`.