@mozilla/readability

Readability.js is Mozilla’s standalone extraction of the algorithm that drives Firefox’s Reader View. Given a DOM document, it strips away navigation, ads, sidebars, and other chrome to return the article’s title, byline, main content, and metadata as clean HTML or text. It runs anywhere a DOM is available — directly in the browser, or in Node.js paired with an external DOM implementation such as jsdom.

The library ships two entry points: Readability, which performs the full extraction and scoring pass, and isProbablyReaderable, a cheap heuristic check used to decide whether it’s worth running the full parse at all. Both are used internally by Firefox itself, so the scoring heuristics and edge-case handling are shaped by years of production traffic against real-world pages rather than a curated test set alone.

What You Get

• The Readability class: new Readability(document, options).parse() returns { title, content, textContent, length, excerpt, byline, dir, siteName, lang, publishedTime }
• isProbablyReaderable(document, options): a fast pre-check to avoid running the full parse on pages unlikely to contain an article
• A bundled fallback JSDOMParser for constrained environments without a full DOM implementation
• Fine-grained tuning options — charThreshold, nbTopCandidates, classesToPreserve, linkDensityModifier, custom serializer — for adjusting extraction behavior per site
• TypeScript type definitions (index.d.ts) shipped in the package
• JSON-LD structured-data parsing for higher-confidence metadata extraction, with an option to disable it

Common Use Cases

• Building a read-it-later or reader-mode feature that strips ads and navigation from saved articles
• Preprocessing scraped or crawled HTML pages into clean text before feeding them to a search index or LLM pipeline
• Generating article summaries, RSS-style excerpts, or text-to-speech input from arbitrary web pages
• Powering browser extensions or content-curation tools that need a distraction-free reading view

Under The Hood

Architecture - The public surface is small by design: index.js re-exports just Readability (from Readability.js, ~2,800 lines) and isProbablyReaderable (from Readability-readerable.js). Readability.parse() runs a fixed pipeline — _prepDocument() normalizes the DOM (unwraps <noscript> images, replaces <br> runs), _grabArticle() performs the core scoring pass by walking candidate block elements and accumulating a content score from text length, comma count, and tag-name weighting, then climbing ancestors to find the best-scoring container, and _postProcessContent() cleans classes, fixes relative URIs, and simplifies nested wrapper elements before metadata (title, byline, JSON-LD-preferred site info) is attached to the returned object. A bundled JSDOMParser.js provides a minimal DOM implementation as a fallback for environments without one, though the library’s normal path expects a real document.

Tech Stack - Zero runtime dependencies — the entire extraction algorithm is dependency-free vanilla JavaScript operating on the standard DOM API, which is what lets it run identically in a browser and in Node.js (paired with jsdom as a devDependency for testing and documented Node usage). Tooling is conventional: ESLint 8 with the Mozilla ESLint config, Prettier for formatting, Mocha/Chai for tests, and release-it for versioned releases with a keep-a-changelog integration. TypeScript consumers get first-class types via a hand-written index.d.ts shipped alongside the JS source rather than compiled output.

Code Quality - Test coverage is substantial and fixture-driven: test/test-readability.js (398 lines) runs the full parser against 130 real-world test-pages fixtures, each pairing captured HTML source with an expected extraction output, plus dedicated suites for isProbablyReaderable and the bundled JSDOMParser. Internal methods are consistently prefixed with _ to signal private API, and the scoring logic is broken into small, named helper methods (_getClassWeight, _getLinkDensity, _isPhrasingContent) rather than one monolithic function, which keeps the otherwise-complex heuristic pipeline traceable. No TypeScript source (types are hand-authored separately), and error handling is minimal by nature of the domain — malformed input degrades to a null/low-quality result rather than throwing.

API Design - The public API is deliberately tiny: construct new Readability(document, options) and call .parse(), or call isProbablyReaderable(document) as a cheap pre-check. Options are flat and well-documented inline in the README and index.d.ts (charThreshold, nbTopCandidates, serializer, etc.), and the returned object’s shape is fixed and predictable. The main ergonomic wrinkle is environment setup — Node.js callers must bring their own DOM via jsdom and are warned in the README to clone the document first, since parse() mutates it in place.