epubcheck-ts

Validate EPUB files in Node.js and the browser. A TypeScript implementation of EPUBCheck.

Status: 93% feature parity with Java EPUBCheck (1038 tests passing). See PROJECT_STATUS.md for details. For full EPUB 3 conformance testing, use the official Java EPUBCheck.

Features

CLI and API — Use as a CLI tool (npx @likecoin/epubcheck-ts book.epub) or import as a library
Browser support — Works in Node.js 18+ and modern browsers via pure JS + WASM
No native dependencies — No Java, no compilation — npm install and go
TypeScript — Full type definitions included
Tree-shakable — ESM with proper exports for minimal bundle impact

Try it Online

Live demo at likecoin.github.io/epubcheck-ts — validate EPUB files in the browser without uploading to any server.

Installation

npm install @likecoin/epubcheck-ts

Quick Start

Command Line Interface (CLI)

Quick validation:

npx @likecoin/epubcheck-ts book.epub

Or install globally:

npm install -g @likecoin/epubcheck-ts
epubcheck-ts book.epub

CLI Options:

epubcheck-ts <file.epub> [options]

Options:
  -j, --json <file>        Output JSON report to file (use '-' for stdout)
  -q, --quiet              Suppress console output (errors only)
  -p, --profile <name>     Validation profile (default|dict|edupub|idx|preview)
  -w, --fail-on-warnings   Exit with code 1 if warnings are found
  -v, --version            Show version information
  -h, --help               Show this help message

Examples:

# Basic validation
epubcheck-ts book.epub

# Generate JSON report
epubcheck-ts book.epub --json report.json

# Quiet mode for CI/CD
epubcheck-ts book.epub --quiet --fail-on-warnings

# Validate with specific profile
epubcheck-ts dictionary.epub --profile dict

ES Modules (recommended)

import { EpubCheck } from '@likecoin/epubcheck-ts';
import { readFile } from 'node:fs/promises';

// Load EPUB file
const epubData = await readFile('book.epub');

// Validate
const result = await EpubCheck.validate(epubData);

if (result.valid) {
  console.log('EPUB is valid!');
} else {
  console.log(`Found ${result.errorCount} errors and ${result.warningCount} warnings`);
  
  for (const message of result.messages) {
    console.log(`${message.severity}: ${message.message}`);
    if (message.location) {
      console.log(`  at ${message.location.path}:${message.location.line}`);
    }
  }
}

CommonJS

const fs = require('node:fs');

async function validate() {
  const { EpubCheck } = await import('epubcheck-ts');
  
  const epubData = fs.readFileSync('book.epub');
  const result = await EpubCheck.validate(epubData);
  
  console.log(result.valid ? 'Valid!' : 'Invalid');
}

validate();

Browser

import { EpubCheck } from '@likecoin/epubcheck-ts';

// From file input
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (event) => {
  const file = event.target.files[0];
  const data = new Uint8Array(await file.arrayBuffer());
  
  const result = await EpubCheck.validate(data);
  console.log(result);
});

API

Full API reference: online | markdown

`EpubCheck.validate(data, options?)`

Static method to validate an EPUB file.

Parameters:

data: Uint8Array - The EPUB file contents
options?: EpubCheckOptions - Optional validation options

Returns: Promise<EpubCheckResult>

`new EpubCheck(options?)`

Create a reusable validator instance.

const checker = new EpubCheck({
  version: '3.3',
  profile: 'default',
  locale: 'en',
});

const result1 = await checker.check(epub1Data);
const result2 = await checker.check(epub2Data);

Options

interface EpubCheckOptions {
  /** EPUB version to validate against (auto-detected if not specified) */
  version?: '2.0' | '3.0' | '3.1' | '3.2' | '3.3';
  
  /** Validation profile */
  profile?: 'default' | 'edupub' | 'idx' | 'dict' | 'preview';
  
