@guardian/prosemirror-elements

A ProseMirror plugin that makes modelling arbitrary nested content simple. It allows structured, non-text content to be modelled as first-class citizens of the ProseMirror schema. This content is called 'elements'.

Contents

• Introduction
• Getting Started
• How It Works
• Useful Links
• Terminology

1. Introduction

Modelling non-text content in ProseMirror can be tricky. prosemirror-elements provides an abstraction that makes it easy to write custom elements that:

• Contain user-defined fields that model many different kinds of content, including rich text, plain text, dropdowns, checkboxes, repeating groups, and arbitrary custom data.
• Are first-class citizens of the ProseMirror schema — nested rich text fields participate fully in collaborative editing, selections, decorations, and marks.
• Are renderer-agnostic — React bindings are provided as a default, but the core is framework-independent.

The library is used by Guardian editorial tools to power structured content such as images, pullquotes, callouts, embeds, recipes, and more.

Note for Guardian developers: Many element definitions used in Composer have been moved into the flexible-content repo (see PR #4410). If you are making a change intended for Composer, make the changes there instead.

2. Getting Started

This section provides instructions for setting up and contributing to the plugin code. For integrating it into consuming code, see the Quick-Start Guide.

Setup

1. Ensure you have dev-nginx and yarn installed on your local machine.
2. Run the setup script: ./script/setup.sh

Running locally

1. Ensure nginx is running.
2. yarn start builds the project locally, spins up a webserver on https://prosemirror-elements.local.dev-gutools.co.uk, and watches for file changes.

Testing

• Run the unit tests via Jest with yarn test:unit.
• Run the integration tests via Cypress with yarn test:integration.
  • You'll need to be running the application via yarn start simultaneously for the tests to work – make sure the server is responding on http://localhost:7890 before running the tests.
  • For reasons we're not yet able to determine, Cypress won't run your tests immediately when you select them in the GUI. Hit the 'refresh' button and they should run normally.

Releasing

This repository uses changesets for version management.

1. Run yarn changeset add and follow the prompts to create a changeset file.
2. Commit the changeset file with your PR.
3. When merged, Changesets will open a release PR. Approve and merge it to publish to npm.

Testing locally in consuming applications

We recommend yalc for testing local changes:

1. Install yalc globally: npm i yalc -g or yarn global add yalc.
2. Build and push to yalc: yarn yalc
3. In the consuming project: yalc add @guardian/prosemirror-elements

Re-run yarn yalc in this repo after each local change.

Why not yarn link? ProseMirror and its dependencies sometimes use instanceof checks. yarn link can cause duplicate dependency copies, breaking these checks. See the Troubleshooting section for a known workaround.

Adding a new element

See the Quick-Start Guide for a step-by-step walkthrough of creating an element with fields and a React UI.

3. How It Works

Overview

For an explanation of the plugin's core functionality, see How prosemirror-elements works.

Core technologies

• ProseMirror — the underlying rich-text editor framework.
• TypeScript — the project is written entirely in TypeScript.

Architecture

The project is structured into three main areas:

• src/plugin/ — The core ProseMirror plugin: field definitions, node spec generation, field views, validation helpers, and the plugin itself.
• src/renderers/react/ — React bindings — createReactElementSpec, field components, stores, and wrapper controls.
• src/elements/ — Built-in element definitions (e.g. image, pullquote, callout, embed, tweet, table, recipe, code, etc.). These are included for reference and no longer used in production.

4. Useful Links

• Quick-Start Guide — creating your first element
• How prosemirror-elements works — detailed technical walkthrough
• Vision — project goals and design philosophy
• ADRs – records of significant decisions made during project development
• ProseMirror documentation

5. Terminology

• Element — A structured, non-text content block within a ProseMirror document (e.g. an image, pullquote, or embed). Composed of one or more Fields.
• Field — A single data unit within an Element. Field types include text, rich text, custom, dropdown, checkbox, repeater, and nested element.
• Field View — The ProseMirror view-layer representation of a Field — manages how a field is rendered and how user input is captured.
• NodeSpec — A ProseMirror schema definition for a node type. prosemirror-elements generates NodeSpecs from element and field definitions. ProseMirror documentation
• Content Expression — A ProseMirror string that defines what child nodes a node may contain (e.g. "block+", "text*"). ProseMirror documentation.
• Repeater Field — A field type that allows zero or more repeated groups of child fields (e.g. a list of books, each with title and ISBN).
• Custom Field — A field that stores arbitrary data as ProseMirror node attributes rather than document content. Updates are always last-write-wins.
• Element Spec — The combination of a field description object and a renderer component that together define an element.
• Data Transformer — A function that converts between an element's external data representation (plain JS object) and its internal ProseMirror node representation.

Troubleshooting

Problems with yarn link

ProseMirror and its dependencies sometimes use object identity checks (e.g. instanceof). When using yarn link, it's possible for the consuming code to bundle different versions of dependencies simultaneously. This can be difficult to work around. It will not happen during a normal install.

We recommend using yalc to avoid this issue, but it's also possible to work around it.

One known instance of this occurs when appending the NodeSpec generated by the library to the parent editor schema. This would normally be accomplished by appending it to a parent schema, like so:

const mySchema = new Schema({
  nodes: OrderedMap.from(schema.spec.nodes).append(nodeSpec),
  marks,
});

This may fail if your bundler has included the ordered-map dependency twice in your project. Because ordered-map uses instanceof to determine if an incoming object is an OrderedMap, the incoming object will fail this check, despite it being the correct shape.

As a workaround, try reconstructing the map as an object:

const objectNodeSpec: Record<string, NodeSpec> = {};
nodeSpec.forEach((key, value) => (objectNodeSpec[key] = value as NodeSpec));

const mySchema = new Schema({
  nodes: OrderedMap.from(schema.spec.nodes).append(objectNodeSpec),
  marks,
});