react-ui-diff

React 컴포넌트의 UI 변경 사항을 시각적으로 비교하는 도구

이런 상황에서 사용하세요

"개발자가 코드를 수정했는데, UI에 뭐가 달라진 거죠?"

디자이너와 개발자가 협업할 때 흔히 겪는 문제들:

• 개발자가 "버튼 색상 수정했습니다"라고 하는데, 다른 곳도 같이 바뀐 건 아닌지 확인하고 싶을 때
• PR 리뷰에서 코드 diff는 보이지만, 실제 화면이 어떻게 달라졌는지 알 수 없을 때
• 컴포넌트를 리팩토링했는데, 의도치 않게 스타일이 깨진 곳이 없는지 확인하고 싶을 때
• 디자인 토큰(색상, 폰트 크기 등)을 변경했는데, 영향받는 컴포넌트 전체를 한눈에 보고 싶을 때

react-ui-diff가 해결해 주는 것

이전 버전과 현재 버전의 React 컴포넌트를 실제로 렌더링하여 나란히 비교합니다. 스크린샷이 아니라 실제 컴포넌트를 띄우기 때문에 호버, 클릭 같은 인터랙션 상태까지 확인할 수 있습니다.

변경된 부분에는 자동으로 색상 하이라이트가 표시됩니다:

| 색상 | 의미 | |------|------| | 노란색 (amber) | 스타일이 변경된 요소 (색상, 간격, 폰트 등) | | 초록색 (green) | 새로 추가된 요소 | | 빨간색 (red) | 삭제된 요소 | | 파란색 (blue) | props(속성)가 변경된 요소 |

비교 모드

Slider 모드 (기본)

좌우로 드래그하여 이전/이후를 비교합니다. Figma의 오버레이 비교와 유사한 방식입니다.

┌─────────────┬─────────────┐
│   Before    │▌   After    │
│             │▌             │
│  (이전 UI)  │▌ (현재 UI)  │
│             │▌             │
└─────────────┴─────────────┘
              ↕ 드래그

Side by Side 모드

이전과 이후를 나란히 배치하여 동시에 비교합니다.

┌─────────────┐ ┌─────────────┐
│   Before    │ │    After    │
│             │ │             │
│  (이전 UI)  │ │ (현재 UI)  │
│             │ │             │
└─────────────┘ └─────────────┘

Blink 모드

이전과 이후를 일정 간격으로 번갈아 보여줍니다. 미세한 변경 사항을 발견하기에 가장 효과적입니다.

┌─────────────┐      ┌─────────────┐
│   Before    │ ──→  │    After    │ ──→ (반복)
│  (깜빡)     │      │  (깜빡)     │
└─────────────┘      └─────────────┘

설치 방법

사전 준비

아래 도구들이 컴퓨터에 설치되어 있어야 합니다. 터미널(맥: Terminal, 윈도우: PowerShell)을 열어 확인하세요.

1. Node.js (18 이상)

node --version

v18.x.x 이상이 출력되면 됩니다. 설치가 안 되어 있다면 nodejs.org에서 LTS 버전을 다운로드하세요.

2. Git

git --version

버전 정보가 출력되면 됩니다. 설치가 안 되어 있다면 git-scm.com에서 다운로드하세요.

패키지 설치

프로젝트 폴더에서 터미널을 열고 아래 명령어를 실행하세요.

# 1. CLI 도구 설치 (개발 의존성)
npm install --save-dev @react-ui-diff/cli

# 2. UI 컴포넌트 설치 (개발 의존성)
npm install --save-dev @react-ui-diff/ui

Storybook을 사용하고 있다면 애드온도 함께 설치하세요:

npm install --save-dev @react-ui-diff/storybook

초기 설정

프로젝트 루트에서 아래 명령어를 실행하면 설정 파일이 생성됩니다:

npx react-ui-diff init

.uidiffrc.json 파일이 생성됩니다. 기본 설정으로 바로 사용할 수 있지만, 필요하다면 아래와 같이 수정할 수 있습니다:

