ADR-0010: UI 프레임워크

이후 변경

  • 2026-11-01: 주변 UI의 CSS는 editor 안의 TypeScript 문자열로 두고 <style>로 넣는다(CSS 로더 없이 모든 셸에서 같게). UI의 한 부분을 여는 명령(환경 설정, 커맨드 팔레트 등)은 그 UI가 명령 목록에 등록한다 → 9. React, 5. 명령 목록과 메뉴
  • 2026-11-01: React가 그리는 주변 UI에 메뉴 바, 커맨드 팔레트, 키 힌트, 모달이 더해졌다 → 1. 화면 구성
  • 2026-10-22: 용어를 SW 엔지니어의 말로 고쳤다(뜻은 그대로). → 01-architecture

배경

packages/editor(편집 UI)를 만들 방식을 정해야 한다. 2026-10-07에 “제안됨”으로 열어 두었다.

그사이 두 결정이 이 물음을 작게 만들었다.

  • 다이어그램은 화면에서도 core의 렌더러가 그린다(ADR-0030). 선택 오버레이, 키 입력 처리(Vim 키, 한글 IME), 블록 위의 인라인 텍스트 입력 필드도 프레임워크 없이 TypeScript로 짠다.
  • 편집기는 명령 레지스트리와 설정 스키마를 제공 인터페이스로 노출하고, Obsidian과 IDE에서는 셸이 그것을 호스트 프로그램의 메뉴와 설정 화면에 등록한다(ADR-0033).

그래서 프레임워크가 맡는 곳은 우리가 직접 그리는 주변 UI 컴포넌트뿐이다: 웹 · 데스크톱 · Confluence의 도구 모음 · 우클릭 메뉴 · 설정 창, 문제 알리기 보고서, 웹의 AI 대화창, 그리고 모든 대상의 도구 모음.

결정 기준

  • 배포 대상 여섯(웹, Obsidian, 데스크톱, Confluence, VSCode, IntelliJ)에 같은 방식으로 붙는다
  • 번들 크기 증가 (Obsidian 플러그인 main.js는 글꼴과 wasm으로 이미 2 MB쯤)
  • UI 컴포넌트가 늘 때 유지보수 비용이 덜 든다
  • 메인테이너(프론트엔드는 처음)가 읽을 수 있다
  • 개발자 층, 자료, 배포 대상의 관례

검토한 대안

같은 도구 모음을 네 방식으로 구현해 빌드하고 번들 크기를 쟀다(2026-10-18). 코드와 견준 표는 시안 M22의 U2에 있다: https://claude.ai/artifact/1gXCQSyoSnPcTP3ro64d5Z (저장소의 사본 journal/assets/2026-10-18-ui-framework-study.html, 코드와 재는 스크립트 journal/assets/2026-10-18-ui-framework-spike/)

안minify 크기gzip
프레임워크 없음1.9 KB0.9 KB
Svelte 5.5757.5 KB21.4 KB
React 19.3219.8 KB68.1 KB
Preact 11.014.5 KB6.1 KB

프레임워크 없음 (TypeScript + DOM)

  • 장점: 런타임 의존성이 없다. 프로토타입(M01)이 이렇게 짜여 있다
  • 단점: 상태가 바뀔 때의 DOM 갱신을 명령형으로 손수 짠다. AI 대화창처럼 요소가 동적으로 늘고 주는 화면은 손이 많이 간다

Svelte 5

  • 장점: 템플릿 문법이 HTML과 가까워 읽기 쉽다. 반응형이라 상태만 바꾸면 DOM이 갱신된다. Obsidian 공식 문서에 통합 가이드가 있다
  • 단점: 개발자 층이 React보다 훨씬 얇다. 5판에서 API(runes)가 바뀌어 자료가 적다

React 19

  • 장점: 개발자 층이 가장 두텁다(Stack Overflow 조사 2024 “써 봤다” 약 40%, Svelte는 약 6.5%). 자료와 컴포넌트 라이브러리가 가장 많다. Confluence Forge와 VSCode 웹뷰의 관례다. 불변 문서(ADR-0029)와 잘 맞는다
  • 단점: 넷 가운데 번들이 가장 크다. 상태가 바뀌면 컴포넌트 함수를 다시 실행하는 렌더링 모델과 훅의 규칙을 익혀야 읽힌다

Preact

  • 장점: React와 API가 같고(호환 레이어) 작다
  • 단점: React의 컴포넌트 라이브러리가 가끔 호환되지 않는다

결정

React. 메인테이너가 시안 M22의 U2에서 3번(추천)을 골랐다 (2026-10-18).

  • 크기는 결정을 가르지 않았다. React를 넣어도 Obsidian 플러그인이 1할쯤 커진다.
  • Claude는 처음에 Svelte를 추천했다(읽기 쉬움을 가장 무겁게 봄). 메인테이너가 “Svelte과 React의 개발자 층은 어느 것이 두터운가요?”라고 물어, 견주지 않았던 개발자 층과 배포 대상의 관례를 더해 React로 바꿨다.
  • React는 주변 UI 컴포넌트에만 쓴다. 다이어그램 영역, 선택 오버레이, 키 입력 처리, 인라인 텍스트 입력 필드는 React 밖의 TypeScript로 두고, React 컴포넌트는 편집기 상태를 구독하고 CommandRegistry로 명령을 실행하기만 한다.

결과

  • 좋아지는 점: 자료와 사람이 가장 많다. Confluence와 VSCode 셸을 만들 때 관례를 따를 수 있다.
  • 감수하는 점: 웹 번들이 68 KB(gzip)쯤 는다. 메인테이너가 코드를 읽으려면 React의 방식을 익혀야 한다.
  • 교체 비용: 주변 UI 컴포넌트만 다시 짠다. 다이어그램 · 키 입력 처리 · 인라인 텍스트 입력 필드는 React에 의존하지 않는다.
  • 후속 작업: 화면 구성과 React 컴포넌트의 경계 → 1. 화면 구성. React를 메인테이너에게 설명하는 기술 정리