이 글의 성격은 무엇인가요?
질문 / 문제 해결
내용을 설명해주세요
안녕하세요. 앱인토스 미니앱(비게임 Web)을 개발 중인데, 토스 개발자 콘솔에서 테스트 QR코드를 스캔하여 진입하면 하얀 화면과 함께 “잠시 문제가 생겼어요” 에러 창만 뜨고 앱이 전혀 렌더링되지 않는 문제가 발생하여 문의드립니다.
저희는 공식 튜토리얼(AI 바이브 코딩 가이드 등)을 참고하여 설정했으나 며칠째 진전이 없어 아래와 같이 저희가 시도해 본 트러블슈팅 내역을 정리하여 올립니다. 혹시 저희가 놓치고 있는 Web 미니앱 필수 설정이 있는지 조언 부탁드립니다.
1. 개발 환경
프레임워크: React (Web) + Vite + TypeScript
라우터: React Router v6 (createMemoryRouter 사용)
SDK 버전: @apps-in-toss/web-framework v2.10.7, @apps-in-toss/cli v2.10.7
2. 에러 증상
CLI(npx ait deploy) 또는 콘솔 수동 업로드(bugcut.ait) 후, 토스 앱으로 QR코드를 스캔하면 로딩 스피너가 돌다가 하얀 화면 상태에서 “잠시 문제가 생겼어요” 바텀 시트가 노출됩니다.
(참고로 커뮤니티에 자주 올라오는 require.context.ts 쌍따옴표 에러는 RN 기반이 아니라서 해당 파일이 존재하지 않습니다.)
3. 시도해 본 트러블슈팅 내역
① Vite 빌드 시 type=“module” 및 crossorigin 제거 (CORS 이슈 대응) 아이폰(WKWebView)에서 커스텀 스킴(intoss-private://)을 사용할 때 type="module"이나 crossorigin이 있으면 CORS 보안 에러로 JS 파일을 불러오지 못해 하얀 화면이 뜬다는 점을 확인했습니다. 
조치: @vitejs/plugin-legacy를 적용하고 커스텀 Vite 플러그인을 통해 빌드된 index.html에서 과 nomodule, crossorigin 속성을 완전히 제거하여 일반(Classic) 스크립트로 동작하도록 강제했습니다. (그러나 여전히 동일 증상 발생)
② React Router History API 문제 대응 커스텀 스킴 위에서 window.history.pushState가 권한 이슈로 에러를 뱉어 앱 전체가 크래시될 가능성을 의심했습니다. 조치: BrowserRouter 대신 브라우저 히스토리 API를 사용하지 않는 createMemoryRouter로 변경했습니다.
③ granite.config.ts 설정 검증 조치: 가이드라인에 따라 appName과 brand.displayName을 토스 콘솔에 등록된 이름(“버그컷”)과 동일하게 맞추고, 임시 placeholder 아이콘 대신 유효한 https:// 로고 URL을 적용했습니다.
④ 번들 배포 방식 변경 조치: CLI의 _deploymentId 파라미터가 섞이는 문제를 배제하기 위해, package.json 버전을 올리면서 빌드한 최신 bugcut.ait 파일을 토스 콘솔에 직접 수동 업로드하여 고정된 QR코드로 테스트했습니다. (Vite의 빌드 결과물은 dist/web에 정상 위치한 것까지 확인)
질문 사항
위와 같이 의심되는 모든 원인(CORS, 라우팅, 설정 파일)을 제거하고 .ait 번들 구조도 규칙에 맞췄으나 여전히 "잠시 문제가 생겼어요"가 뜹니다.
React Web 환경(Vite)에서 @apps-in-toss/web-framework를 사용할 때, App.tsx 최상단을 감싸주어야 하는 전용 Provider 컴포넌트( 등)가 별도로 존재하나요?
Web 미니앱 빌드 시 Vite 대신 반드시 특정 번들러(Webpack, mpack 등)나 토스 전용 보일러플레이트를 사용해야만 정상 로딩이 되나요?
혹시 granite.config.ts 파일에서 Web 미니앱이 필수로 가져가야 하는 숨겨진(문서화되지 않은) 옵션이 있을까요?
어떤 작은 단서라도 좋으니 고견 부탁드리겠습니다! 감사합니다.
