BuilderIO/mitosis 딥다이브
— "한 번 짜면 모든 프레임워크로 컴파일되는" 컴포넌트 컴파일러

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

Mitosis(@builder.io/mitosis)는 Builder.io가 만든 컴포넌트 컴파일러다. 개발자는 React와 매우 비슷한 문법(JSX + 훅)으로 컴포넌트를 .lite.tsx 확장자 파일에 작성한다. 그러면 Mitosis가 이를 분석해 Mitosis JSON이라는 프레임워크 중립 트리로 바꾸고, 선택한 타깃마다 별도의 제너레이터가 그 트리를 진짜 React·Vue·Angular·Svelte·Solid·Qwik 코드로 뽑아낸다.

핵심은 "한 번 쓰고, 어디서나 실행(write once, run everywhere)"인데, 웹 컴포넌트(Web Components)처럼 런타임 추상화 레이어를 끼우는 방식과는 정반대다. Mitosis는 컴파일이 끝나면 자기 흔적을 남기지 않는다. 그래서 각 팀은 자기 프레임워크의 표준 코드를 받아 그대로 쓰고 트리쉐이킹·최적화도 정상적으로 누린다. 대표 활용처는 디자인 시스템(여러 프레임워크에 같은 UI를 배포)과 Figma → 코드 동기화다.

2왜 주목받는가

트렌딩 이유 · 경쟁 접근 대비 장점.

2026년 현재 프런트엔드 생태계는 React 천하가 아니다. Vue·Svelte·Solid·Qwik·Angular가 각자 자리를 지키고, 한 회사 안에서도 팀마다 다른 프레임워크를 쓴다. 이 "프레임워크 파편화" 속에서 같은 UI를 여러 번 만드는 비용이 커졌고, Mitosis는 그 통증을 정확히 겨냥한다. 단순 인기가 아니라 ★13.8k · 253개 릴리스 · 1,898 커밋으로 오래 다져진 성숙한 프로젝트라는 점이 신뢰를 준다. 차별점은 넷이다.

3기술 스택 전체 지도

컴파일러 코어 / 입력(파서) / 출력(제너레이터) / 모노레포 운영의 4축으로 본다.

Mitosis는 서버·DB가 있는 웹앱이 아니라 개발자 도구(컴파일러)다. 그래서 "백/프론트/인프라" 대신 컴파일러 파이프라인 + 모노레포 운영 관점으로 스택을 그리는 게 정확하다.

① 컴파일러 코어 — @builder.io/mitosis (packages/core)

② 입력(파서) — 무엇을 받아들이나

packages/core/src/parsers/에 입력 파서가 있다. 기본은 JSX 파서(parsers/jsx)이고, 그 외 angular.ts·svelte/·builder/·context.ts가 있다. 즉 React식 JSX뿐 아니라 Angular·Svelte·Builder.io 콘텐츠도 "원본"으로 삼아 Mitosis JSON으로 끌어올 수 있다. 설정에서 parser를 직접 넣어 커스텀 입력 형식을 만들 수도 있다.

③ 출력(제너레이터) — 어디로 내보내나

핵심 자산. packages/core/src/generators/ 하위에 타깃별 폴더 21개가 있고, 각각 componentToReact·componentToVue처럼 "Mitosis JSON → 문자열 코드"를 만드는 함수를 export 한다. 이들을 한데 모은 게 targets.ts다.

// packages/core/src/targets.ts — 타깃 레지스트리(요약)
export const targets = {
  alpine, angular, customElement, html, mitosis, liquid,
  react, reactNative, solid, svelte, swift, template,
  webcomponent, vue, stencil, qwik, marko, preact, lit,
  rsc, taro,
} as const;
export type Targets = keyof typeof targets;

④ 모노레포 운영 — Yarn 4 + Nx

