Remirror's readme names its successor and links a migration guide

The banner is the most useful thing in the readme

The first block after the title is a callout that says, in bold, that the project is in maintenance mode and is not recommended for new projects.

It then says three more things in the same block. The package stays stable and critical bugs will keep being fixed. Active development has moved on. And for new projects you should use a different toolkit instead, described as framework-agnostic and built on the same foundation, with a link to a migration guide for moving an existing editor across.

That is a well-executed handover, and it is rarer than it should be. The successor is named, it is linked, the reason it exists is given in one phrase, and there is documentation for the migration rather than just a suggestion that you go elsewhere.

There is one structural detail worth noticing. This project's whole reason for existing is its framework binding: the description calls it a toolkit for one framework, and the readme calls it a toolkit for building editors in that framework. The successor it points at is framework-agnostic. So the thing being recommended over is, in part, the coupling.

Everything below the banner is unchanged documentation for a live package, which is why the rest of this article is about what is still there.

The headline example stops in the middle of a prop

The introduction gives you a code sample and says that with it your editor supports basic editing.

The sample imports a framework, three formatting extensions from one entry point, and three things from the framework binding. It builds an extension list, calls a hook with content, a string handler set to HTML and the selection placed at the end, and returns the component with an initial state.

And then it stops, mid-expression, on an opening component tag whose callback prop has been named but not closed. No closing tag, no closing parenthesis, no closing brace for the component.

So the first thing a new user copies is incomplete, and it is incomplete at the point where the interesting part starts: the change handler is the thing that makes the editor useful, and that is exactly where the sample runs out.

The file does offer alternatives in the same breath. There is a five minute tutorial and a link to a starter on an online code playground, which is the route most people will take instead.

The clean script commits your work and then deletes it

The root manifest has more than sixty scripts and most of them are ordinary. This one is not:

"clean": "git add --all; git commit -m 'WIP: before clean'; git clean -fdx --exclude=node_modules --exclude=**/node_modules"

Read it left to right. It stages every change in the working tree. It commits them with the message WIP: before clean. And then it force-deletes every untracked and ignored file except the dependency directories.

That is a safety net, and it is also a surprise. Anyone who runs the clean script expecting to discard their experiment now has a commit containing it, on a maintenance-mode project where nobody asked for that commit. Anyone who wanted the clean to be a no-op on their changes gets one anyway.

The script next to it is stricter still: the full clean variant excludes only the IDE directory, so dependency directories are fair game there.

None of this is in the readme. It is visible only if you open the manifest, which is where anyone running a maintenance script should be looking first.

Eleven configuration files at the root, and a todo file

Count the tool configuration at the top of this repository and you get roughly eleven files before you reach a single line of source.

There is a linter configuration in the older key-on-a-file format rather than the flat configuration most tools have moved to. A separate file configures the linter's own type checking. A formatter configuration and an ignore file for it. A stylesheet linter ignore file. A markdown linter configuration. A bundle size budget. A compiler configuration for a fast transformer. A compiler configuration for the formatter. A Babel configuration. A commit message linter configuration. And an API documentation tool configuration.

Alongside them sit three separate test configurations, a workspace definition, a task runner definition, a lock file, a patches directory, and the two agent-independent pieces of the build.

And then there is a file called as a to-do list, committed at the root, in a project that has told you active development has moved to another repository.

None of this is criticism of a large monorepo. It is an observation about what it costs to keep a project installable and testable after the team working on it has gone to do something else, because every one of those files is a thing that has to keep working without anyone updating it.

Two tables of logos above the maintenance banner's consequences

The community section is longer than the installation section.

The first table is two sponsors. The second is five companies, under a heading that calls them a community spotlight rather than sponsors.

The next sentence invites you to become a sponsor, and the section after that is the documentation list. So the emotional peak of the readme is a logo wall, and it sits between the installation instructions and the feature list, in a project whose own banner says not to start anything new here.

I would read that as a project being run correctly by people who have not yet accepted the banner's implications for the parts of the readme that are about momentum rather than about reference material. A maintenance-mode readme is a thing people return to from search results and from old pull requests, not something they read once, and a reader landing on two tables of customer logos before the feature list is not being told anything useful about the code.

It also means the page is doing marketing work for a package whose own authors are directing new users to a different package.

Getting started lives in a different repository

There are three ways into this project and none of them is the file you are reading.

The first is the five minute tutorial on the documentation site. The second is the starter on an online code playground, and the link to it is a repository called with a starter suffix, which is not this repository. The third is the documentation site itself.

So the canonical quick start for a maintenance-mode framework is a separate starter repository plus a hosted tutorial, and this readme's own code sample is the truncated one.

The documentation index is thorough in the way you would expect from a project with a documentation team: an introduction, the out-of-the-box tutorial, a page on creating your own editor, a page on extensions, a live component gallery, and the starter.

The gallery is on a different hosting domain from the documentation, and the chat link used for the community server in the support section is the documentation domain too, which means the community runs through the project's own site rather than through the hosting service's own domain.

Three packages to install, and the third has no description

The installation section gives you three commands for three package managers and the same three package names in each.

The first is the umbrella package. The second is the framework binding, which is the one your code actually imports a component from. The third is a scoped package under the same scope as the binding, and nothing in the readme says what it is for.

Based on the naming, it is the underlying document-model packages re-exported under the project's own scope, which is the pattern that lets an application depend on one version of the editor layer rather than resolving several copies of the model layer itself. But that is an inference from the name, and the readme does not make it.

That is a small gap in an otherwise careful installation section. Three names, one unexplained, and a reader who installs all three without knowing why has no way to check whether they needed the third.

The feature list, for what it is worth, covers accessibility and ARIA, internationalisation through one specific library, mobile support, an out-of-the-box editor or one composed from extensions, the ability to write extensions that drop to the underlying library directly, collaborative editing through either of two libraries, more than thirty extensions, and types as a first-class concern.

Editorial conclusion

Remirror still makes sense if you are maintaining an editor that already uses it, because the banner promises stability and critical bug fixes rather than a freeze. Two things to check before you start anything new. Read the banner rather than the feature list, because the recommendation is explicit and the successor is named, linked and has a migration guide. And if you run the maintenance scripts, read them first, since the one that cleans the tree commits everything you have changed before deleting what is untracked.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. remirror/remirror on GitHub