Trafilatura Core npm library
Use Node.js 22.22.2+ on 22.x, 24.15.0+ on 24.x, or 26+:
npm init -y
npm install @markdownee/trafilaturacore
Save this as clean.mjs (.mjs enables ES modules):
import { clean } from "@markdownee/trafilaturacore";
const input = "<nav>Home</nav><p>Saved article text.</p>";
const result = await clean(input, { boilerplate: "keep" });
console.log(result.html);
node clean.mjs
It prints <p>Saved article text.</p>. Use the default balanced mode to
extract a full article's main content; keep skips extraction and applies cleanup.
Options and results
clean(html, options?) returns a promise of html, diagnostic messages,
and optional metadata. Metadata includes available title, author, date, sitename,
tags, and other declared fields. declaredPageType is the page's OpenGraph type
or an upstream-recognized JSON-LD type; it does not select an extraction strategy.
| Option | Values and behavior |
|---|---|
boilerplate | precision, balanced (default), recall, keep |
imageHandling | include (default), exclude, alt-text, resolved-url |
linkHandling, tableHandling, commentHandling | include (default) or exclude |
url | Source URL for metadata and relative-image context; never fetched |
config | JSON-serializable cleaning policy replacing the default |
maxInputBytes | Positive safe integer; defaults to 10 MiB UTF-8 |
Content controls explain what each mode retains.
The exported Boilerplate, ImageHandling, LinkHandling, TableHandling,
and CommentHandling aliases represent the same string values.
Custom cleaning
CleanConfig accepts allowedTags, allowedAttributes, allowedClasses,
selfClosing, nonTextTags, and transformTags. It replaces the default
policy; nonTextTags discards a subtree, while disallowed ordinary tags are
unwrapped. The exported DEFAULT_CLEAN_CONFIG provides the default policy;
isCleanConfig and cleanConfigError validate a candidate.
Custom policies still filter scripts, event handlers, dangerous URL schemes, and unsafe inline CSS. Remote links and images can remain. Before rendering untrusted output, sanitize for your output context and apply a Content Security Policy; extraction is not a security boundary.
Presentation and limits
prepare() returns cleaned HTML before presentation. Passing its html to
formatSecuredHtml() produces compact output without repeating extraction.
A formatting failure returns cleaned unformatted HTML with a warning.
Invalid input/options throw TypeError; input above maxInputBytes throws
RangeError. Every mode runs byte, token, and depth checks before DOM parsing;
structural limits reject with ERR_TRAFILATURACORE_RESOURCE_LIMIT.
Extraction runs synchronously inside the async API and occupies the event loop;
the API does not provide cancellation.
See CLI usage for shell processing and Python for the native API and its differences.
Updated: September 25, 2026