시작하기

1. 패키지 설치

@reopt-ai/opt-editor는 React 19 이상을 peer dependency로 요구합니다. 별도 CSS 라이브러리나 상태 관리 도구 없이 동작합니다.

# npm
npm install @reopt-ai/opt-editor

# bun
bun add @reopt-ai/opt-editor

Peer dependencies:

기본 에디터 스타일을 적용하려면 엔트리포인트에서 스타일시트를 import 하세요:

import "@reopt-ai/opt-editor/styles.css";

2. 첫 번째 에디터

에디터를 렌더링하려면 세 가지 핵심 요소가 필요합니다: createEditorStore로 상태를 생성하고, EditorProvider로 컨텍스트를 제공한 뒤, Editor컴포넌트로 렌더링합니다.

"use client";

import { useMemo } from "react";
import {
  Editor,
  EditorProvider,
  createEditorStore,
  defaultCatalog,
} from "@reopt-ai/opt-editor";
import "@reopt-ai/opt-editor/styles.css";

export default function App() {
  const store = useMemo(() => createEditorStore(), []);

  return (
    <EditorProvider store={store} catalog={defaultCatalog}>
      <Editor store={store} catalog={defaultCatalog} mode="edit" />
    </EditorProvider>
  );
}

3. 초기 콘텐츠 설정

createEditorStore에 EditorSpec을 전달하면 초기 콘텐츠가 설정됩니다. EditorSpec은 세 가지 필드로 구성됩니다:

• root — 최상위 요소 ID의 표시 순서 배열
• elements — 모든 요소를 ID로 매핑한 flat map (Record<string, EditorElement>)
• version — 낙관적 동시성 버전 번호 (mutation마다 자동 증가)

const store = createEditorStore({
  root: ["h1", "p1"],
  elements: {
    h1: {
      id: "h1",
      type: "heading",
      props: { text: "Hello", level: 1 },
    },
    p1: {
      id: "p1",
      type: "paragraph",
      props: { text: "Welcome to **opt-editor**." },
    },
  },
  version: 1,
});

4. 편집 모드 활용

mode="edit"에서는 사용자가 직접 콘텐츠를 편집할 수 있습니다. 다음 기능이 지원됩니다:

• contentEditable — 텍스트 블록을 클릭하여 바로 편집. 변경 사항이 store에 자동 반영
• 마크다운 단축키 — 줄 시작에서 # → heading, > → quote, ``` → code 블록으로 자동 변환
• 슬래시 명령 — /를 입력하면 블록 타입 선택 메뉴가 표시. heading, list, code, quote, divider, callout, table, image 등 삽입
• 인라인 마크 — 텍스트 내에서 **bold**, *italic*, `code` 마크다운 구문이 렌더링 시 서식으로 변환
• Split/Merge — Enter로 블록 분할, Backspace로 이전 블록과 병합
• Undo/Redo — store.undo() / store.redo()로 히스토리 탐색

// 마크다운 단축키 예시 (줄 시작에서 입력)
// "#␣"      → heading (level 1)
// "##␣"     → heading (level 2)
// ">␣"      → quote
// "```"    → code block
// "-␣"      → unordered list
// "1.␣"     → ordered list
// "---"     → divider

// 슬래시 명령 예시
// "/"       → 블록 타입 선택 메뉴 열기
// "/heading" → heading 블록 삽입
// "/table"  → table 블록 삽입
// "/image"  → image 블록 삽입

5. 다음 단계

기본 에디터를 실행했다면, 다음 문서를 통해 더 깊이 알아보세요:

• 핵심 개념 — Flat Spec 아키텍처, EditorStore API, 카탈로그와 검증 시스템
• 블록 타입 레퍼런스 — 15개 기본 블록의 Props, 중첩 구조, 렌더링 방식
• AI 연동 — buildSystemPrompt, SSE 스트림 처리, useEditorStream 훅 활용
• 스트리밍 프로토콜 — NDJSON 패치 규칙, StreamCompiler, 재시도/이어쓰기
• 커스텀 블록 — BlockDefinition 작성, defineCatalog 확장
• Markdown 변환 — specToMarkdown, markdownToSpec 양방향 변환