개발 서버 미리보기

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

빠른 시작

# 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 소켓이 연결됩니다.

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

지원 프레임워크

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

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

사용 사례

모바일 테스트

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

termbridge --proxy 5173

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

풀스택 개발

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

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

작업물 시연하기

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

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

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

샌드박스 모드

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

export TERMBRIDGE_SANDBOX_PREVIEW_PORT=5173

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

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를 우회하세요(개발용으로만 사용)