xushanpei/open-file-viewer 딥다이브
— 50가지 파일을 한 컨테이너에 띄우는 프리뷰 엔진

1한 줄 정체

open-file-viewer는 "브라우저 안에서 아무 파일이나 미리보기 창을 띄워주는 부품(SDK)"이다. 네가 만드는 웹 앱에 이 라이브러리를 붙이면, 사용자가 올린 .pdf·.docx·.xlsx·.png·.mp4·.zip·.eml·.glb(3D)·.dwg(CAD)·.geojson(지도) 파일을 새 탭으로 나가지 않고 페이지 안 지정된 자리에 그려준다.

기술적으로 정리하면 세 층이다. ① 코어(@open-file-viewer/core) — 순수 DOM만 다루는 프레임워크 무관 엔진. ② 플러그인 20종 — 형식별 렌더링 로직(image / pdf / office / archive / 3d / cad / gis …). ③ 프레임워크 바인딩 3종(react / vue / svelte) — 코어를 각 프레임워크의 컴포넌트로 감싼 얇은 래퍼. 순수 JS만 쓸 거면 바인딩 없이 코어를 직접 부르면 된다.

2왜 주목받는가 — "미리보기"라는 오래된 골칫거리

파일 미리보기는 "쉬워 보이지만 실제로는 지옥"인 대표적 문제다. 웹 브라우저가 기본으로 보여줄 수 있는 건 이미지·영상·PDF 정도뿐이다. 워드·엑셀·PPT·한글 문서·CAD·3D 모델은 브라우저가 전혀 모른다. 그래서 대부분의 서비스는 이렇게 때운다:

• 구글/MS 뷰어에 iframe으로 떠넘기기 — 파일을 외부 서버로 보내야 하고, 사내 문서엔 못 쓴다(보안).
• 서버에서 PDF로 변환 — LibreOffice를 서버에 띄워야 하고 느리고 비싸다.
• 형식마다 라이브러리를 직접 붙이기 — pdf.js, mammoth, SheetJS, three.js… 를 각각 배선하다 프로젝트가 누더기가 된다.

open-file-viewer의 매력은 이 세 번째 길을 한 번만 잘 배선해서 재사용 가능하게 포장했다는 것이다. 게다가 최근 흐름과 정확히 맞물린다:

3기술 스택 전체 지도

모노레포 & 빌드 도구

형식별 렌더링 라이브러리 (핵심 의존성 지도)

이 표가 이 레포의 진짜 알맹이다. "어떤 형식을 무슨 라이브러리로 그리는가"를 한눈에 보여준다. 거의 전부 import()로 지연 로딩된다.

4아키텍처 심화 — 코어·플러그인·프레임워크 바인딩

전체 흐름 한 장

핵심 패턴 ① — "첫 매치가 이긴다" 플러그인 레지스트리

레지스트리라고 하면 복잡한 등록 시스템을 상상하지만, 여기선 그냥 배열을 순서대로 훑는 for 루프다. 놀랍도록 단순하다.

// viewer.ts — 사용자가 준 플러그인 + 항상 마지막에 fallback
const plugins = [...(options.plugins || []), fallbackPlugin()];
const plugin = await findPlugin(plugins, file);

async function findPlugin(plugins, file) {
  for (const plugin of plugins) {
    if (await plugin.match(file)) {   // 이 형식 내가 그릴 수 있어?
      return plugin;                    // 응 → 채택하고 종료
    }
  }
  return fallbackPlugin();               // 아무도 못 그림 → 다운로드 안내
}

핵심 패턴 ② — 플러그인 계약(interface)은 딱 두 가지 질문

플러그인이 지켜야 할 규약은 types.ts에 있고, 요구하는 건 단 둘 — "이 파일 네가 맡을래?(match)"와 "그럼 그려줘(render)"뿐이다.

interface PreviewPlugin {
  name: string;
  match:  (file) => boolean | Promise<boolean>;      // 담당 판별
  render: (ctx)  => PreviewInstance | Promise<…>;      // 실제 그리기
}
interface PreviewInstance {
  resize?:  (size) => void;      // 컨테이너 크기 변하면
  command?: (cmd)  => void;      // 확대·회전 같은 툴바 명령
  destroy:  () => void;         // 정리(메모리 해제)
}

