0
# Plate Core
1

2
Plate Core is the foundation of the Plate rich text editor framework, providing a comprehensive plugin system, editor creation utilities, serialization capabilities, and extensible architecture for building rich text editing experiences. It extends Slate.js with powerful abstractions, type safety, and a rich ecosystem of plugins and utilities.
3

4
## Package Information
5

6
- **Package Name**: @platejs/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @platejs/core`
10

11
## Core Imports
12

13
```typescript
14
import { createSlateEditor, SlateEditor } from "@platejs/core";
15
import { createSlatePlugin, getCorePlugins } from "@platejs/core";
16
```
17

18
For specific functionality:
19

20
```typescript
21
import { 
22
  HtmlPlugin, 
23
  deserializeHtml, 
24
  HistoryPlugin,
25
  DebugPlugin
26
} from "@platejs/core";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { createSlateEditor, getCorePlugins, createSlatePlugin } from "@platejs/core";
33

34
// Create a basic editor with core plugins
35
const editor = createSlateEditor({
36
  plugins: getCorePlugins()
37
});
38

39
// Create a custom plugin
40
const CustomPlugin = createSlatePlugin({
41
  key: 'custom',
42
  node: { type: 'custom' }
43
});
44

45
// Create editor with custom plugins
46
const customEditor = createSlateEditor({
47
  plugins: [
48
    ...getCorePlugins(),
49
    CustomPlugin
50
  ]
51
});
52

53
// Basic editor operations
54
editor.insertText('Hello world');
55
editor.insertBreak();
56
```
57

58
## Architecture
59

60
Plate Core is built around several key architectural components:
61

62
- **Plugin System**: Comprehensive plugin architecture where all functionality is plugin-based, including core features
63
- **Editor Factory**: `createSlateEditor` function that creates fully-configured editor instances with plugin integration
64
- **Core Plugins**: 12+ essential plugins automatically included for basic editor functionality
65
- **Type System**: Full TypeScript integration with sophisticated type inference for plugins and editor operations
66
- **Extensibility**: Multiple extension points allowing deep customization of editor behavior
67
- **Serialization**: Multi-format serialization support (HTML, AST fragments, custom formats)
68
- **Performance**: Built-in optimizations including chunking for large documents and lazy plugin loading
69

70
## Capabilities
71

72
### Editor Creation and Configuration
73

74
Core functionality for creating and configuring Slate editors with Plate enhancements, plugin integration, and type safety.
75

76
```typescript { .api }
77
function createSlateEditor(options?: {
78
  plugins?: any[];
79
  value?: any[];
80
  editor?: BaseEditor;
81
}): SlateEditor;
82

83
function withSlate(editor: BaseEditor): SlateEditor;
84
```
85

86
[Editor Creation](./editor-creation.md)
87

88
### Plugin System
89

90
Comprehensive plugin architecture for extending editor functionality with type-safe configuration, lifecycle hooks, and extensibility patterns.
91

92
```typescript { .api }
93
function createSlatePlugin<T>(config: PluginConfig<T>): SlatePlugin<T>;
94
function getCorePlugins(): CorePlugin[];
95
function getSlatePlugin<T>(plugin: WithRequiredKey<T>): T;
96

97
interface PluginConfig<T = {}> {
98
  key: string;
99
  node?: NodeConfig;
100
  api?: ApiConfig;
101
  transforms?: TransformConfig;
102
  options?: T;
103
}
104
```
105

106
[Plugin System](./plugin-system.md)
107

108
### HTML Serialization
109

110
Complete HTML serialization and deserialization system with customizable parsing, cleaning utilities, and Slate format conversion.
111

112
```typescript { .api }
113
const HtmlPlugin: SlatePlugin;
114

115
function deserializeHtml(
116
  editor: SlateEditor, 
117
  options: {
118
    element: HTMLElement | string;
119
    collapseWhiteSpace?: boolean;
120
  }
121
): any[];
122

