Getting started

Introduction

Matra is a headless rich text editor framework. It gives you a document model, an extension API and a command system · and stays out of the way of your interface.

Why another editor

Every editor framework leaks its engine into your code. You import the engine's types, write against its internals, and upgrading it becomes your problem. Matra wraps the engine completely: your document is plain JSON and no engine type appears in a public signature.

It also has no runtime dependencies. The document model, transforms, position mapping, editor state and the editable view are written from scratch, which is why an app bundles 31.1 kB gzipped instead of 117.

The three ideas

Everything else follows from these, and there is not a fourth.

• The document is data. Plain JSON — log it, store it, diff it, read it on a server that has never loaded an editor. Document model →
• The extension array is the feature list. What you pass in decides what the editor can do, what it accepts on paste, and what editor.commands is typed as. An editor with no heading extension has no heading command, and TypeScript knows. Writing an extension →
• Positions are mapped, not remembered. A position held across an await is wrong by the time you come back, so the async path never hands you a raw number. Position mapping →

Install

npm i @matrajs/core

import { createEditor, starterKit } from '@matrajs/core'

const editor = createEditor({ extensions: starterKit, content: '<p>Hello.</p>' })
editor.mount(document.querySelector('#editor'))

That is a working editor. It will look like unstyled text until you write some CSS, which is what headless means — Styling covers it in a page.

What is in the box

Table of contents, unique block ids, drag handle and comments are in the core and stay there. They are paid features elsewhere.

Where to go next

Depending on what you came here to do:

• Get something working. Your first editor, then Styling.
• Fit it into your app. Frameworks — React, Vue, Svelte, Solid, Angular and plain JavaScript.
• Understand it. Document model and Commands.
• Decide whether to trust it. Benchmarks, including the row where the harness was wrong and what it was measuring instead.

Edit this page on GitHub