이렇게 계약을 좁게 잡으면 누구나 새 형식 플러그인을 쉽게 추가할 수 있다. "한글(.hwp) 플러그인"을 만들고 싶다면 match에서 확장자를 검사하고 render에서 그려 배열에 끼우면 끝이다.

핵심 패턴 ③ — renderToken으로 "빨리 넘기기" 경쟁 상태 막기

여러 파일을 빠르게 넘길 때 문제가 생긴다. A파일 렌더링(비동기)이 끝나기 전에 사용자가 B로 넘기면, 뒤늦게 끝난 A가 B 위에 덮어 그려버린다. 해결책은 단조 증가 토큰이다.

let renderToken = 0;
async function renderFile(file) {
  const token = ++renderToken;         // 이번 렌더의 번호표
  const instance = await plugin.render(ctx);
  if (destroyed || token !== renderToken) return;  // 번호표 낡음 → 버림
  // 여기 왔으면 "내가 최신" → 화면에 반영
}

핵심 패턴 ④ — 프레임워크 바인딩은 "생성/파괴 3줄"

React·Vue·Svelte 바인딩이 하는 일은 똑같다: ① <div> ref 만들고 ② 마운트되면 createViewer() 호출 ③ 언마운트/prop 변경 시 destroy(). React 예시(툴바 배선 생략):

function FileViewer({ width="100%", height="600px", ...options }) {
  const containerRef = useRef(null);
  const viewerRef = useRef(null);
  useEffect(() => {
    if (!containerRef.current) return;
    viewerRef.current?.destroy();
    viewerRef.current = createViewer({          // ← 코어 호출
      ...options, container: containerRef.current, width, height,
    });
    return () => { viewerRef.current?.destroy(); };  // 정리
  }, [options.file, options.files, width, height /* …모든 prop… */]);
  return <div ref={containerRef} />;             // 코어가 그릴 빈 자리
}

숨은 보석 — 마이크로 프론트엔드 sandbox 버그 우회

이 레포에서 가장 "실전 냄새 나는" 코드가 sandbox-compat.ts다. qiankun·micro-app·wujie 같은 마이크로 프론트엔드 환경에선 zip 기반 미리보기(docx/xlsx/pptx/epub)가 영원히 "로딩 중"에 멈추는 악명 높은 버그가 있다.

5디렉토리 구조 해부

코드 무게중심이 어디인지 줄 수가 말해준다. office.ts가 5,536줄로 압도적이다 — 오피스 문서가 그만큼 지옥이라는 방증이다. 그다음이 asset.ts(3,223), cad.ts(2,714). 테스트도 두껍다 — render-smoke.test.ts가 5,900줄로, "형식별로 실제 렌더가 깨지지 않는가"를 집요하게 검증한다.

6학습 포인트 — 기술별 배울 것

실습 아이디어 (짧게)

• examples/vanilla를 띄우고 아무 파일이나 드래그해 어떤 플러그인이 잡는지 콘솔로 추적해 보기.
• plugins/image.ts를 복사해 나만의 형식 플러그인(예: .log를 색칠해 보여주기)을 하나 추가.
• 네트워크 탭을 열고 3D 파일을 열 때 three 청크가 그제서야 다운로드되는지 확인.

7시스템 / 브라우저 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

10핵심 키워드 사전

11참고 링크

• GitHub: github.com/xushanpei/open-file-viewer — 소스·README(한국어 README.ko.md 포함)
• 문서/데모 사이트: 저장소 doc/ 앱 (Vite로 로컬 실행 pnpm dev:doc)
• npm: @open-file-viewer/core, /react, /vue, /svelte (v0.1.32)
• 핵심 렌더링 라이브러리 문서: pdf.js, SheetJS(xlsx), mammoth, three.js, DOMPurify, JSZip
• 배경 지식: 마이크로 프론트엔드 qiankun