{
  "baseCommit": "HEAD~1",              // 비교 기준 (직전 커밋)
  "include": ["src/**/*.tsx", "src/**/*.jsx"],  // 비교할 파일 범위
  "exclude": ["**/*.test.*", "**/*.spec.*", "**/*.stories.*"],  // 제외할 파일
  "port": 4400,                         // 비교 서버 포트
  "theme": {
    "styleChange": "#FFD700",           // 스타일 변경 하이라이트 색상
    "added": "#4CAF50",                 // 추가된 요소 색상
    "removed": "#F44336",              // 삭제된 요소 색상
    "propsChange": "#2196F3"           // props 변경 색상
  }
}

사용 방법

방법 1: CLI로 빠르게 확인하기 (가장 간단)

터미널에서 3단계로 확인할 수 있습니다.

Step 1. 빌드

npx react-ui-diff build

이 명령어는 자동으로:

1. Git에서 변경된 컴포넌트 파일을 찾고
2. 이전 커밋의 컴포넌트를 빌드하고
3. 현재 상태의 컴포넌트를 빌드합니다

특정 커밋과 비교하고 싶다면:

npx react-ui-diff build --base main
npx react-ui-diff build --base abc1234

Step 2. 서버 실행

npx react-ui-diff serve

Step 3. 브라우저에서 확인

브라우저에서 http://localhost:4400을 엽니다. 변경된 컴포넌트들의 이전/이후를 시각적으로 비교할 수 있습니다.

방법 2: 터미널에서 바로 결과 확인하기

서버를 띄우지 않고 터미널에서 바로 변경 사항 요약을 확인할 수 있습니다:

# 직전 커밋과 비교
npx react-ui-diff diff

# 특정 커밋과 비교
npx react-ui-diff diff --commit abc1234

# JSON 형식으로 출력 (CI/CD 연동 시 유용)
npx react-ui-diff diff --json

방법 3: React 앱에 직접 통합하기

개발 중인 앱에 비교 UI를 바로 얹을 수 있습니다.

// App.tsx
import { DiffProvider, DiffOverlay } from '@react-ui-diff/ui';
import '@react-ui-diff/ui/styles.css';

function App() {
  return (
    // enabled={process.env.NODE_ENV === 'development'} 로 개발 환경에서만 활성화
    <DiffProvider
      mode="slider"
      enabled={process.env.NODE_ENV === 'development'}
    >
      <DiffOverlay showDiffPanel>
        <YourApp />
      </DiffOverlay>
    </DiffProvider>
  );
}

화면 하단에 모드 전환 버튼이 나타나고, 우측에 변경 사항 패널이 표시됩니다.

방법 4: Storybook에서 확인하기

Storybook을 사용하고 있다면, 각 스토리에서 바로 비교할 수 있습니다.

1단계. 애드온 등록

.storybook/main.ts:

export default {
  addons: [
    // ... 기존 애드온들
    '@react-ui-diff/storybook',
  ],
};

2단계. 스토리에서 활성화

// Button.stories.tsx
export default {
  title: 'Components/Button',
  parameters: {
    uiDiff: {
      enabled: true,
      mode: 'slider',  // 'slider' | 'side-by-side' | 'blink'
    },
  },
};

Storybook 하단 패널에 "UI Diff" 탭이 추가되어 변경 사항을 확인할 수 있습니다.

자주 사용하는 시나리오

시나리오 1: "이번 커밋에서 뭐가 바뀌었나요?"

npx react-ui-diff build && npx react-ui-diff serve

브라우저에서 확인하세요. 변경된 컴포넌트 목록과 구체적인 스타일 변경 내역이 표시됩니다.

시나리오 2: "main 브랜치 대비 변경 사항을 보고 싶어요"

npx react-ui-diff build --base main
npx react-ui-diff serve

시나리오 3: "특정 커밋과 비교하고 싶어요"

# 커밋 해시를 지정하여 비교
npx react-ui-diff build --base a1b2c3d
npx react-ui-diff serve

시나리오 4: "디자인 토큰 변경 영향도를 파악하고 싶어요"