  /** Include usage messages in results (default: false) */
  includeUsage?: boolean;
  
  /** Include info messages in results (default: true) */
  includeInfo?: boolean;
  
  /** Maximum errors before stopping, 0 = unlimited (default: 0) */
  maxErrors?: number;
  
  /** Locale for messages (default: 'en') */
  locale?: string;
}

Result

interface EpubCheckResult {
  /** Whether the EPUB is valid (no errors or fatal errors) */
  valid: boolean;
  
  /** All validation messages */
  messages: ValidationMessage[];
  
  /** Counts by severity */
  fatalCount: number;
  errorCount: number;
  warningCount: number;
  infoCount: number;
  usageCount: number;
  
  /** Detected EPUB version */
  version?: string;
  
  /** Validation time in milliseconds */
  elapsedMs: number;
}

interface ValidationMessage {
  /** Unique message identifier (e.g., 'OPF-001') */
  id: string;
  
  /** Severity level */
  severity: 'fatal' | 'error' | 'warning' | 'info' | 'usage';
  
  /** Human-readable message */
  message: string;
  
  /** Location in the EPUB */
  location?: {
    path: string;
    line?: number;
    column?: number;
    context?: string;
  };
  
  /** Suggestion for fixing the issue */
  suggestion?: string;
}

JSON Report

Generate a JSON report compatible with the original EPUBCheck:

import { EpubCheck, Report } from '@likecoin/epubcheck-ts';

const result = await EpubCheck.validate(data);
const jsonReport = Report.toJSON(result);
console.log(jsonReport);

Supported Environments

Environment	Version	Notes
Node.js	18+	Full support
Chrome	89+	Full support
Firefox	89+	Full support
Safari	15+	Full support
Edge	89+	Full support

Architecture

This library is a TypeScript port of the Java-based EPUBCheck tool maintained by the W3C. Key implementation details:

XML Processing: Uses libxml2-wasm for XML parsing and schema validation (RelaxNG, XSD) via WebAssembly
ZIP Handling: Uses fflate for fast, lightweight EPUB container processing
CSS Validation: Uses css-tree for CSS parsing and validation
Schematron: Uses fontoxpath with slimdom for XPath 3.1 evaluation

Validation Coverage

Component	Status	Completeness	Notes
OCF Container	🟢 Complete	~92%	ZIP structure, mimetype, container.xml, encryption.xml obfuscation
Package Document (OPF)	🟢 Complete	~92%	Metadata, manifest, spine, collections, Schematron-equivalent checks
Content Documents	🟢 Complete	~93%	XHTML structure, CSS url(), @import, SVG, entities, title, SSML, XML version
Navigation Document	🟢 Complete	~85%	Nav content model, landmarks, labels, reading order, hidden
Schema Validation	🟡 Partial	~55%	RelaxNG for OPF/container; XHTML/SVG disabled (libxml2 limitation)
CSS	🟡 Partial	~75%	@font-face, @import, url() extraction, position, forbidden properties
Cross-reference Validation	🟢 Complete	~92%	Reference tracking, fragments, fallbacks, remote resources
Accessibility Checks	🟡 Partial	~30%	Basic checks only (empty links, image alt, SVG titles)
Media Overlays	🟡 Partial	~70%	SMIL structure, timing, audio, OPF metadata, duration validation
Media Validation	❌ Not Started	0%	Planned

Legend: 🟢 Complete | 🟡 Partial | 🔴 Basic | ❌ Not Started

Overall Progress: ~93% of Java EPUBCheck features

See PROJECT_STATUS.md for detailed comparison.

Development

Prerequisites

Node.js 18+
npm 9+

Setup

# Clone the repository
git clone https://github.com/likecoin/epubcheck-ts.git
cd epubcheck-ts

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

Scripts

