LexKit Docs

Extensions API

Core API reference for LexKit extensions

Complete API reference for creating, configuring, and using LexKit extensions. Learn about the core interfaces, types, and functions that power the extension system.

Type-SafeFunctional APIComplete Reference

Quick Links

Creating Extensions Guide

Step-by-step guide to building custom extensions with interactive examples and best practices.

createEditorSystem API

Learn how to create typed editor systems from your extension arrays.

Core API Overview

The extension system is built around a few key interfaces and functions that work together to provide type safety and modularity.

createExtension

Factory function for creating type-safe extensions with a functional API. Perfect for simple extensions and rapid development.

BaseExtension

Abstract base class for creating extensions with traditional object-oriented patterns. Ideal for complex extensions with inheritance.

Extension Types

Core TypeScript interfaces and types that define the extension contract and ensure type safety throughout the system.

createExtension Function

The primary factory function for creating type-safe extensions.

Function Signature

createExtension Type Signature

export function createExtension<
  Name extends string,
  Config extends BaseExtensionConfig,
  Commands extends Record<string, any>,
  StateQueries extends Record<string, () => Promise<boolean>>,
  Plugins extends ReactNode[]
>(
  config: CreateExtensionConfig<Name, Config, Commands, StateQueries, Plugins>
): BaseExtension<Name, Config, Commands, StateQueries, Plugins>

Parameters

Parameter	Type	Description
`config`	`CreateExtensionConfig`	Configuration object defining the extension's behavior

CreateExtensionConfig Properties

Property	Type	Required	Description
`name`	`string`	Yes	Unique identifier for the extension
`category`	`ExtensionCategory[]`	No	Categories this extension belongs to
`config`	`Partial<Config>`	No	Default configuration values
`commands`	`(editor: LexicalEditor) => Commands`	No	Function returning command implementations
`stateQueries`	`(editor: LexicalEditor) => StateQueries`	No	Function returning state query implementations
`plugins`	`ReactNode[]`	No	React components to render as plugins
`initialize`	`(editor: LexicalEditor) => (() => void) \| void`	No	Initialization function called when extension is registered
`nodes`	`any[]`	No	Custom Lexical nodes provided by the extension
`supportedFormats`	`readonly TextFormatType[]`	No	Text formats supported by this extension

Example Usage

Creating an extension with createExtension

const myExtension = createExtension({
  name: 'my-extension',
  commands: (editor) => ({
    myCommand: () => console.log('Hello!'),
  }),
  stateQueries: (editor) => ({
    isActive: async () => true,
  }),
  initialize: (editor) => {
    console.log('Extension initialized');
    return () => {
      console.log('Extension cleaned up');
    };
  }
});

BaseExtension Class

Abstract base class for creating extensions with object-oriented patterns.

Class Signature

BaseExtension Class Definition

export abstract class BaseExtension<
  Name extends string = string,
  Config extends BaseExtensionConfig = BaseExtensionConfig,
  Commands extends Record<string, any> = {},
  StateQueries extends Record<string, () => Promise<boolean>> = {},
  Plugins extends ReactNode[] = ReactNode[]
> implements Extension<Name, Config, Commands, StateQueries, Plugins> {
  // Properties and methods...
}

Key Methods

Method	Return Type	Description
`register(editor)`	`() => void`	Register the extension with the Lexical editor
`getCommands(editor)`	`Commands`	Return command implementations
`getStateQueries(editor)`	`StateQueries`	Return state query implementations
`getPlugins()`	`Plugins`	Return React plugins/components
`getNodes()`	`any[]`	Return custom Lexical nodes
`configure(config)`	`this`	Configure the extension with new settings

Example Implementation

Creating an extension with BaseExtension

class MyExtension extends BaseExtension<'my-extension'> {
  constructor() {
    super('my-extension');
  }

  register(editor: LexicalEditor): () => void {
    // Registration logic
    return () => {
      // Cleanup logic
    };
  }

  getCommands(editor: LexicalEditor) {
    return {
      myCommand: () => console.log('Hello!'),
    };
  }

  getStateQueries(editor: LexicalEditor) {
    return {
      isActive: async () => true,
    };
  }
}

const myExtension = new MyExtension();

Core Types & Interfaces

Essential TypeScript types that define the extension system.

Extension Interface

Extension Interface Definition

export interface Extension<
  Name extends string = string,
  Config extends BaseExtensionConfig = BaseExtensionConfig,
  Commands extends Record<string, any> = {},
  StateQueries extends Record<string, () => Promise<boolean>> = {},
  Plugins extends ReactNode[] = ReactNode[]
> {
  name: Name;
  category: ExtensionCategory[];
  config: Config;
  supportedFormats: readonly TextFormatType[];

  register(editor: LexicalEditor): () => void;
  getCommands(editor: LexicalEditor): Commands;
  getStateQueries(editor: LexicalEditor): StateQueries;
  getPlugins(): Plugins;
  getNodes(): any[];
  configure(config: Partial<Config>): this;
}

ExtensionCategory Enum

Extension Categories

export enum ExtensionCategory {
  Toolbar = 'toolbar',
  Sidebar = 'sidebar',
  ContextMenu = 'context-menu',
  StatusBar = 'status-bar',
  Core = 'core',
  Formatting = 'formatting',
  Media = 'media',
  Export = 'export',
  Custom = 'custom'
}

BaseExtensionConfig Interface

Base Configuration Interface

export interface BaseExtensionConfig {
  /** Whether the extension is enabled */
  enabled?: boolean;

  /** Priority for extension loading (higher = loaded first) */
  priority?: number;

  /** Plugin position relative to editor content */
  position?: 'before' | 'after';

  /** Custom CSS classes for styling */
  className?: string;

  /** Additional configuration properties */
  [key: string]: any;
}

API Best Practices

Guidelines for building robust and maintainable extensions.

Type Safety

Leverage TypeScript's type system to ensure compile-time safety. Define clear interfaces for commands and state queries.

Proper Cleanup

Always return cleanup functions from registration methods. Properly dispose of event listeners and resources.

Performance

Use editor.read() for reading operations and editor.update() for mutations. Avoid unnecessary re-renders and optimize state queries.

Documentation

Document your extension's API with JSDoc comments. Include examples and usage patterns for other developers.