디자인 토큰(CSS 변수)을 변경한 후:

npx react-ui-diff diff

변경된 CSS 변수와 영향받는 컴포넌트 목록이 출력됩니다.

시나리오 5: "PR 리뷰에 변경 사항을 첨부하고 싶어요"

npx react-ui-diff diff --json > diff-report.json

JSON 리포트를 생성하여 PR 코멘트에 첨부할 수 있습니다.

npm scripts 등록 (선택)

매번 긴 명령어를 입력하기 번거롭다면, package.json에 스크립트를 등록하세요:

{
  "scripts": {
    "ui-diff": "react-ui-diff build && react-ui-diff serve",
    "ui-diff:build": "react-ui-diff build",
    "ui-diff:serve": "react-ui-diff serve",
    "ui-diff:report": "react-ui-diff diff --json"
  }
}

이후에는 이렇게만 실행하면 됩니다:

npm run ui-diff

설정 파일 상세 (.uidiffrc.json)

| 필드 | 타입 | 기본값 | 설명 | |------|------|--------|------| | baseCommit | string | "HEAD~1" | 비교 기준 커밋. "HEAD~1"은 직전 커밋, "main"은 main 브랜치 | | include | string[] | ["src/**/*.tsx", "src/**/*.jsx"] | 비교 대상에 포함할 파일 패턴 | | exclude | string[] | ["**/*.test.*", "**/*.spec.*", "**/*.stories.*"] | 비교에서 제외할 파일 패턴 | | port | number | 4400 | 비교 서버의 포트 번호 | | buildCommand | string | "npm run build" | 컴포넌트 빌드 명령어 | | storybook | boolean | false | Storybook 연동 여부 | | theme | object | 아래 참조 | 하이라이트 색상 설정 | | watchStyles | string[] | [] | 감시할 CSS 속성 목록 (빈 배열이면 전체) |

theme 설정

{
  "theme": {
    "styleChange": "#FFD700",  // 스타일 변경: 노란색 (amber)
    "added": "#4CAF50",        // 추가: 초록색
    "removed": "#F44336",      // 삭제: 빨간색
    "propsChange": "#2196F3"   // Props 변경: 파란색
  }
}

브랜드 컬러에 맞게 변경할 수 있습니다.

변경 감지 항목

스타일 변경 감지

react-ui-diff는 렌더링된 컴포넌트의 computed style을 비교하여 다음 항목의 변경을 감지합니다:

| 카테고리 | 감지하는 속성들 | |----------|----------------| | 색상 | color, background-color, border-color, box-shadow, outline-color | | 타이포그래피 | font-family, font-size, font-weight, font-style, line-height, letter-spacing, text-align | | 간격 | margin (상하좌우), padding (상하좌우), gap, row-gap, column-gap | | 레이아웃 | width, height, min/max-width/height, display, position, flex 관련, grid 관련 | | 시각 | border-radius, opacity, transform, transition, border-width, cursor |

Props 변경 감지

컴포넌트의 기본 props 값 변경을 추적합니다:

// Before
function Button({ size = 'small', color = 'blue' }) { ... }

// After
function Button({ size = 'large', color = 'blue', disabled = false }) { ... }

// 감지 결과:
// - size: 'small' → 'large' (변경)
// - disabled: undefined → false (추가)

디자인 토큰 변경 감지

CSS 커스텀 프로퍼티(변수) 변경을 추적합니다:

/* Before */
:root {
  --color-primary: #3b82f6;
  --spacing-sm: 8px;
}

/* After */
:root {
  --color-primary: #ef4444;    /* 변경 감지 */
  --spacing-sm: 8px;
  --spacing-md: 16px;          /* 추가 감지 */
}

React 컴포넌트 API

<DiffProvider>

diff 기능의 최상위 Provider. 앱 전체 또는 비교하려는 영역을 감싸세요.

