시작하기 | reopt design docs

시작하기

패키지 설치, EditorProvider 설정, 첫 에디터 렌더링까지의 빠른 시작 가이드

reopt design업데이트 2026년 8월 2일

1. 패키지 설치

권장 설정: 전용 스킬

신규 설치와 업그레이드, 필수 CSS와 첫 Editor 연결, 선택적 AI 스트리밍 설정 및 검증을 처리합니다.

소비자 프로젝트 루트에서 스킬을 에이전트 런타임에 설치합니다. 이미 설치했다면 이 명령은 생략할 수 있습니다.

bash

npx skills add reopt-ai/reopt-skills/opt-editor-install

설치 후 에이전트에게 아래처럼 요청하세요. 스킬은 현재 설치 상태를 확인해 신규 설치와 업그레이드를 구분합니다.

text

opt-editor-install 스킬로 이 프로젝트에 @reopt-ai/opt-editor을 설정하고 결과까지 검증해줘.

스킬은 소비자 프로젝트의 AGENTS.md(없으면 CLAUDE.md)에 reopt marker 블록을 멱등하게 갱신하고, 설치된 패키지 버전의 문서를 읽은 뒤 typecheck·doctor 등 해당 모듈의 검증을 실행합니다.

아래 패키지 설치 명령은 스킬을 사용할 수 없거나 설정 과정을 직접 통제해야 할 때의 수동 대안입니다. 스킬 소스와 최신 지원 범위 확인.

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

bash

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

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

Peer dependencies:

패키지	버전
react	^19.0.0
react-dom	^19.0.0

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

tsx

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

2. 첫 번째 에디터

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

tsx

"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>
  );
}

모드	용도	특징
stream	AI 생성 콘텐츠 표시	읽기 전용, NDJSON 패치 실시간 적용
edit	사용자 직접 편집	contentEditable, 마크다운 단축키, 슬래시 명령

3. 초기 콘텐츠 설정

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

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

tsx

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,
});

Flat map 구조의 장점: 트리 대신 flat map을 사용하면 AI 스트리밍 시 인덱스 시프트 없이 요소를 추가할 수 있고, RFC 6902 JSON Patch와 자연스럽게 호환되며, O(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()로 히스토리 탐색

tsx

// 마크다운 단축키 예시 (줄 시작에서 입력)
// "#␣"      → 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 양방향 변환

시작하기

패키지 설치, EditorProvider 설정, 첫 에디터 렌더링까지의 빠른 시작 가이드

reopt design업데이트 2026년 8월 2일

1. 패키지 설치

권장 설정: 전용 스킬

신규 설치와 업그레이드, 필수 CSS와 첫 Editor 연결, 선택적 AI 스트리밍 설정 및 검증을 처리합니다.

소비자 프로젝트 루트에서 스킬을 에이전트 런타임에 설치합니다. 이미 설치했다면 이 명령은 생략할 수 있습니다.

bash

npx skills add reopt-ai/reopt-skills/opt-editor-install

설치 후 에이전트에게 아래처럼 요청하세요. 스킬은 현재 설치 상태를 확인해 신규 설치와 업그레이드를 구분합니다.

text

opt-editor-install 스킬로 이 프로젝트에 @reopt-ai/opt-editor을 설정하고 결과까지 검증해줘.

아래 패키지 설치 명령은 스킬을 사용할 수 없거나 설정 과정을 직접 통제해야 할 때의 수동 대안입니다. 스킬 소스와 최신 지원 범위 확인.

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

bash

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

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

Peer dependencies:

패키지	버전
react	^19.0.0
react-dom	^19.0.0

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

tsx

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

2. 첫 번째 에디터

tsx

"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>
  );
}

모드	용도	특징
stream	AI 생성 콘텐츠 표시	읽기 전용, NDJSON 패치 실시간 적용
edit	사용자 직접 편집	contentEditable, 마크다운 단축키, 슬래시 명령

3. 초기 콘텐츠 설정

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

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

tsx

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()로 히스토리 탐색

tsx

// 마크다운 단축키 예시 (줄 시작에서 입력)
// "#␣"      → 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 양방향 변환