LexKit Docs

Type Definitions

Complete TypeScript reference for LexKit

Comprehensive TypeScript definitions that power LexKit's type-safe architecture. Understand the core interfaces, generics, and utility types that make LexKit type-safe.

Type-SafeGeneric TypesComplete Reference

Quick Links

createEditorSystem API

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

Extensions API

Complete API reference for creating, configuring, and using LexKit extensions.

Core Concepts

LexKit's type system is built around several key concepts that work together to provide compile-time safety and excellent developer experience.

Generic Types

Extensive use of TypeScript generics to provide type safety at compile time, ensuring that commands, state queries, and plugins are correctly typed.

Extension Arrays

Type-safe arrays of extensions that are analyzed at compile time to extract available commands, state queries, and plugin types.

Type Inference

Advanced type inference utilities that automatically extract and merge types from extension arrays, providing IntelliSense and compile-time validation.

Editor Configuration Types

Types that define how the editor is configured and themed.

EditorConfig Interface

export interface EditorConfig {
  /** Theme configuration for different node types */
  theme?: LexKitTheme;
  /** Placeholder text to display when editor is empty */
  placeholder?: string;
  /** Additional configuration options */
  [key: string]: any;
}

NodeTheme Interface

export interface NodeTheme {
  /** CSS class name for the node */
  className?: string;
  /** Inline CSS styles for the node */
  style?: CSSProperties;
}

Editor Context Types

The main context type that provides type-safe access to the editor and its extensions.

EditorContextType Interface

Generic interface that provides strongly typed access to editor functionality based on the extensions array

EditorContextType Interface

export interface EditorContextType<Exts extends readonly Extension[]> {
  /** The Lexical editor instance */
  editor: LexicalEditor | null;
  /** Editor configuration */
  config: EditorConfig;
  /** Array of registered extensions */
  extensions: Exts;
  /** Dynamic commands aggregated from all extensions */
  commands: any;
  /** Dynamic active states from all extensions */
  activeStates: any;
  /** Event listeners for editor updates */
  listeners: {
    /** Register a listener for editor state updates */
    registerUpdate: (listener: (state: any) => void) => () => void;
    /** Register a listener for node mutations (optional) */
    registerMutation?: (listener: (mutations: any) => void) => () => void;
    /** Register a listener for paste events */
    registerPaste: (listener: (event: ClipboardEvent) => boolean) => () => void;
  };
  /** Export functionality */
  export: {
    /** Export editor content to HTML */
    toHTML: () => Promise<string>;
    /** Export editor content to Markdown */
    toMarkdown: () => Promise<string>;
    /** Export editor content to JSON */
    toJSON: () => any;
  };
  /** Import functionality */
  import: {
    /** Import HTML content into the editor */
    fromHTML: (html: string) => Promise<void>;
    /** Import Markdown content into the editor */
    fromMarkdown: (md: string) => Promise<void>;
    /** Import JSON content into the editor */
    fromJSON: (json: any) => void;
  };
  /** Direct access to the Lexical editor instance */
  lexical: LexicalEditor | null;
  /** API for managing extensions at runtime */
  extensionsAPI: {
    /** Add a new extension */
    add: (ext: Extension) => void;
    /** Remove an extension by name */
    remove: (name: string) => void;
    /** Reorder extensions by name array */
    reorder: (names: string[]) => void;
  };
  /** React plugins from extensions */
  plugins: ReactNode[];
  /** Plugins that render before children */
  pluginsBefore: ReactNode[];
  /** Plugins that render after children */
  pluginsAfter: ReactNode[];
  /** Check if a specific extension is registered */
  hasExtension: (name: Exts[number]['name']) => boolean;
}

Key Properties

Property	Type	Description
`editor`	`LexicalEditor \| null`	The raw Lexical editor instance
`config`	`EditorConfig`	Editor configuration including theme
`extensions`	`Exts`	Array of registered extensions (typed)
`commands`	`any`	Aggregated commands from all extensions
`activeStates`	`any`	Current state of all extensions
`plugins`	`ReactNode[]`	React plugins from extensions
`hasExtension`	`Function`	Check if a specific extension is loaded

Extension Types

Core types that define the extension system and its contracts.

ExtensionCategory Enum

Extension Categories

export enum ExtensionCategory {
  Toolbar = 'toolbar',
  Sidebar = 'sidebar',
  ContextMenu = 'contextmenu',
  Floating = 'floating',
  // Add more as needed
}

BaseExtensionConfig Interface

Base Configuration Interface

export interface BaseExtensionConfig {
  showInToolbar?: boolean;
  category?: ExtensionCategory[];
  position?: 'before' | 'after';
  [key: string]: any;
}

Extension Interface

The core interface that all extensions must implement, with extensive generic type parameters