| Prop | 타입 | 기본값 | 설명 | |------|------|--------|------| | mode | 'slider' \| 'blink' \| 'side-by-side' | 'slider' | 비교 모드 | | enabled | boolean | true | 활성화 여부. false이면 children만 그대로 렌더링 | | baseCommit | string | - | 비교 기준 커밋 (선택) | | highlightStyle | 'overlay' \| 'outline' | 'overlay' | 하이라이트 스타일 | | serverUrl | string | 'http://localhost:4400/api/diff' | diff 데이터 API URL |

<DiffOverlay>

비교 UI를 렌더링하는 오버레이 컴포넌트.

| Prop | 타입 | 기본값 | 설명 | |------|------|--------|------| | component | string | - | 특정 컴포넌트만 필터링 (선택) | | page | string | - | 페이지 단위 비교 (선택) | | showDiffPanel | boolean | true | 우측 변경 사항 패널 표시 여부 |

<DiffPanel>

변경 사항을 구조화된 목록으로 보여주는 사이드 패널.

| Prop | 타입 | 기본값 | 설명 | |------|------|--------|------| | files | DiffFile[] | (필수) | 변경된 파일 목록 | | onClose | () => void | - | 패널 닫기 콜백 |

Hooks

// 현재 diff 상태 가져오기
const { mode, setMode, diffResult, loading, error } = useDiff();

// 특정 엘리먼트의 스타일 변경 목록
const styleChanges = useStyleDiff(elementRef);

// 특정 컴포넌트의 props 변경 목록
const propsChanges = usePropsDiff('src/components/Button.tsx');

// before/after 컴포넌트 로더
const { beforeComponent, afterComponent, loading } = useBundleLoader('src/components/Button.tsx');

// blink 모드 타이머 (true/false 토글)
const showBefore = useBlinkTimer(1000);  // 1초 간격

CLI 명령어 요약

| 명령어 | 설명 | |--------|------| | npx react-ui-diff init | 설정 파일(.uidiffrc.json) 생성 | | npx react-ui-diff build | 이전/현재 컴포넌트 빌드 | | npx react-ui-diff build --base <commit> | 특정 커밋 기준으로 빌드 | | npx react-ui-diff build --output <dir> | 출력 디렉토리 지정 | | npx react-ui-diff serve | 비교 UI 서버 실행 (기본 포트 4400) | | npx react-ui-diff serve --port <number> | 포트 지정하여 서버 실행 | | npx react-ui-diff diff | 변경 사항 분석 결과 출력 | | npx react-ui-diff diff --commit <hash> | 특정 커밋과 비교 | | npx react-ui-diff diff --json | JSON 형식으로 출력 |

문제 해결

"command not found: react-ui-diff"

npx를 붙여서 실행하세요:

npx react-ui-diff build

또는 전역으로 설치하세요:

npm install -g @react-ui-diff/cli

"No component changes detected"

• .uidiffrc.json의 include 패턴이 실제 파일 경로와 맞는지 확인하세요
• 변경된 파일이 .tsx 또는 .jsx 확장자인지 확인하세요
• Git에 커밋 기록이 있는지 확인하세요 (git log로 확인)

"포트 4400이 이미 사용 중입니다"

다른 포트를 지정하세요:

npx react-ui-diff serve --port 4401

또는 .uidiffrc.json에서 포트를 변경하세요:

{
  "port": 4401
}

"Git stash 관련 에러"

빌드 중 에러가 발생하면 Git 상태가 자동 복원됩니다. 만약 복원이 안 되었다면:

git stash pop   # 보관된 변경 사항 복원

패키지 구성

| 패키지 | 이름 | 용도 | |--------|------|------| | @react-ui-diff/core | 핵심 엔진 | diff 알고리즘, Git 조작, 설정 관리 | | @react-ui-diff/ui | UI 컴포넌트 | 비교 오버레이, 하이라이트, 패널 | | @react-ui-diff/cli | CLI 도구 | 빌드 자동화, dev 서버 | | @react-ui-diff/storybook | Storybook 애드온 | Storybook 통합 |

요구 사항

• Node.js 18 이상
• React 18 이상
• Git
• 프로젝트가 Git 저장소로 관리되고 있어야 합니다

라이선스

MIT