debug-time-machine-react-client/README.md

🕰️ 완전 자동화된 React 디버깅 라이브러리 - 설치하고 바로 사용하세요!

# debug-time-machine-react-client

React 앱에서 Debug Time Machine을 쉽게 사용할 수 있는 React Hook 패키지입니다.

## 설치

```bash
npm install debug-time-machine-react-client
# 또는
yarn add debug-time-machine-react-client
# 또는
pnpm add debug-time-machine-react-client
```

## 사용법

### 기본 사용법

```tsx
import { useDebugTimeMachine } from 'debug-time-machine-react-client';

function App() {
  const { isConnected, clientId } = useDebugTimeMachine();
  
  return (
    <div>
      {isConnected ? (
        <p>✅ Time Machine connected! Client ID: {clientId}</p>
      ) : (
        <p>🔄 Connecting to Time Machine...</p>
      )}
      
      <YourAppContent />
    </div>
  );
}
```

### 고급 설정

```tsx
import { useDebugTimeMachine } from 'debug-time-machine-react-client';

function App() {
  const timeMachine = useDebugTimeMachine({
    websocketUrl: 'ws://localhost:3001/ws',
    debugMode: true,
    captureUserActions: true,
    captureErrors: true,
    captureStateChanges: true,
    maxReconnectAttempts: 5,
    reconnectInterval: 3000,
    developmentOnly: true,
  });
  
  // 수동으로 상태 변경 캡처
  const handleStateChange = () => {
    timeMachine.captureStateChange(
      'MyComponent',
      { count: 0 },
      { count: 1 },
      { userId: 123 }
    );
  };
  
  // 수동으로 에러 캡처
  const handleError = () => {
    try {
      throw new Error('Something went wrong!');
    } catch (error) {
      timeMachine.captureError(error, { context: 'user action' });
    }
  };
  
  return (
    <div>
      <h1>Debug Time Machine Demo</h1>
      
      <div>
        <p>연결 상태: {timeMachine.isConnected ? '✅ 연결됨' : '❌ 연결 안됨'}</p>
        <p>클라이언트 ID: {timeMachine.clientId || 'N/A'}</p>
        <p>재연결 시도: {timeMachine.connectionInfo.reconnectAttempts}</p>
        {timeMachine.connectionInfo.lastError && (
          <p>마지막 에러: {timeMachine.connectionInfo.lastError}</p>
        )}
      </div>
      
      <div>
        <button onClick={handleStateChange}>상태 변경 캡처</button>
        <button onClick={handleError}>에러 캡처</button>
        <button onClick={timeMachine.reconnect}>수동 재연결</button>
      </div>
    </div>
  );
}
```

## API

### `useDebugTimeMachine(config?)`

Debug Time Machine 서버와 연결하고 이벤트 캡처를 자동으로 설정하는 React Hook입니다.

#### Parameters

- `config?`: `DebugTimeMachineConfig` - 옵션 설정 객체

#### Returns

`DebugTimeMachineHookReturn` 객체:

- `isConnected: boolean` - 서버 연결 상태
- `clientId: string | null` - 서버에서 할당받은 클라이언트 ID
- `reconnect: () => void` - 수동 재연결 함수
- `sendMessage: (type: string, data: any) => boolean` - 커스텀 메시지 전송
- `captureError: (error: Error, errorInfo?: any) => void` - 수동 에러 캡처
- `captureStateChange: (componentName: string, prevState: any, newState: any, props?: any) => void` - 수동 상태 변경 캡처
- `connectionInfo` - 연결 정보 객체

### Configuration

#### `DebugTimeMachineConfig`

```typescript
interface DebugTimeMachineConfig {
  websocketUrl?: string;          // 기본값: 'ws://localhost:3001/ws'
  debugMode?: boolean;            // 기본값: development 환경에서 true
  captureUserActions?: boolean;   // 기본값: true
  captureErrors?: boolean;        // 기본값: true
  captureStateChanges?: boolean;  // 기본값: true
  maxReconnectAttempts?: number;  // 기본값: 10
  reconnectInterval?: number;     // 기본값: 5000 (ms)
  developmentOnly?: boolean;      // 기본값: true
}
```

## 자동 캡처 기능

### 사용자 상호작용 캡처

다음 이벤트들이 자동으로 캡처됩니다:
- 클릭 (`click`)
- 입력 (`input`, `change`)
- 폼 제출 (`submit`)
- 키보드 입력 (`keydown`)
- 포커스 변경 (`focus`, `blur`)

### 에러 캡처

다음 에러들이 자동으로 캡처됩니다:
- JavaScript 런타임 에러
- Promise rejection
- Console.error 호출

### 환경별 동작

- **Development**: 모든 기능 활성화, 콘솔 로그 출력
- **Production**: `developmentOnly: true`인 경우 자동 비활성화

## 서버 설정

Debug Time Machine 백엔드 서버가 실행되어 있어야 합니다:

```bash
cd apps/backend
npm run dev
```

서버는 기본적으로 `http://localhost:3001`에서 실행되며, WebSocket은 `/ws` 경로에서 연결됩니다.

## TypeScript 지원

이 패키지는 완전한 TypeScript 지원을 제공합니다. 모든 타입이 포함되어 있어 IDE에서 자동완성과 타입 검사를 받을 수 있습니다.

## 라이선스

MIT License