Extension Interface

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[]> {
  /** Unique identifier for this extension */
  name: Name;

  /** Categories this extension belongs to */
  category: ExtensionCategory[];

  /** Configuration object */
  config: Config;

  /** Text formats supported by this extension */
  supportedFormats?: readonly TextFormatType[];

  /** Configure the extension with new settings */
  configure?: (config: Partial<Config>) => Extension<Name, Config, Commands, StateQueries, Plugins>;

  /** Register the extension with the Lexical editor */
  register: (editor: LexicalEditor) => () => void;

  /** Override the UI component for this extension */
  overrideUI?: (CustomUI: ComponentType<{ selected?: boolean; className?: string; style?: CSSProperties; [key: string]: any }>) => Extension<Name, Config, Commands, StateQueries, Plugins>;

  /** Override node rendering */
  overrideNodeRender?: (overrides: { createDOM?: (config: any) => HTMLElement; updateDOM?: (prev: any, next: any, dom: HTMLElement) => boolean }) => Extension<Name, Config, Commands, StateQueries, Plugins>;

  /** Get custom Lexical nodes */
  getNodes?: () => any[];

  /** Get React plugins */
  getPlugins: () => Plugins;

  /** Get commands provided by this extension */
  getCommands: (editor: LexicalEditor) => Commands;

  /** Get state query functions */
  getStateQueries?: (editor: LexicalEditor) => StateQueries;

  /** Get toolbar items (legacy) */
  // getToolbarItems?(): ToolbarItem<Commands>[];
}

Type Extraction Utilities

Advanced TypeScript utilities that extract and merge types from extension arrays.

BaseCommands Interface

Base Commands

export interface BaseCommands {
  formatText: (format: TextFormatType, value?: boolean | string) => void;
}

Type Extraction Helpers

Utility types that analyze extension arrays to extract available functionality

Type Extraction Utilities

// Infer unions from array of extensions
export type ExtractNames<Exts extends readonly Extension[]> = Exts[number]['name'];
export type ExtractCommands<Exts extends readonly Extension[]> = MergeCommands<
  ReturnType<Exts[number]['getCommands']>
>;
export type ExtractPlugins<Exts extends readonly Extension[]> = ReturnType<Exts[number]['getPlugins']>[number];

// Extract state queries similarly
export type ExtractStateQueries<Exts extends readonly Extension[]> = MergeStateQueries<
  ReturnType<NonNullable<Exts[number]['getStateQueries']>>
>;

EditorContextType (Extensions Version)

The extensions version of EditorContextType with proper type extraction

EditorContextType (Extensions)

export interface EditorContextType<Exts extends readonly Extension[]> {
  /** Raw Lexical editor instance */
  editor: LexicalEditor | null;

  /** Editor configuration */
  config?: EditorConfig;

  /** Array of loaded extensions */
  extensions: Exts;

  /** Available commands from all extensions */
  commands: BaseCommands & ExtractCommands<Exts>;

  /** Current state of all extensions */
  activeStates: ExtractStateQueries<Exts>;

  /** State query functions from all extensions */
  stateQueries: Record<string, () => Promise<any>>;

  /** Event listener registration functions */
  listeners: {
    registerUpdate: (listener: (state: any) => void) => (() => void) | undefined;
    registerPaste: (listener: (event: ClipboardEvent) => boolean) => (() => void) | undefined;
  };

  /** Export functions for different formats */
  export: {
    toHTML: () => Promise<string>;
    toMarkdown: () => Promise<string>;
    toJSON: () => any;
  };

  /** Import functions for different formats */
  import: {
    fromHTML: (html: string) => Promise<void>;
    fromMarkdown: (md: string) => Promise<void>;
    fromJSON: (json: any) => void;
  };

  /** Alias for the raw Lexical editor */
  lexical: LexicalEditor | null;

  /** API for managing extensions dynamically */
  extensionsAPI: {
    add: (ext: Extension) => void;
    remove: (name: string) => void;
    reorder: (names: string[]) => void;
  };

  /** React plugins from all extensions */
  plugins: ExtractPlugins<Exts>[];

  /** Check if a specific extension is loaded */
  hasExtension: (name: ExtractNames<Exts>) => boolean;
}

Type System Benefits

How LexKit's advanced type system improves your development experience.

IntelliSense Support

Get full autocomplete for commands, state queries, and extension methods. Never guess what methods are available on your editor context.

Compile-Time Safety

Catch extension configuration errors and API misuse at compile time, preventing runtime errors and improving code reliability.

Refactoring Safety

When you change extension APIs or add/remove extensions, TypeScript will guide you through all the necessary updates.

Better DX

Rich type information enables better IDE support, documentation, and makes the codebase more maintainable and self-documenting.

Usage Examples

See how the type system works in practice with real code examples.

Typed Extension Array

Creating a type-safe array of extensions that TypeScript can analyze

Typed Extension Usage

const extensions = [
  boldExtension,
  italicExtension,
  linkExtension
] as const;

type MyEditorContext = EditorContextType<typeof extensions>;

// Now you have full type safety!
const MyEditor: React.FC = () => {
  const { commands, activeStates } = useEditor();
  // commands has all available commands with proper types
  // activeStates has all state queries with boolean types
};