Open-source project
unifiedjs/unified avatar
unifiedjs/unified

unified: parse, run, stringify, and the plugins that fill the gaps

Parse, inspect, transform, and serialize content with syntax trees

5,053 stars136 forksJavaScriptMIT

At a glance

What is it?
unified is the small ESM only core that the remark, rehype and retext ecosystems plug into. It parses nothing and compiles nothing on its own, which makes it a pipeline to understand rather than a tool to install and run.
Who is it for?
Reach for unified when one document mixes content types, or when you are writing a plugin that has to sit between two trees. For a single format, the ecosystem package such as remark is the shorter path.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 43 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • unifiedjs/unified5,053 ★ · +18
Star history
Repository2026-09-232026-11-15
unifiedjs/unified5k5.1k

18 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The root processor does nothing until you attach plugins

A bare unified() is not a parser, a compiler or a transformer. On its own the root processor does not work, because nothing is attached to it, and the runtime dependency list holds no parser and no compiler either: vfile, trough, bail, extend, devlop, is-plain-obj and the unist types are all there is. The library is a pipeline that other packages fill.

What you get instead is four entry points, one per stage. parse turns text into a syntax tree, run works on the tree, stringify turns the tree back into text, and process does all three in order. A processor built from remarkParse and rehypeStringify alone can parse markdown and compile a tree, but the stage in between stays empty until you add something to it.

Exported processors are frozen so one caller cannot change another's

Processors implement processors. You create one by calling another, and the new processor starts out configured the same way as its ancestor, but configuring the descendant later does not touch the ancestor. That rule exists because modules export ready made processors, and configuring one of those directly would change its behaviour for every module user at once. Such processors are frozen, and the documented way to use one is to call it and get a fresh processor.

The consequence shows up in wrappers and shared helpers rather than in your own scripts. If a function hands you a processor and you call .use() on the object in front of you, you have changed state that the caller also holds. Calling the exported processor again instead of configuring the instance you were given keeps that state to yourself.

parse, run, stringify, and the transformers hung off the tree

The process is three stages with a junction in the middle. Text enters, a parser produces a syntax tree, a compiler turns that tree back into text, and transformers attach to the tree in between. Those trees are unist nodes, which is the format plugins on both sides of the junction agree on. The overview ties each method to a stage, so parse covers markdown becoming a tree, run covers parsed markdown becoming formatted HTML, stringify covers compiling HTML, and process covers the whole round trip.

ascii
| ........................ process ........................... |
| .......... parse ... | ... run ... | ... stringify ..........|

          +--------+                     +----------+
Input ->- | Parser | ->- Syntax Tree ->- | Compiler | ->- Output
          +--------+          |          +----------+
                              X
                              |
                       +--------------+
                       | Transformers |
                       +--------------+

run takes a tree as its first argument, so calling it without one from parse leaves nothing to transform, and the compiler stage emits nothing until a tree exists.

remark, rehype and retext each bring their own tree

Three ecosystems grow around this core: remark for markdown, rehype for HTML, and retext for natural language. The choice the README asks you to make is about how many kinds of content you have. One kind, markdown only, means you can use that ecosystem's own main package, remark, and leave unified out of it. Mixed content, markdown and HTML in one document, means using unified itself and picking the plugins you need one at a time.

Crossing between ecosystems takes a bridge plugin, and the example chain is remarkParse, then remarkRehype to move from a markdown tree to an HTML tree, then rehypeDocument, rehypeFormat and rehypeStringify. The tree on each side of that bridge is a different type, which is why the development dependencies carry both @types/mdast and @types/hast. A plugin written for one ecosystem will not accept the other ecosystem's tree.

Problems land on the vfile, and nothing prints them for you

Metadata about the document being processed is gathered into a vfile, the format that stores data, metadata and messages for unified and its plugins. The example hands that file to vfile-reporter, and on a clean run the reporter prints one line: no issues found.

In the example, the report only appears because the file is passed to vfile-reporter and printed.

ESM only, Node 16 or newer, and browser imports pinned to a major

The package is ESM only, so there is no CommonJS entry point to require. On Node 16 or newer it installs from npm, while Deno and browsers import it from esm.sh, and both of those examples pin the major version inside the URL instead of tracking a moving target.

