Maintainers' Guide

This is the grimoire of arcane knowledge covering the overall organization of the Lexical monorepo, including its conventions, quirks, and configurations.

Monorepo Organization

Workspaces

The top-level package.json uses pnpm workspaces to configure the monorepo. This mostly means that all packages share a top-level pnpm-lock.yaml and pnpm -C {package} run {command} is often used to run a command from a nested package's package.json.

Private

Some packages in the monorepo do not get published to npm, for example:

• packages/lexical-devtools - browser extension for working with Lexical sites
• packages/lexical-playground - the playground.lexical.dev demo site
• packages/lexical-website - the lexical.dev docusaurus website that you may even be reading right now
• packages/shared - internal code that is used by more than one repository but should not be a public API

It is required that these packages, and any other package that should not be published to npm, have a "private": true property in their package.json. If you have an in-progress package that will eventually be public, but is not ready for consumption, it should probably still be set to "private": true otherwise the tooling will find it and publish it.

Package naming conventions

Overall

Multiple module export (@lexical/react)

Instead of having a single module, some packages may have many modules (currently only @lexical/react) that are each exported separately. In that scenario, there should be no index.ts entrypoint file and every module at the top-level should be an entrypoint. All entrypoints should be a TypeScript file, not a subdirectory containing an index.ts file.

The update-packages script will ensure that the exports match the files on disk.

Creating a new package

The first step in creating a new package is to create the workspace directory and package.json file. The example we will use is the steps that were used to create the lexical-eslint-plugin, which will be published to npm as @lexical/eslint-plugin.

Create the workspace

mkdir -p packages/lexical-eslint-plugin

Create the initial package.json file (you can base it on an existing package or use the template below):

packages/lexical-eslint-plugin/package.json

{
  "name": "@lexical/eslint-plugin",
  "description": "",
  "keywords": [
    "lexical",
    "editor"
  ],
  "version": "0.14.3",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/facebook/lexical.git",
    "directory": "packages/lexical-eslint-plugin"
  },
  "main": "LexicalEslintPlugin.js",
  "types": "index.d.ts",
  "bugs": {
    "url": "https://github.com/facebook/lexical/issues"
  },
  "homepage": "https://github.com/facebook/lexical#readme"
}

Some next steps for this package.json before moving on:

• Update the description
• Add appropriate keywords

Create the initial source file

mkdir -p packages/lexical-eslint-plugin/src
code packages/lexical-eslint-plugin/src/index.ts

Here are some minimal examples of those files that you might start out with. I've elided the license header, the eslint header/header fixer will help you with that!

packages/lexical-eslint-plugin/src/index.ts

import {name, version} from '../package.json';

const plugin = {
  meta: {name, version},
  rules: {},
};

export default plugin;

Run update-packages to generate boilerplate docs & config

pnpm run update-packages

This will set up the tsconfig, flow, etc. configuration to recognize your new module. It will also create an initial README.md using only the description from the package.json.

Create an initial unit test

mkdir -p packages/lexical-eslint-plugin/src/__tests__/unit
code packages/lexical-eslint-plugin/src/__tests__/unit/LexicalEslintPlugin.test.ts

packages/lexical-eslint-plugin/src/__tests__/unit/LexicalEslintPlugin.test.ts

import plugin from '@lexical/eslint-plugin';

describe('LexicalEslintPlugin', () => {
  it('exports a plugin with meta and rules', () => {
    expect(Object.keys(plugin).sort()).toMatchObject(['meta', 'rules']);
  });
});

Scripts for development

pnpm run update-packages

This script runs: update-version, update-tsconfig, update-flowconfig, create-docs, and create-www-stubs. This is safe to do at any time and will ensure that package.json files are all at the correct versions, paths are set up correctly for module resolution of all public exports, and that various defaults are filled in.

These scripts can be run individually, but unless you're working on one of these scripts you might as well run them all.

pnpm run prepare-release

This runs all of the pre-release steps and will let you inspect the artifacts that would be uploaded to npm. Each public package will have a npm directory, e.g. packages/lexical/npm that contains those artifacts.

This will also update scripts/error-codes/codes.json, the mapping of production error codes to error messages. It's imperative to commit the result of this before tagging a release.

pnpm run ci-check

Check flow, TypeScript, prettier and eslint for issues. A good command to run after committing (which will auto-fix most prettier issues) and before pushing a PR.

pnpm run flow

Check the Flow types

pnpm run tsc

Check the TypeScript types

pnpm run tsc-extension

Check the TypeScript types of the lexical-devtools extension

pnpm run test-unit

Run the unit tests

pnpm run lint

Run eslint

Scripts for release managers

pnpm run extract-codes

This will run a build that also extracts the generated error codes.json file.

This should be done, at minimum, before each release, but not in any PR as it would cause conflicts between serial numbers.

It's safe and probably advisable to do this more often, possibly any time a branch is merged to main.

The codes.json file is also updated any time a release build is generated as a failsafe to ensure that these codes are up to date in a release. This command runs a development build to extract the codes which is much faster as it is not doing any optimization/minification steps.

pnpm run increment-version

Increment the monorepo version. The -i argument must be one of minor | patch | prerelease.

The postversion script will:

• Create a local ${npm_package_version}__release branch
• pnpm run update-version to update example and sub-package monorepo dependencies
• pnpm install to update the pnpm-lock.yaml
• pnpm run update-packages to update other generated config
• pnpm run extract-codes to extract the error codes
• pnpm run update-changelog to update the changelog (if it's not a prerelease)
• Create a version commit and tag from the branch

This is typically executed through the version.yml GitHub Workflow which will also push the tag and branch.

pnpm run changelog

Update the changelog from git history.

pnpm run release

Prerequisites: all of the previous release manager scripts, plus creating a tag in git, and likely other steps.

Runs prepare-release to do a full build and then uploads to npm.

Release Procedure

This is the current release procedure for public releases, at least as of May 2024 (~0.15.0).

The main branch should be "frozen" during this procedure (no other PRs should be merged during this time). This avoids a mismatch between the contents of the GitHub release (created from main in step 1) and the NPM release (created from main in step 4).

1. Create a new version with the Github Actions "Create New Release Branch" workflow (version.yml)
2. Raise a PR against version branch created by that action
3. After PR is approved with passing tests, merge PR
4. After PR is merged to main, publish to NPM with the Github Actions "Publish to NPM" workflow (pre-release.yml)
5. Create a GitHub release from the tag created in step 1, manually editing the release notes
6. Announce the release in #announcements on Discord
7. Raise a PR against the post-release-* version branch (created by call-post-release.yml via pre-release.yml) to update the examples

Release Protocol

1. All PRs with breaking changes must have [Breaking Change] in the PR's title with documentation of what followup actions consumers of the lexical library need to be aware of.
2. Monthly releases happen on the last week of the month, with a minor increment (eg. v0.20+1.0).
3. Anything in between will be a patch increment (eg. 0.20.0+1), unless there is a breaking change.

Website Team Page

The team page displays core team members, emeriti, and distinguished contributors. The team.json data is generated from GitHub contributor information and some predetermined decisions in the script to acknowledge emeriti and historically important distinguished contributors.

To update the team page data:

pnpm run update-team-data

This fetches the latest contributor data from GitHub and categorizes team members based on recent activity (last 12 months). See packages/lexical-website/src/data/README.md for more details on configuration and team categorization logic.