123
function serializeHtml(
124
  editor: SlateEditor,
125
  options?: { nodes?: any[] }
126
): string;
127
```
128

129
[HTML Serialization](./html-serialization.md)
130

131
### Core Plugins
132

133
Essential plugins that provide fundamental editor functionality including history, debugging, DOM management, and node handling.
134

135
```typescript { .api }
136
const HistoryPlugin: SlatePlugin;
137
const DebugPlugin: SlatePlugin;
138
const DOMPlugin: SlatePlugin;
139
const ParserPlugin: SlatePlugin;
140
const NodeIdPlugin: SlatePlugin;
141
```
142

143
[Core Plugins](./core-plugins.md)
144

145
### Transform Functions
146

147
Editor manipulation functions for programmatic content modification, selection handling, and editor state management.
148

149
```typescript { .api }
150
interface EditorTransforms {
151
  init(options: { value?: any[]; selection?: any }): void;
152
  setValue(value: any[]): void;
153
  insertExitBreak(): void;
154
  resetBlock(options?: { type?: string }): void;
155
}
156
```
157

158
[Transform Functions](./transform-functions.md)
159

160
### Type System and Interfaces
161

162
Comprehensive TypeScript interfaces and type utilities for type-safe editor development with full plugin inference.
163

164
```typescript { .api }
165
interface SlateEditor extends BaseEditor {
166
  api: EditorApi;
167
  plugins: Record<string, any>;
168
  transforms: EditorTransforms;
169
  getPlugin<T>(plugin: WithRequiredKey<T>): T;
170
  getApi<T>(plugin?: WithRequiredKey<T>): EditorApi & InferApi<T>;
171
}
172

173
interface BaseEditor {
174
  children: any[];
175
  selection: any;
176
  operations: any[];
177
}
178

179
type InferApi<T> = T extends { api: infer A } ? A : {};
180
type InferTransforms<T> = T extends { transforms: infer Tr } ? Tr : {};
181
```
182

183
[Type System](./type-system.md)
184

185
### Event Handling and Hotkeys
186

187
Comprehensive event handling system with cross-platform hotkey support, customizable shortcuts, and event pipeline management.
188

189
```typescript { .api }
190
interface Hotkeys {
191
  createHotkey(hotkey: string): (event: KeyboardEvent) => boolean;
192
  isHotkey(hotkey: string, event: KeyboardEvent): boolean;
193
  parseHotkey(hotkey: string): { key: string; modifiers: string[] };
194
}
195

196
const Hotkeys: Hotkeys;
197
```
198

199
[Event Handling](./event-handling.md)
200

201
### Utility Functions
202

203
Essential utility functions for node manipulation, plugin management, and editor state operations.
204

205
```typescript { .api }
206
function applyDeepToNodes(options: {
207
  node: any;
208
  source: any;
209
  apply: (node: any) => any;
210
}): any;
211

212
function mergeDeepToNodes(options: {
213
  node: any;
214
  source: any;
215
}): any;
216

217
function overridePluginsByKey(
218
  plugins: any[],
219
  overrides: Record<string, any>
220
): any[];
221
```
222

223
[Utility Functions](./utility-functions.md)
224

225
### Multi-format Serialization
226

227
Support for multiple serialization formats including HTML, AST fragments, and custom format parsing with extensible parser system.
228

229
```typescript { .api }
230
const AstPlugin: SlatePlugin;
231
const ParserPlugin: SlatePlugin;
232

233
interface ParserOptions {
234
  format: string;
235
  mimeType: string;
236
  deserialize: (data: string) => any[];
237
}
238
```
239

240
[Multi-format Serialization](./multi-format-serialization.md)
241

242
## Constants and Enums
243

244
```typescript { .api }
245
// Plugin priorities
246
const PRIORITY_LOW = 75;
247
const PRIORITY_NORMAL = 100;
248
const PRIORITY_HIGH = 125;
249

250
// Core plugin keys
251
const PLUGIN_KEYS = {
252
  HISTORY: 'history',
253
  DEBUG: 'debug',
254
  HTML: 'html',
255
  DOM: 'dom',
256
  PARSER: 'parser'
257
} as const;
258
```