저장소 전체는 Yarn 4 워크스페이스 + Nx(빌드 캐시·태스크 오케스트레이션)로 묶인 모노레포다. package.json의 workspaces에 packages/*·e2e/*·examples/**가 등록돼 있고, 릴리스는 @changesets/cli로 버전·체인지로그를 관리한다.

4아키텍처 심화 분석

파싱 → IR → 제너레이트, 그리고 그 사이에 끼는 플러그인.

4-1. 3단 파이프라인 (컴파일러의 정석)

Mitosis는 거의 모든 컴파일러가 쓰는 "앞단(parse) → 가운데(IR) → 뒷단(generate)" 구조다. 가운데의 프레임워크 중립 IR이 핵심 — 입력이 N개, 출력이 M개여도 N×M개의 변환기를 짤 필요 없이 N+M개만 있으면 된다.

입력 형식이 늘어도 IR만 잘 채우면 21개 출력이 공짜로 따라오고, 새 프레임워크 타깃을 추가할 때도 제너레이터 하나만 더 쓰면 된다. 이게 "한 번 쓰고 어디서나"가 가능한 구조적 이유다.

4-2. IR의 실제 모양 — MitosisComponent / MitosisNode

IR이 추상적으로 들리면, 실제 타입을 보면 분명해진다. 컴포넌트는 메타데이터 + 노드 트리로 쪼개진다.

// types/mitosis-component.ts (요약) — 컴포넌트 = 메타+상태+훅+트리
interface MitosisComponent {
  name: string;
  imports: MitosisImport[];        // 어떤 모듈을 import 했나
  state: MitosisState;             // useStore/useState → 상태 맵
  hooks: { onMount, onUpdate, ... }; // 라이프사이클
  children: MitosisNode[];         // JSX 트리(렌더 결과)
  context: { get, set };           // useContext/setContext
  props?, refs?, meta? ...
}

// types/mitosis-node.ts (요약) — 노드 = 이름+속성+바인딩+자식
type MitosisNode = {
  '@type': '@builder.io/mitosis/node';
  name: string;                    // 'div', 'Show', 컴포넌트명…
  properties: { [k: string]: string };  // 정적 속성(class="x")
  bindings: { [k: string]: Binding };   // 동적 바인딩(checked={...})
  children: MitosisNode[];
};

여기서 properties(정적)와 bindings(동적)를 나눈 게 영리하다. class="view"는 properties로, checked={props.todo.completed}는 bindings로 들어간다. 제너레이터는 이 구분을 보고 React는 checked={...}, Vue는 :checked="...", Angular는 [checked]="..."처럼 각 프레임워크의 바인딩 문법으로 번역한다.

4-3. 입력 예시 한 컷 — 진짜 .lite.tsx

레포의 examples/todo에 있는 실제 컴포넌트(요약). React를 닮았지만 상태는 useStore, 조건부는 <Show>로 쓴다 — 이 "Mitosis 사투리"가 모든 타깃으로 번역 가능한 최소 공통 문법이다.

// examples/todo/src/components/todo.lite.tsx (요약)
import { Show, useStore } from '@builder.io/mitosis';

export default function Todo(props) {
  const state = useStore({
    editing: false,
    toggle() { props.todo.completed = !props.todo.completed; },
  });
  return (
    <li>
      <input type="checkbox" checked={props.todo.completed}
             onClick={() => state.toggle()} />
      <label onDblClick={() => { state.editing = true; }}>
        {props.todo.text}
      </label>
      <Show when={state.editing}>
        <input class="edit" value={props.todo.text} />
      </Show>
    </li>
  );
}

4-4. 핵심 설계 패턴 3가지

5디렉토리 구조 해부

모노레포 → 컴파일러 코어 → 그 안의 핵심 3폴더 순으로 좁혀 본다.

5-1. 저장소 전체

5-2. 컴파일러 코어 packages/core/src/

읽는 순서를 추천하면 ① types/(IR이 무엇인가) → ② parsers/jsx/(입력을 어떻게 IR로 채우나) → ③ generators/react/(IR을 어떻게 코드로 푸나). 이 셋만 따라가면 컴파일러 전체 그림이 잡힌다.

5-3. 입력 파서 parsers/jsx/ 내부

파서가 "통짜 함수" 하나가 아니라 관심사별로 쪼개진 게 학습 포인트다 — 컴포넌트의 각 부분을 따로 읽는다.

6학습 포인트 (기술별)

이 레포 하나로 "컴파일러 + 멀티 프레임워크 + 모노레포"를 동시에 챙긴다.

① 컴파일러 사고법 — parse / IR / generate

가장 값진 배움. 입력 N개·출력 M개를 N×M이 아니라 N+M으로 푸는 "중간 표현(IR)" 발상은 Babel·SWC·LLVM·Svelte까지 관통하는 핵심 아이디어다. Mitosis는 이걸 친숙한 "컴포넌트"라는 소재로 보여줘서 입문용으로 최적이다.

② 프레임워크들의 공통점과 차이

같은 IR이 React·Vue·Svelte·Solid·Angular 코드로 어떻게 다르게 풀리는지 비교하면, 각 프레임워크의 반응성 모델이 선명해진다. useStore가 React에선 useState, Vue에선 ref, Svelte에선 그냥 변수가 되는 걸 보면 "상태 관리란 결국 같은 문제의 다른 해법"임이 보인다.

③ "번역 가능한 부분집합" 설계 — 제약이 곧 힘

왜 .map() 대신 <For>, && 대신 <Show>를 강제할까? 자유로운 JS는 번역 불가능하기 때문이다. eslint-plugin이 이 제약을 강제한다. "표현력을 일부러 줄여서 이식성을 얻는" 설계 트레이드오프를 체험할 수 있다.

// mitosis.config.js — 컴파일 설정의 뼈대(요약)
module.exports = {
  files: 'src/**',
  targets: ['react', 'vue', 'svelte', 'solid', 'qwik'],
  dest: 'output',
  options: {
    react: { stylesType: 'styled-jsx', stateType: 'hooks' },
    vue:   { api: 'composition' },
  },
};

④ 모노레포 + Nx + Changesets 운영

core·cli·docs·e2e가 한 저장소에서 어떻게 의존하고, Nx가 nx run-many로 바뀐 패키지만 빌드/테스트하며, Changesets가 릴리스를 자동화하는지를 실물로 본다. 실제 OSS 운영을 배우는 좋은 교본이다.

⑤ 스냅샷 테스트로 "출력 고정"

__tests__/의 스냅샷은 "이 입력 → 정확히 이 React 코드"를 박제한다. 제너레이터를 고칠 때 의도치 않은 출력 변화를 즉시 잡아내는 컴파일러 회귀 테스트의 정석이다.

7시스템 요구사항 & 설치

서버·DB 없음 — Node 환경이면 끝. 빌드 타임 도구다.

새 프로젝트로 시작

# 대화형 스캐폴딩(starter 패키지가 생성)
npm create @builder.io/mitosis@latest

# 생성된 폴더에서 — 컴포넌트를 모든 타깃으로 컴파일
npm run build       # 내부적으로 mitosis build 실행

기존 프로젝트에 추가

npm i -D @builder.io/mitosis-cli @builder.io/mitosis

# mitosis.config.js를 만든 뒤
npx mitosis build            # config의 targets로 일괄 컴파일
npx mitosis compile -t=vue ./Button.lite.tsx  # 단일 파일 → Vue

CLI 커맨드는 packages/cli/src/commands/에 build.ts(설정 기반 일괄 빌드)·compile.ts(단일 파일 변환)·new.ts(스캐폴딩) 셋으로 단순하게 나뉜다. 브라우저에서 빠르게 감을 잡고 싶으면 설치 없이 플레이그라운드를 쓰면 된다.

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

읽기만 말고, 난이도순으로 손을 움직여 보자.

9관련 기술 심화 학습 로드맵

4주 코스 — 컴파일러 개념과 프레임워크 비교를 번갈아 다진다.

10핵심 키워드 사전

이 레포를 읽다 마주치는 용어들.

11참고 링크

원본과 더 깊이 파고들 자료.

프로젝트 원본

· GitHub 저장소: github.com/BuilderIO/mitosis
· 공식 문서: mitosis.builder.io/docs
· 플레이그라운드: mitosis.builder.io/playground
· npm 패키지: @builder.io/mitosis, @builder.io/mitosis-cli

코드 안에서 먼저 볼 곳

· IR 타입: packages/core/src/types/mitosis-component.ts, mitosis-node.ts
· 타깃 레지스트리: packages/core/src/targets.ts
· 기본 파서: packages/core/src/parsers/jsx/ · 제너레이터: packages/core/src/generators/react/
· 실제 예제: examples/todo/src/components/todo.lite.tsx

배경 지식

· Figma 연동: mitosis.builder.io/docs/figma
· 컴파일러 개념 실습: astexplorer.net (JSX를 AST로 보는 도구)
· Discord 커뮤니티 / 기여 가이드: 레포 CONTRIBUTING.md