Script	Description
`npm run build`	Build the library (ESM + CJS)
`npm run dev`	Build in watch mode
`npm test`	Run tests in watch mode
`npm run test:run`	Run tests once
`npm run test:coverage`	Run tests with coverage
`npm run lint`	Lint with ESLint
`npm run lint:fix`	Lint and auto-fix
`npm run format`	Format with Biome
`npm run typecheck`	TypeScript type checking
`npm run check`	Run all checks (format + typecheck)
`npm run docs`	Generate API docs (HTML + Markdown)
`npm run docs:html`	Generate HTML API docs to `docs/html/`
`npm run docs:md`	Generate Markdown API docs to `docs/md/`

Project Structure

epubcheck-ts/
├── src/
│   ├── index.ts           # Public API exports
│   ├── checker.ts         # Main EpubCheck class
│   ├── types.ts           # TypeScript type definitions
│   ├── core/              # Core validation logic
│   ├── ocf/               # OCF container validation ✅
│   ├── opf/               # Package document validation ✅
│   ├── content/           # Content document validation ✅
│   ├── nav/               # Navigation validation ✅
│   ├── ncx/               # NCX validation (EPUB 2) ✅
│   ├── references/        # Cross-reference validation ✅
│   ├── schema/            # Schema validation ✅
│   │   ├── relaxng.ts     # RelaxNG validation
│   │   ├── xsd.ts         # XSD validation
│   │   ├── schematron.ts  # Schematron validation
│   │   └── orchestrator.ts # Schema orchestration
│   └── messages/          # Error messages
├── schemas/               # Schema files (RNG, RNC, SCH)
├── test/
│   ├── fixtures/          # Test EPUB files
│   └── integration/       # Integration tests
├── docs/
│   └── md/                # Generated API docs (Markdown, checked in)
├── examples/
│   └── web/               # Web demo ✅
└── dist/                  # Build output

Legend: ✅ Implemented

Comparison with Java EPUBCheck

Aspect	epubcheck-ts	EPUBCheck (Java)
Runtime	Node.js / Browser	JVM
Feature Parity	~93%	100%
Bundle Size	~450KB JS + ~1.6MB WASM	~15MB
Installation	`npm install`	Download JAR
Integration	Native JS/TS	CLI or Java API
Performance	Comparable	Baseline

See PROJECT_STATUS.md for detailed feature comparison.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

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

License

GPL-3.0

This is an independent TypeScript implementation inspired by the Java-based EPUBCheck (BSD-3-Clause). No code was directly copied from the original project.

Acknowledgments

W3C EPUBCheck - The original Java implementation
DAISY Consortium - Maintainers of EPUBCheck
libxml2-wasm - WebAssembly XML processing

Built by 3ook.com

This project is built and maintained by the 3ook.com team. 3ook is a Web3 eBook platform where authors can publish EPUB ebooks and readers can collect them as digital assets. If you're an author looking to publish your ebook, check out 3ook.com.

Related Projects

EPUBCheck - Official Java validator
epub.js - EPUB reader library
r2-shared-js - Readium shared models

Name		Name	Last commit message	Last commit date
Latest commit History 166 Commits
.github		.github
bin		bin
docs/md		docs/md
examples/web		examples/web
schemas		schemas
scripts		scripts
src		src
test		test
.gitignore		.gitignore
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PROJECT_STATUS.md		PROJECT_STATUS.md
README.md		README.md
biome.json		biome.json
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
typedoc.json		typedoc.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

epubcheck-ts

Features

Try it Online

Installation

Quick Start

Command Line Interface (CLI)

ES Modules (recommended)

CommonJS

Browser

API

EpubCheck.validate(data, options?)

new EpubCheck(options?)

Options

Result

JSON Report

Supported Environments

Architecture

Validation Coverage

Development

Prerequisites

Setup

Scripts

Project Structure

Comparison with Java EPUBCheck

Contributing

License

Acknowledgments

Built by 3ook.com

Related Projects

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`EpubCheck.validate(data, options?)`

`new EpubCheck(options?)`

Packages