Matra
A headless rich text editor framework with a first-class extension API. Zero runtime dependencies.
Documentation · Extensions · AI tools · Changelog · Design notes
- No engine leakage — the document model is plain JSON; no ProseMirror type appears in a public signature
- Plain objects, plain functions — no
this, no classes, no inheritance chains - Inferred types — adding an extension adds its commands, fully typed, with no module augmentation
- Async-safe — position mapping is built in, so a late AI response cannot corrupt the document
See DESIGN.md for the API rationale, CHANGELOG.md for what changed when, and CONTRIBUTING.md before a pull request.
Packages
Matra is মাত্রা — the horizontal line that runs across the top of Bengali
script and holds a word together. Packages live under the @matrajs scope,
matching matrajs.com.
Installing a binding installs the engine with it. For a React application
pnpm add @matrajs/react is the entire install: one package, and no
third-party dependency arrives behind it.
Quick start
import { createEditor, starterKit } from '@matrajs/core'
const editor = createEditor({
extensions: starterKit,
content: '<p>Hello</p>',
})
editor.mount(document.querySelector('#editor')!)
editor.commands.toggleBold()
Every command comes from the array you passed. Nothing else is on editor.commands,
and calling something that is not there is a compile error.
The packages in detail
Nine packages, one version number, released together. Every binding
depends on @matrajs/core and on nothing else, so installing a binding
installs the whole editor — there is no second package to remember, no
@matrajs/pm to keep in step, and no peer range to resolve by hand.
@matrajs/core — MIT
The engine, and the only package that is not optional. The document model, transforms, position mapping, editor state and the editable view are written here, with zero runtime dependencies.
pnpm add @matrajs/core
Entry points
EditorOptions
The editor
Core commands, present whatever you pass: select, insert, replace,
remove, moveBlock, focus. insert and replace accept blocks at a
caret inside a paragraph and split the paragraph around them, which is what
a rule or a table asked for at the caret means.
What an extension may declare, beyond commands, keys and input rules:
@matrajs/react — MIT
pnpm add @matrajs/react
import { starterKit } from '@matrajs/core'
import { EditorContent, useEditor, useEditorState } from '@matrajs/react'
export function Notes() {
const editor = useEditor({ extensions: starterKit, content: '<p>Hello</p>' })
const bold = useEditorState(editor, (e) => e.isActive('bold'))
return (
<>
<button onClick={() => editor.commands.toggleBold()} aria-pressed={bold}>
Bold
</button>
<EditorContent editor={editor} className="prose" />
</>
)
}
Options are read once. Changing them later does not recreate the editor,
because tearing down a live document on a prop change loses the user's work —
use the commands instead. The mount is guarded on unsafe.view, so StrictMode's
double invoke cannot leave two views fighting over one element.
@matrajs/vue — MIT
The same four names as React, returning refs.
pnpm add @matrajs/vue
<script setup lang="ts">
import { starterKit } from '@matrajs/core'
import { EditorContent, useEditor, useEditorState } from '@matrajs/vue'
const editor = useEditor({ extensions: starterKit })
const bold = useEditorState(editor, (e) => e.isActive('bold'))
</script>
<template>
<button :aria-pressed="bold" @click="editor.commands.toggleBold()">Bold</button>
<EditorContent :editor="editor" />
</template>
The mount is guarded, so a <KeepAlive> remount does not attach a second view.
@matrajs/svelte — MIT
Svelte already has the right shape — an action runs when the element exists and is told when it goes away — so the binding is thin on purpose. Written with stores rather than runes, so it behaves identically on Svelte 4 and 5.
pnpm add @matrajs/svelte
<script>
import { starterKit } from '@matrajs/core'
import { matra } from '@matrajs/svelte'
const { action, editor, state } = matra({ extensions: starterKit })
</script>
<button aria-pressed={$state.isActive('bold')} onclick={() => editor.commands.toggleBold()}>
Bold
</button>
<div use:action></div>
The editor exists before the element does, so commands, content and
getJSON() all work before anything is on screen — which is what a server
render and a test both need.
@matrajs/solid — MIT
Solid's reactivity is not a render loop, so there is no useSyncExternalStore
shape to reach for: a signal that bumps on every change is enough.
pnpm add @matrajs/solid
import { starterKit } from '@matrajs/core'
import { createMatra } from '@matrajs/solid'
const { editor, mount, state } = createMatra({ extensions: starterKit })
return (
<>
<button aria-pressed={state().isActive('bold')} onClick={() => editor.commands.toggleBold()}>
Bold
</button>
<div ref={mount} />
</>
)
state() returns the editor itself rather than a copy: a toolbar asks
isActive at render time, and cloning a document to answer that would be the
expensive way to do nothing.
@matrajs/ai — Commercial
Streaming edits that survive concurrent typing. The range being rewritten is re-resolved against the current document on every chunk, so a user who keeps typing while the model streams does not end up with a corrupted paragraph.
pnpm add @matrajs/ai
Commands: askAi(instruction), cancelAi(), acceptAi(), rejectAi().
import { createEditor, starterKit } from '@matrajs/core'
import { ai } from '@matrajs/ai'
const editor = createEditor({
extensions: [
...starterKit,
ai({
async *stream({ text, instruction, signal }) {
const response = await fetch('/api/rewrite', {
method: 'POST',
body: JSON.stringify({ text, instruction }),
signal,
})
for await (const chunk of response.body!.pipeThrough(new TextDecoderStream())) yield chunk
},
onStatus: (session) => setSpinner(session.status === 'streaming'),
}),
] as const,
})
editor.commands.askAi('make this shorter')
stream runs in your application, so the model key stays on your server. The
extension never talks to us.
@matrajs/collab — Commercial
Step exchange, rebasing and presence, with no CRDT dependency. Another client's work rebases over unsent local work without either being lost.
pnpm add @matrajs/collab
Command: receiveCollabSteps(steps) — steps this client sent are skipped, and a
step that no longer applies is dropped rather than thrown, because one bad
message from a peer must not take the editor down.
import { createEditor, starterKit } from '@matrajs/core'
import { collab, remoteCursors, sendableSteps } from '@matrajs/collab'
const editor = createEditor({
extensions: [...starterKit, collab({ clientId: 'me' }), remoteCursors()] as const,
})
editor.on('change', () => {
const sendable = sendableSteps(editor)
if (sendable) socket.send(JSON.stringify(sendable))
})
socket.onmessage = (event) => editor.commands.receiveCollabSteps(JSON.parse(event.data))
Authority is a plain class with no server attached — run it in a WebSocket
handler, a Durable Object, or a test.
@matrajs/versions — Commercial
Snapshots, a real diff between them, and restore as one undo step.
pnpm add @matrajs/versions
Commands: snapshotVersion(label?), restoreVersion(id),
previewVersion(id | null), forgetVersion(id).
import { createEditor, starterKit } from '@matrajs/core'
import { localVersionStore, versionList, versions } from '@matrajs/versions'
const editor = createEditor({
extensions: [
...starterKit,
versions({
idleMs: 30_000,
keep: 50,
store: localVersionStore('doc-42'),
onChange: (state) => render(state.versions, state.diff),
}),
] as const,
})
editor.commands.snapshotVersion('before the rewrite')
editor.commands.previewVersion(versionList(editor)[0].id)
idleMs: null turns automatic snapshots off and leaves them to
snapshotVersion. A version per keystroke is not history, it is a keylogger
with a nicer name. now is injected rather than reached for, so a test does not
have to sleep to make two versions differ.
Documentation for AI tools
@matrajs/mcp serves this documentation over the
Model Context Protocol: every Markdown
page in this repository and every page of
matrajs.com/docs, converted at build time and
shipped inside the package. Nothing is fetched at runtime, and the package
has zero dependencies, like the rest.
claude mcp add matra -- npx -y @matrajs/mcp # Claude Code
npx -y @matrajs/mcp --http # any client that speaks HTTP, at localhost:3333/mcp
Ask the connected tool anything about Matra and it answers from the documentation rather than from memory. Configuration for Claude Desktop, Cursor and Codex is in packages/mcp.
Security
Document JSON, pasted HTML and collaborative steps are all treated as hostile, and the rendering path is the gate they all pass through: executable attributes are never set, URL attributes are scheme-checked, undeclared attributes are dropped, and commands report failure rather than throwing. See SECURITY.md.
Development
pnpm install
pnpm dev # playground at localhost:5173
pnpm test # vitest
pnpm typecheck # tsc, including the type-level tests
pnpm check # biome, and prettier for .astro
pnpm build # tsup, all packages
pnpm size # the bundle ladder the site quotes
pnpm bench:check # the performance ratchet, against the recorded baseline
pnpm links # no dead internal links on the site
pnpm packaging # every built package imports and requires (run after build)
pnpm wiring # every script on the site finds the markup it asks for
pnpm exercise # drive every extension through the built package in a DOM: every command, rule and paste
pnpm install:matrix # pack every package, npm-install it into fresh Vite apps for each framework, build and run them
pnpm facts # the counts the site prints — tests, adversarial tests, extensions
Status
1.0 — the Matra engine, end to end. Document model, transforms, position
mapping, editor state and the editable view are written from scratch, with
zero runtime dependencies. 779 tests, 68 of them adversarial, and every
package is installed with plain npm into a fresh React, Vue, Svelte, Solid
and vanilla Vite app and built there before a release (pnpm install:matrix).
An app on the starter kit bundles 31 kB gzipped, because nothing arrives
that the editor does not use — seventy-nine extensions ship in the package
and none of them is in the bundle until it is in the array. The whole ladder,
from an empty extension array upwards, is measured by pnpm size and checked
in CI. It was 25 kB at 0.16; what the five kilobytes bought is listed in
CHANGELOG.md.
Drag and drop landed in 0.9.0: blocks drag with a handle, a line shows where they will land, and the move is one undo step.
The view passes its tests but has not yet met real IME users on iOS Safari or Android Chrome. See ENGINE.md for where the risk actually sits, and harness/ime for the page that checks it on a real device.
Extensions
Everything in the box, and everything free unless marked.
Tiptap 3 moved most of its old Pro extensions to MIT — a table of contents, unique ids, the drag handle, the file handler, emoji, details, invisible characters and mathematics are all free there now, and it is worth saying so rather than repeating a comparison that was true of Tiptap 2. What is still behind a Tiptap subscription is comments, snapshots and version history, the AI toolkit, track changes, DOCX import and export, and pagination.
Of those, comments are free here. Version history, collaboration and AI are the three packages this project charges for, and the shape is deliberate: the things that take a week are free and drive adoption, and the ones that took months are what you pay for.
Adding one, step by step
Every extension follows the same four steps. Search and replace, as the example:
- Import it from
@matrajs/core— the binding you installed already depends on it, so there is nothing to add topackage.json. - Put it in the array. Extensions that take options are functions; the rest are plain objects.
- Call its commands. They are on
editor.commands, typed from the array, so a typo is a compile error. - Paste its CSS if it has any. Extensions that draw something export a
…CSSstring; the editor ships no appearance of its own.
import { createEditor, search, searchCSS, starterKit } from '@matrajs/core'
const editor = createEditor({ extensions: [...starterKit, search()] as const })
editor.commands.setSearch({ query: 'colour', wholeWord: true })
editor.commands.nextMatch() // selects it, so the view scrolls there
editor.commands.replaceMatch('color')
editor.commands.replaceAllMatches('color') // one undo step
editor.extensionState('search') // { matches, current, query, … } for a panel
document.head.appendChild(Object.assign(document.createElement('style'), { textContent: searchCSS }))
The same shape for the rest: textStyle then editor.commands.setColor('#c00');
callout then toggleCallout('warning'); ...detailsKit then
insertDetails(); youtube then insertYoutube({ src: url });
fileHandler({ accept: ['image/'], onDrop }) then upload in onDrop and
insert at marker.map(pos); ...tableKit then insertTable(3, 3) and
addRowAfter(). Each is one row in the directory on
matrajs.com/extensions, with the line you
would write.
toMarkdown and fromMarkdown are pure string work rather than a trip through
HTML, so they run in Node, in a worker, and at the edge. Turning a document into
Markdown on a server does not need a DOM polyfill.
Against the alternatives
Measured, not asserted — see BENCHMARKS.md for the method and what the numbers are not.
Package counts are what npm resolves for a React install of each, measured by
scripts/rivals.mjs on 2026-09-07 against Tiptap
3.31.3, Lexical 0.50.0 and Slate 0.126.2, with React and @types/* left out
of the count.
Rows that used to be here and are no longer true: Tiptap 3 publishes its table
of contents, unique ids, drag handle, file handler, emoji, details, invisible
characters and mathematics extensions as MIT, and @tiptap/markdown parses and
serialises Markdown in bare Node. Tiptap also ships an official Vue binding,
which an earlier version of this table called community.
Where the alternatives win, and it is worth saying so: ProseMirror's ecosystem is a decade deep and Tiptap inherits all of it, Lexical has been hardened by Meta's traffic, and both have met far more real IME users than this has. If you need a mature extension for something exotic today, they have it and this does not.
Releasing
One registry, and an order that matters. See RELEASING.md. Every release is recorded in CHANGELOG.md.
Licence
The core is MIT and stays that way. @matrajs/core and every framework
binding — @matrajs/react, @matrajs/vue, @matrajs/svelte and
@matrajs/solid — the engine, the document model, the extension API, the
starter kit, tables, comments, every mark and node that ships in the box. No
open-core asterisk on any of it, no feature removed later to sell back.
AI, collaboration and version history are paid. @matrajs/ai,
@matrajs/collab and @matrajs/versions are source-available under the
Matra Commercial License:
free to evaluate, develop against, test, teach with, and use in personal
projects and small internal tools; paid per developer in production. They are
the things here that took months rather than days — streaming edits that
survive concurrent typing, rebasing another client's work over unsent local
work without losing either, and a real diff between two snapshots of a
document.
Nothing phones home and there is no runtime licence check. Your editor never talks to us, in development or in production, and a lapsed subscription cannot switch anything off in an app you already shipped.
There is no download gate either. The source is in this repository and the packages install from public npm — the licence is the boundary, as with the Business Source Licence. What a subscription buys is the right to run them in production, plus updates and support.
Versions up to 0.5.0 shipped under MIT, including ai and collab, and that
grant cannot be withdrawn. Anyone already on 0.5.0 may stay there under MIT
forever. The commercial licence starts at 0.6.0.