sh
npm install unified
js
import {unified} from 'https://esm.sh/unified@11'
html
<script type="module">
  import {unified} from 'https://esm.sh/unified@11?bundle'
</script>

Once installed, you import the named export and call it to obtain a processor:

js
import {unified} from 'unified'

Two costs follow from ESM only. A build step that still expects require() will not resolve this package, and the browser path puts a third party CDN between your page and the code, with the ?bundle query asking that CDN to serve a single bundle.

One export string, three published files, and no subpath to import

The manifest is small and it decides what consumers can reach. exports is a single string pointing at ./index.js, so there is no subpath export to import from, and files limits what ships to lib/, index.d.ts and index.js. Types sit next to the code, with index.d.ts at the root and index.test-d.ts kept in the repository for type tests.

json
"dependencies": {
  "@types/unist": "^3.0.0",
  "bail": "^2.0.0",
  "devlop": "^1.0.0",
  "extend": "^3.0.0",
  "is-plain-obj": "^4.0.0",
  "trough": "^2.0.0",
  "vfile": "^6.0.0"
},
"exports": "./index.js",
"files": [
  "lib/",
  "index.d.ts",
  "index.js"
]

A deep import into lib/ therefore works in a checkout and is refused after installation. Two runtime dependencies also pin majors you inherit, vfile at ^6.0.0 and trough at ^2.0.0, so a plugin written against another major of either will not drop in.

The last tag is 11.0.5 from 2024, and main moved on in 2026

The three most recent releases are 11.0.5 on 2024-06-19, 11.0.4 on 2023-10-26 and 11.0.3 on 2023-09-05. The repository is not archived and its last push is dated 2026-10-03, so the branch has been pushed to since those tags. The root listing shows the shape of that work: changelog.md beside index.js, index.d.ts, lib/, script/, test/ and tsconfig.json.

So the main branch and the last published version are two different things, and the esm.sh examples above declare which one they assume, since they name the @11 major. Track main and you read unreleased behaviour with changelog.md as your only record of what changed.

Editorial conclusion

Reach for unified when one document mixes content types, or when you are writing a plugin that has to sit between two trees. For a single format, the ecosystem package such as remark is the shorter path. Before you commit, check three things: which Node version and module system your build already assumes, since the package is ESM only, whether your plugins match the vfile major you get, and whether you are reading the last published version or the main branch, which has been pushed to since the 11.0.5 tag. To see a run's messages, print the file with a reporter as the README example does.

Frequently asked questions

how to use unified

Call unified() to get a processor, attach a parser, then the transformers you need, then a compiler, and pass your text to process. The example chains remarkParse, remarkRehype, rehypeDocument, rehypeFormat and rehypeStringify, then prints the resulting vfile through vfile-reporter. The package is ESM only and needs Node 16 or newer.

Is unified one library or a family of them?

It is two things at once. The collective covers more than 500 free and open source packages that work with content as structured data, and this repository is the core package inside it, used in over 1.3 million projects on GitHub to process content with plugins. The remark, rehype and retext ecosystems are built on it, and they can be connected together.

Do I need to add unified to a project that already uses MDX, Gatsby or Docusaurus?

No. Those projects already use unified, so you do not need to add it yourself, though you can include plugins into them. If you build your own pipeline, use remark when you deal with one type of content such as markdown, and use unified itself when you deal with different kinds of content and want to pick the plugins yourself.

What is a vfile?

A vfile is the format that stores data, metadata and messages about files for unified and its plugins, and it is where a processor gathers what it learned about the document. The example prints the file through vfile-reporter, where a clean run prints no issues found.

Which runtimes does unified support, and can it be loaded with require?

The package is ESM only, so require is not the documented path. On Node 16 or newer you install it with npm, in Deno you import it from esm.sh as https://esm.sh/unified@11, and in browsers the same service is used with a ?bundle query inside a module script.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. unifiedjs/unified on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/unifiedjs-unified.svg)](https://hysenlabs.com/projects/unifiedjs-unified)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/unifiedjs-unified.svg)](https://hysenlabs.com/projects/unifiedjs-unified)

Was this useful?