debug-time-machine/README.md

제로 설정 React 디버깅 도구

# 🕰️ Debug Time Machine

완전 통합된 React 디버깅 시간여행 도구 - 제로 설정으로 바로 사용!

## ✨ 특징

- 🚀 **제로 설정**: 설치 후 바로 사용 가능
- 🔌 **자동 연결**: 서버 자동 감지 및 연결
- 📡 **실시간 모니터링**: WebSocket을 통한 실시간 이벤트 캡처
- 🐛 **올인원 솔루션**: 하나의 패키지로 모든 기능 제공

## 🚀 빠른 시작

### 1. 설치

```bash
npm install debug-time-machine
```

### 2. 서버 시작 (별도 터미널)

```bash
debug-time-machine start
```

이 명령은 다음을 자동으로 시작합니다:
- 백엔드 서버 (localhost:4000)
- Debug UI (localhost:8080) 
- 브라우저에서 localhost:8080 자동 열림

### 3. React 앱에서 Hook 사용

```jsx
import { useDebugTimeMachine } from 'debug-time-machine';

function App() {
  useDebugTimeMachine(); // localhost:4000에 자동 연결
  return <YourApp />;
}
```

그게 전부입니다! 🎉

## 📖 자세한 사용법

### 기본 사용법

```jsx
import { useDebugTimeMachine } from 'debug-time-machine';

function MyComponent() {
  const debug = useDebugTimeMachine({
    // 모든 옵션은 선택사항입니다
    debugMode: true,
    captureUserActions: true,
    captureErrors: true,
    captureStateChanges: true,
  });

  return (
    <div>
      <p>연결 상태: {debug.isConnected ? '연결됨' : '연결 안됨'}</p>
      <p>클라이언트 ID: {debug.clientId}</p>
      {/* 여러분의 앱 코드 */}
    </div>
  );
}
```

### 수동 이벤트 캡처

```jsx
function MyComponent() {
  const { captureError, captureStateChange } = useDebugTimeMachine();

  const handleButtonClick = () => {
    try {
      // 어떤 작업
    } catch (error) {
      captureError(error);
    }
  };

  const handleStateChange = (newState) => {
    captureStateChange('MyComponent', oldState, newState);
  };

  return <button onClick={handleButtonClick}>클릭</button>;
}
```

## 🛠️ CLI 명령어

### 서버 시작

```bash
debug-time-machine start
```

또는 간단히:

```bash
debug-time-machine
```

### 도움말

```bash
debug-time-machine --help
```

## 🔧 설정 옵션

```jsx
const config = {
  websocketUrl: 'ws://localhost:4000/ws',    // WebSocket 서버 URL
  debugMode: false,                          // 디버그 로그 출력
  captureUserActions: true,                  // 사용자 액션 캡처
  captureErrors: true,                       // 에러 캡처
  captureStateChanges: true,                 // 상태 변경 캡처
  maxReconnectAttempts: 5,                   // 최대 재연결 시도
  reconnectInterval: 5000,                   // 재연결 간격 (ms)
  autoConnect: true,                         // 자동 연결
};

useDebugTimeMachine(config);
```

## 🌐 포트 정보

- **백엔드 서버**: `http://localhost:4000`
- **Debug UI**: `http://localhost:8080`
- **WebSocket**: `ws://localhost:4000/ws`

## 🔍 캡처되는 이벤트

- ✅ 사용자 클릭, 입력, 폼 제출
- ✅ JavaScript 에러 및 Promise rejection
- ✅ React 상태 변경
- ✅ 네트워크 요청 (선택적)
- ✅ 컴포넌트 생명주기

## 🚨 문제 해결

### 연결이 안 될 때

1. 서버가 실행 중인지 확인:
   ```bash
   curl http://localhost:4000/health
   ```

2. 포트가 사용 중인지 확인:
   ```bash
   lsof -i :4000
   lsof -i :8080
   ```

3. 방화벽 설정 확인

### 이벤트가 캡처되지 않을 때

1. Hook이 올바르게 사용되고 있는지 확인
2. `debugMode: true`로 설정하여 로그 확인
3. 브라우저 개발자 도구에서 WebSocket 연결 상태 확인

## 📦 기술 스택

- **Frontend**: React, WebSocket
- **Backend**: Express.js, WebSocket (ws)
- **Build**: TypeScript, tsup
- **Packaging**: 통합 NPM 패키지

## 🤝 기여

이슈나 기능 요청은 [GitHub Issues](https://github.com/amenooto/debugTimeMachine/issues)에서 해주세요.

## 📄 라이선스

MIT License

---

**Debug Time Machine**으로 더 나은 React 디버깅 경험을 시작하세요! 🚀