개발 모드로 실행하기

스타터 프로젝트를 만들었다면 이제 앱이 실제로 뜨는지 확인할 차례입니다.

이 단계의 목표는 간단합니다. 어떤 명령이 데스크톱 앱을 시작하는지, 그리고 데스크톱 모드와 웹 프리뷰 모드를 어떻게 구분하는지만 알면 됩니다.

1. 프로젝트 폴더로 이동

cd my-app

2. 의존성 설치

npm install

3. 개발 모드 시작

npm run app:dev

이 명령은 스타터 스크립트 뒤에서 frontron dev 를 실행합니다.

아래 두 가지가 연결됩니다.

• frontron.config.ts 에 적힌 웹 개발 명령
• Frontron support 를 통한 Electron 데스크톱 앱

브라우저 탭만 열리는 것이 아니라 데스크톱 창이 떠야 정상입니다.

반대로 npm run dev 는 웹 프리뷰 전용입니다. 데스크톱 브리지는 붙지 않습니다.

4. 무엇을 확인하면 되나요?

첫 실행에서는 아래를 보면 됩니다.

• 데스크톱 창이 열리는지
• 커스텀 타이틀바가 보이는지
• 스타터 화면이 보이는지

5. 보통의 수정 흐름

1. 파일 수정
2. 저장
3. 앱 창에서 결과 확인

React 변경은 보통 빠르게 반영됩니다. 런타임 쪽 변경은 다시 시작이 필요할 수 있습니다.

6. 잘 안 될 때 먼저 볼 것

창이 뜨지 않을 때

• 먼저 npx frontron check 를 실행합니다
• npm install 이 정상적으로 끝났는지
• 터미널에 runtime 에러가 없는지
• 같은 포트를 쓰는 다른 프로세스가 없는지

흰 화면이 보일 때

먼저 npx frontron check 를 실행하세요.

가장 먼저 vite.config.ts 와 루트 frontron.config.ts 의 개발 포트와 URL 이 맞는지 확인하세요.

브리지 관련 UI 가 이상할 때

타이틀바에 Web preview 가 보이거나 Desktop bridge unavailable 같은 문구가 보이면 아래를 확인하세요.

• npm run dev 가 아니라 npm run app:dev 를 실행했는지
• 렌더러 코드가 frontron/client 를 import 하는지
• 터미널에 runtime 또는 preload 에러가 없는지

TIP

본격적인 커스터마이징 전에 앱이 한 번 정상적으로 뜨는 경험을 먼저 만드는 것이 좋습니다.