Matra

A headless rich text editor framework with a first-class extension API.

• 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

Eight packages, one version number, released together. Every other package 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