Payload Lexical Plugin

A plugin for Payload CMS whichs adds a lexical-based richtext editor. Lexical is a lot nicer to use than Slate & more modern - it's also maintained by Meta.

This plugin only supports payload 1.x - not 2.x. While this plugin can still be used if you need extra features (tables, color picker, collapsibles etc. etc.), it will not receive further development or support. This plugin is also a great reference for building new Features in the new Lexical editor in Payload core 2.0. It has the same features as the lexical playground, but its API is closer to the new Lexical Payload 2.0 API (which was inspired by this plugin), which makes porting over Features easier.

Note: This plugin and the new lexical in Payload 2.0 Lexical is powering the next richtext editor in Payload 2.0 (I'm calling it Lexical core here). Future development is focused on the new lexical editor rather than the older Slate-based editor.

There is a converter you can use to migrate everything from this plugin to the new lexical core. You can find more info about it here: https://payloadcms.com/docs/rich-text/lexical#migrating-from-payload-plugin-lexical

Please note that this migrator only migrates data, not features. While lexical core is more stable and carefully crafted than this plugin, this plugin still has more features which lexical core does not have - for example tables or collapsibles.

If you use these features, the data can be migrated over, but it will not be displayed inside the core lexical editor until you migrate the Feature over from this plugin to lexical core as well.

Lexical 2.0 core will eventually get all the missing features, and thus the missing converters. The main focus right now is stability

This plugin already comes packed with a ton of features which the original 1.0 Slate editor doesn't have (from tables & markdown to stuff like speech-to-tech) - all customizable. It's also a lot easier to extend this editor and add new stuff to it!

Installation / How to use

Install the plugin using yarn add payload-plugin-lexical. You can find examples of how to use it below.

Minimum required payload version: 1.6.32

Screenshots

How I'm using it in production - customized & with some features turned on or off:

Arc.2023-03-20.at.01.45.57.mp4

Example - Basic

payload.config.ts:

import { buildConfig } from 'payload/config';
import { LexicalPlugin } from "payload-plugin-lexical";

export default buildConfig({
  ...
  plugins: [
    LexicalPlugin({
      // Only set this if you want to use the the AISuggest Feature
      ai: {
        openai_key: process.env.OPENAI_KEY,
      },
    }),
  ],
  typescript: {
    outputFile: path.resolve(__dirname, 'payload-types.ts'),
  },
});

Collection config:

import { CollectionConfig } from 'payload/types';
import { lexicalRichTextField } from 'payload-plugin-lexical';

const Lexical: CollectionConfig = {
  slug: 'lexicalRichText',
  admin: {
    useAsTitle: 'title',
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    lexicalRichTextField({
      name: 'lexicalRichTextEditor',
      label: 'Lexical Rich Text Editor',
    }),
  ],
};

export default Lexical;

Example - more customization and own, custom node:

import { CollectionConfig } from 'payload/types';
import {
  lexicalRichTextField,
  EquationsFeature,
  EmojisFeature,
  EmojiPickerFeature,
  HorizontalRuleFeature,
  FigmaFeature,
  YouTubeFeature,
  TwitterFeature,
  SpeechToTextFeature,
  ImportFeature,
  ExportFeature,
  ClearEditorFeature,
  ReadOnlyModeFeature,
  ConvertFromMarkdownFeature,
  MentionsFeature,
  TreeViewFeature,
  KeywordsFeature,
  AutoCompleteFeature,
  CollapsibleFeature,
  TypingPerfFeature,
  PasteLogFeature,
  TestRecorderFeature,
  LinkFeature,
  TableOfContentsFeature,
  AISuggestFeature,
} from 'payload-plugin-lexical';

const Lexical: CollectionConfig = {
  slug: 'lexicalRichText',
  admin: {
    useAsTitle: 'title',
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    lexicalRichTextField({
      name: 'lexicalRichTextEditor',
      label: 'cool richtext editor',
      localized: true,
      editorConfigModifier: (defaultEditorConfig) => {
        defaultEditorConfig.debug = false;
        defaultEditorConfig.toggles.textColor.enabled = false;
        defaultEditorConfig.toggles.textBackground.enabled = false;
        defaultEditorConfig.toggles.fontSize.enabled = false;
        defaultEditorConfig.toggles.font.enabled = false;
        defaultEditorConfig.toggles.align.enabled = false;
        defaultEditorConfig.toggles.tables.enabled = true;
        defaultEditorConfig.toggles.tables.display = false;

        // Optional: these are the default features. Feel free to customize them or remove the ones you do not like!
        defaultEditorConfig.features = [
          EquationsFeature({}), // LaTex (well KaTeX) equations
          EmojisFeature({}), // Adds new Emoji nodes with new, different-looking emojis
          EmojiPickerFeature({}), // Use in combination with EmojisPlugin. When you start typing ":" it will show you different emojis you can use. They also look different!
          HorizontalRuleFeature({}), // Horizontal rule in the editor.
          FigmaFeature({}), // Figma Embed
          YouTubeFeature({}), // YouTube Embed
          TwitterFeature({}), // Twitter Embed
          SpeechToTextFeature({}), // Adds a Speech-to-text button in the Actions menu (bottom right of the editor). When you click on it and speak, it converts the speech into text
          ImportFeature({}), // Acion button: import
          ExportFeature({}), // Acion button: export
          ClearEditorFeature({}), // Adds a button in the action menu which clears the editor
          ReadOnlyModeFeature({}), // Acion button: toggle read-only mode on or off
          ConvertFromMarkdownFeature({}), // Acion button: convert from markdown
          MentionsFeature({}), // Ability to mention someone when you type "@"
          TreeViewFeature({ enabled: defaultEditorConfig.debug }), // If enabled, will show the node representation of the editor under the editor. Good for debugging
          KeywordsFeature({}), // Highlights certain words
          AutoCompleteFeature({}), // Autocompletes certain words while typing
          CollapsibleFeature({}), // Adds a "collapsible" node
          TypingPerfFeature({ enabled: defaultEditorConfig.debug }), // Some debug tool for performance testing
          PasteLogFeature({ enabled: defaultEditorConfig.debug }), // Another debug tool
          TestRecorderFeature({ enabled: defaultEditorConfig.debug }), // Another debug tool used for lexical core development, with which you can automatically generate tests
          LinkFeature({}), // Obvious: hyperlinks! This includes the AutoLink plugin.
          TableOfContentsFeature({ enabled: false }), // Shows a table of contents on the right hand-side of the screen
          AISuggestFeature({}), // Make sure you set your openai key in the plugin config to be able to use it
        ];

        // A feature can consist of nodes, plugins, modals, toolbar elements and more! YourOwnCustomFeature must be of type "Feature"
        defaultEditorConfig.features.push(YourOwnCustomFeature({}));

        return defaultEditorConfig;
      },
    }),
  ],
};

export default Lexical;

This example can also be found in the demo!

Serializing

Feel free to use my serializer in the serialize-example folder of this repo. Lexical is using bitwise operations for the node formats.

This currently serialized the most important stuff, but not everything. Feel free to contribute to it if you add more!

Idea list:

• Update slash commands to reflect the toolbar
• Add wordcount, charactercount & preview to the json output
• Commenting functionality
• Upload plugin/node captions
• Ability to add custom fields to uploads like captions
• (relationship node?)
• Fix internal collection search for internal link editor
• Edit Upload Button
• Improve design & UX of links. For example, clicking on the link button should open the link drawer immediately
• (maybe?) lazy loading lexical editor to reduce load times. or maybe just the images?
• New format/node: "highlight"/"mark" (WILL BE ADDED NATIVELY BY LEXICAL IN 0.7.8)
• Increase customizability & DX. Plugins should all be set in the config. Slash commands & Toolbar items should come from the same place.
• Add ExcaliDraw
• Take a closer look at AutoLink. Is it necessary and what does it do?
• Make extranodes, extraplugins ... config options hold the ENTIRE nodes, and rename to just "nodes" and "plugins". Makes it easier to remove them and start from scratch, or to insert one at a special position, instead of just pushing it to the end. Especially useful for the Toolbar plugin.
• extraFloatingToolbarElements
• Implement Table Cell Background Color PR

Updating lexical

Since this is based on their playground, you gotta upstream their changes. Then, the following is additionally copied over outside of the playground package - needs to be considered in lexical updates as well:

• https://github.com/facebook/lexical/blob/main/packages/lexical-react/src/LexicalOnChangePlugin.ts
• https://github.com/facebook/lexical/blob/main/packages/lexical-react/src/LexicalLinkPlugin.ts
• https://github.com/facebook/lexical/blob/main/packages/lexical-react/src/LexicalAutoLinkPlugin.ts
• https://github.com/facebook/lexical/tree/main/packages/shared
• https://github.com/facebook/lexical/blob/main/packages/lexical-link/src/index.ts
• And of course their playground package