# 개발 서버 미리보기

Termbridge은 로컬 개발 서버를 프록시해 미리보기 창에 표시할 수 있습니다. 모바일 테스트를 하거나 터미널 명령을 실행하면서 앱을 확인하기에 좋습니다.

## 빠른 시작

```bash
# Start your dev server (e.g., Vite on port 5173)
cd my-app && npm run dev

# In another terminal, start Termbridge with proxy
termbridge --proxy 5173
```

이제 UI에서 **터미널** 보기와 **미리보기** 보기 간에 전환할 수 있습니다.

## 작동 방식

`--proxy <port>`을 전달하면:

1. 모든 Termbridge 경로가 `/__tb/` 아래에 유지됩니다
2. 그 밖의 모든 요청은 개발 서버로 프록시됩니다
3. UI에 터미널과 미리보기 간에 전환하는 **보기** 버튼이 표시됩니다
4. 미리보기는 프록시를 거쳐 iframe에서 앱을 불러옵니다

```
Browser → Termbridge → Your dev server (localhost:5173)
```

## 보기 전환

1. 하단 바에서 **보기** 버튼을 탭합니다
2. **터미널로 전환** 또는 **미리보기로 전환**을 선택합니다
3. 보기가 즉시 바뀝니다

미리보기를 보는 동안에도 터미널 세션이 계속 실행되므로 두 보기 모두 연결된 상태로 유지됩니다.

## 핫 모듈 교체(HMR)

Vite의 HMR은 프록시를 통해 작동합니다. 로그인된 브라우저에서 `/__tb/` 외부로 연결되는 모든 WebSocket 연결이 경로와 관계없이 개발 서버로 전달되므로 별도 설정 없이 HMR 소켓이 연결됩니다.

코드를 수정하면 새로고침하지 않아도 미리보기 보기에서 변경 사항을 바로 확인할 수 있습니다.

## 지원 프레임워크

로컬 포트에서 실행되는 개발 서버라면 무엇이든 사용할 수 있습니다:

| 프레임워크 | 명령어 | 기본 포트 |
|-----------|---------|--------------|
| Vite | `npm run dev` | 5173 |
| Next.js | `npm run dev` | 3000 |
| Create React App | `npm start` | 3000 |
| Nuxt | `npm run dev` | 3000 |
| SvelteKit | `npm run dev` | 5173 |

`--proxy` 포트를 개발 서버의 포트와 일치시키세요.

## 사용 사례

### 모바일 테스트

실제 휴대폰에서 반응형 디자인을 테스트하세요:

```bash
termbridge --proxy 5173
```

QR 코드를 스캔하고 Safari 또는 Chrome의 모바일 화면에서 앱이 표시되는 모습을 그대로 확인하세요.

### 풀스택 개발

앱을 확인하면서 터미널에서 명령을 실행하세요:

1. 터미널 보기에서 빌드 출력을 확인합니다
2. 미리보기 보기에서 앱을 확인합니다
3. 탭 한 번으로 두 보기 사이를 전환합니다
4. 휴대폰이나 태블릿에서 계속 작업합니다

### 작업물 시연하기

다른 사람에게 보여줄 작업물이 있다면 공개 URL을 공유하세요:

- 실행 중인 앱(미리보기)
- 터미널 세션(터미널)

원격 페어링이나 간단한 시연에 유용합니다.

## 샌드박스 모드

Daytona 샌드박스를 사용할 때는 미리보기 포트를 설정하세요:

```bash
export TERMBRIDGE_SANDBOX_PREVIEW_PORT=5173
```

개발 서버가 모든 인터페이스에 바인딩되도록 설정하세요:

```bash
npm run dev -- --host 0.0.0.0 --port 5173
```

Termbridge은 Daytona 미리보기 URL를 UI을 통해 프록시합니다.

## 문제 해결

### 미리보기에 빈 페이지가 표시됨

- 개발 서버가 실행 중인지 확인하세요
- 포트가 `--proxy`과 일치하는지 확인하세요
- 샌드박스 모드에서는 포트에 접근할 수 있도록 `--host 0.0.0.0`을 사용하세요

### HMR이 작동하지 않음

- 개발 서버가 HMR을 지원하는지 확인하세요
- 브라우저 콘솔에서 WebSocket 오류를 확인하세요
- 일부 프레임워크는 HMR을 명시적으로 설정해야 합니다

### CORS 오류

프록시가 대부분의 CORS 문제를 처리하지만, 앱이 다른 출처에 요청을 보내는 경우:

- 개발 서버의 CORS 설정을 구성하세요
- 또는 브라우저 확장 프로그램으로 CORS를 우회하세요(개발용으로만 사용)