Getting started

Install

bun

bun add @adecore/editor

npm

npm install @adecore/editor

pnpm

pnpm add @adecore/editor

The package brings @adecore/editor-core and Shiki along. It has no React and no peer dependencies.

Styles

Import the theme of @adecore/ui first and the editor's styles after it. The editor reads the theme's tokens for its surface, text, accent and status colors, and its own --editor-*, --find-* and --agent-* tokens build on those.

@import '@adecore/ui/theme.css';
@import '@adecore/editor/editor.css';

An app without that theme defines the tokens itself: --surface, --surface-raised, --surface-hover, --border, --text, --text-muted, --text-faint, --accent, the four --status-* colors, the radii, --font-sans, --font-mono and the --text-xs and --text-code sizes. See Theme and syntax.

Mount an editor

Create an engine once and mount it into an element. The editor fills the element, so the element needs a position and a size from its parent.

import { createSmartEditorEngine } from '@adecore/editor';

const engine = createSmartEditorEngine({ tokenizer: async () => null });

const editor = engine.mount(element, {
    text: 'const greeting = "hello";\n',
    language: 'typescript',
    theme: 'github-light'
});

const stopSave = editor.onSave(() => save(editor.getText()));

text and theme are the only required options; Options and keymaps lists the rest. The tokenizer above colors nothing. Theme and syntax wires Shiki.

Give the element something like position: relative; height: 400px. Inside a flex or grid layout, its parent may also need min-height: 0. The editor follows the element's size through a ResizeObserver.

Mod+S, which is Cmd+S on a Mac and Ctrl+S elsewhere, calls onSave listeners and nothing else. What saving means is the app's: the path, the permission and the write.

Engine options

One engine can mount any number of editors. Each editor has its own document, history and decorations; the engine holds what they share.

SmartEditorEngineOptions	Default	Meaning
tokenizer	required	Returns the LineTokenizer for a language and theme, or null for plain text
scopeColors		The colors of a theme by TextMate scope; without it semantic tokens are ignored
keymap	KEYMAP	The key table; see keymaps
handBack	[]	KeyChords the editor leaves alone, so the app's own shortcuts work from inside it
apple	false	Read Ctrl and Meta the way macOS does

The tokenizer loads while the editor is already on screen and editable. A tokenizer that fails, or answers after a newer theme was set, is ignored.

Tear down

dispose() removes the editor's DOM and its listeners. Call the functions that on* methods return when what listened goes away first. One element holds one editor: dispose the old one before mounting another.

stopSave();
editor.dispose();