unified

unified is the core interface for processing content as structured data using abstract syntax trees. It ties together a parser, a chain of plugin transformers, and a compiler into a single processor, so you can turn text into a tree, manipulate that tree with reusable plugins, and serialize it back out.

As the foundation of the remark (markdown), rehype (HTML), and retext (natural language) ecosystems, unified powers tools like MDX, Gatsby, Docusaurus, and Prettier, and is used in over a million projects on GitHub. You pick and choose plugins to build custom content pipelines without needing to understand the underlying tree formats.

What You Get

• A single unified() processor factory that chains parse, transform, and stringify phases
• A .use() plugin API for composing reusable transformers and presets
• Both async (process) and sync (processSync) processing, plus lower-level parse, run, and stringify steps
• Integration with the remark, rehype, and retext ecosystems and 500+ plugins
• First-class TypeScript types for parsers, compilers, plugins, and processors

Common Use Cases

• Building markdown-to-HTML pipelines with remark and rehype plugins
• Linting and transforming prose or documentation as part of a build
• Bridging between content formats (markdown, HTML, natural language) in one workflow

Under The Hood

Architecture — unified’s runtime lives in a single lib/index.js that defines a CallableInstance-based unified function (see lib/callable-instance.js), where each processor is both callable and an object carrying parse, run, stringify, process, and use. Calling a processor clones its frozen configuration into a fresh descendant, so ancestors are never mutated; freeze() seals a processor before export. The three phases — parse (text → tree via a Parser), run (tree → tree via a trough pipeline of Transformers), and stringify (tree → output via a Compiler) — are orchestrated through the trough library, which sequences sync and async transformers and threads a vfile for data, metadata, and messages.

Tech Stack — Pure ESM JavaScript (Node 16+), typed entirely through JSDoc with a hand-written index.d.ts. Runtime dependencies are minimal and focused: trough (middleware pipeline), vfile (virtual file format), bail, extend, is-plain-obj, devlop (dev-only assertions), and @types/unist. Build and quality tooling includes TypeScript project references, tsd for type tests, c8 for 100% coverage enforcement, xo/prettier for linting, and type-coverage pinned at 100%.

Code Quality — Exceptionally rigorous: the test suite under test/ covers every phase and edge case across core.js, freeze.js, parse.js, process.js, run.js, stringify.js, use.js, and more, and CI enforces 100% code coverage and 100% type coverage. Error handling is explicit through bail and vfile messages, naming is consistent, and the public surface is fully documented with inline JSDoc that doubles as the TypeScript API.

API Design — The API is deliberately tiny and highly ergonomic: unified().use(plugin, options).process(file) reads almost like prose, and the same processor exposes lower-level parse/run/stringify for advanced control. Plugins are just functions returning an optional transformer, making the extension model trivial to learn. The extensive readme, worked examples, and precise TypeScript types keep boilerplate near zero, though understanding syntax trees and the plugin lifecycle presents a moderate conceptual learning curve.