[Feat/#3] 웹뷰 셸 구현 #4
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| # 웹뷰로 띄울 stream-client-web 주소. | ||
| # 이 파일을 .env.local로 복사한 뒤 값을 자기 환경에 맞게 채운다. | ||
| # | ||
| # 실행 환경마다 주소가 다르다 (docs/local-development.md 참고): | ||
| # - iOS 시뮬레이터 http://localhost:5173 | ||
| # - Android 에뮬레이터 http://10.0.2.2:5173 | ||
| # - 실제 기기 http://{개발 PC의 LAN IP}:5173 | ||
| # | ||
| # LAN IP 확인: ipconfig getifaddr en0 | ||
| # 실제 기기는 PC와 같은 네트워크에 있어야 하고, 웹도 pnpm dev --host로 띄워야 한다. | ||
| # 배포 후에는 운영 URL로 바꾼다. | ||
| EXPO_PUBLIC_WEB_URL=http://192.168.0.2:5173 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,57 +1,61 @@ | ||
| # stream-client-app | ||
|
|
||
| 국민대학교 소프트웨어융합대학 통합 플랫폼 'STREAM' 앱 (Expo + React Native + TypeScript). | ||
|
|
||
| 화면 UI는 [stream-client-web](https://github.com/billilge/stream-client-web)이 전담한다. 이 저장소는 그 웹을 WebView로 띄우는 **네이티브 셸**이다. 앞으로 푸시 알림, 토큰 저장처럼 웹이 할 수 없는 기능을 네이티브에서 맡는다. | ||
|
|
||
| ## 개발 환경 | ||
|
|
||
| - Node: `.nvmrc` 참고 (`nvm use`) | ||
| - 패키지 매니저: [pnpm](https://pnpm.io/) — Corepack으로 관리한다 (`corepack enable` 후 `pnpm install`만 실행하면 `packageManager` 필드에 고정된 버전이 자동으로 쓰인다) | ||
|
|
||
| ```bash | ||
| corepack enable | ||
| pnpm install | ||
| cp .env.example .env.local # 웹 주소를 실행 환경에 맞게 채운다 | ||
| pnpm start | ||
| ``` | ||
|
|
||
| ### 웹 주소 설정 | ||
|
|
||
| WebView가 띄울 주소는 `.env.local`의 `EXPO_PUBLIC_WEB_URL`로 주입한다. 이 파일은 git에 올리지 않는다. | ||
|
|
||
| **실행 환경마다 가리켜야 하는 주소가 다르다.** | ||
|
|
||
| | 실행 환경 | 웹 주소 | | ||
| | --- | --- | | ||
| | iOS 시뮬레이터 | `http://localhost:5173` | | ||
| | Android 에뮬레이터 | `http://10.0.2.2:5173` | | ||
| | 실제 기기 (Expo Go) | `http://{개발 PC의 LAN IP}:5173` | | ||
|
|
||
| 실제 기기에서는 `localhost`가 기기 자신을 가리켜 개발 PC에 닿지 않으므로 LAN IP를 써야 하고, 웹도 `pnpm dev --host`로 띄워야 한다. | ||
|
|
||
| 자세한 실행 방법·준비물·트러블슈팅은 **[docs/local-development.md](docs/local-development.md)** 참고. | ||
|
|
||
| ## 스크립트 | ||
|
|
||
| | 명령 | 설명 | | ||
| | --- | --- | | ||
| | `pnpm start` | Expo 개발 서버 실행 | | ||
| | `pnpm ios` | iOS 시뮬레이터에서 실행 | | ||
| | `pnpm android` | Android 에뮬레이터에서 실행 | | ||
| | `pnpm web` | 웹에서 실행 | | ||
| | `pnpm lint` | Biome lint | | ||
| | `pnpm format` | Biome로 포맷 적용 | | ||
| | `pnpm check` | Biome lint + format 검증 | | ||
|
|
||
| ## 구조 | ||
|
|
||
| ``` | ||
| src/ | ||
| ├─ app/ expo-router 라우팅 껍데기 | ||
| ├─ features/webview/ WebView 셸 화면 | ||
| ├─ constants/ 설정 상수 | ||
| └─ utils/ 공용 유틸 | ||
| ``` | ||
|
|
||
| ## 문서 | ||
|
|
||
| - [로컬 실행 가이드](docs/local-development.md) | ||
| - [코딩 컨벤션](docs/conventions/coding-style.md) | ||
| - [Git 컨벤션](docs/conventions/git-convention.md) |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| # 로컬 실행 가이드 | ||
|
|
||
| > 이 앱은 `stream-client-web`을 WebView로 띄우는 셸이다. 따라서 **웹 서버와 앱을 함께 띄워야** 화면이 보인다. | ||
|
|
||
| --- | ||
|
|
||
| ## 1. 준비 | ||
|
|
||
| ```bash | ||
| corepack enable | ||
| pnpm install | ||
| cp .env.example .env.local | ||
| ``` | ||
|
|
||
| `.env.local`의 `EXPO_PUBLIC_WEB_URL`에 웹 주소를 넣는다. **실행 환경마다 주소가 다르다** — 아래 표 참고. | ||
|
|
||
| | 실행 환경 | 웹 주소 | 비고 | | ||
| | --- | --- | --- | | ||
| | iOS 시뮬레이터 | `http://localhost:5173` | 시뮬레이터가 맥의 네트워크를 그대로 쓴다 | | ||
| | Android 에뮬레이터 | `http://10.0.2.2:5173` | `10.0.2.2`가 호스트 PC의 `localhost`에 매핑된다 | | ||
| | 실제 기기 (Expo Go) | `http://{개발 PC의 LAN IP}:5173` | 기기와 PC가 같은 네트워크에 있어야 한다 | | ||
|
|
||
| LAN IP 확인: | ||
|
|
||
| ```bash | ||
| ipconfig getifaddr en0 # 유선이면 en1 등 다른 인터페이스일 수 있다 | ||
| ``` | ||
|
|
||
| ## 2. 웹 서버 띄우기 | ||
|
|
||
| 별도 터미널에서 `stream-client-web`을 실행한다. | ||
|
|
||
| ```bash | ||
| cd ../stream-client-web | ||
| pnpm dev | ||
| ``` | ||
|
|
||
| **실제 기기로 볼 때는 `--host`가 필요하다.** Vite dev 서버는 기본적으로 `localhost`에만 바인딩해서 다른 기기에서 닿지 않는다. | ||
|
|
||
| ```bash | ||
| pnpm dev --host | ||
| ``` | ||
|
|
||
| ## 3. 앱 실행 | ||
|
|
||
| ```bash | ||
| pnpm start # QR 코드가 뜬다 | ||
| pnpm ios # iOS 시뮬레이터로 바로 실행 | ||
| pnpm android # Android 에뮬레이터로 바로 실행 | ||
| pnpm web # 브라우저에서 실행 | ||
| ``` | ||
|
|
||
| `.env.local`을 고쳤으면 **Expo 개발 서버를 재시작해야 반영된다.** `EXPO_PUBLIC_*` 값은 번들 시점에 주입되기 때문이다. | ||
|
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis🏁 Script executed: sed -n '1,135p' docs/local-development.md
cat package.jsonRepository: billilge/stream-client-app Length of output: 4437 🌐 Web query:
💡 Result: <search_synthesis> <source_evidence> Citations:
Require a full app reload after 🤖 Prompt for AI Agents |
||
|
|
||
| --- | ||
|
|
||
| ## 실행 환경별 준비물 | ||
|
|
||
| ### 실제 기기 (권장 — 준비물이 가장 적다) | ||
|
|
||
| 기기에 **Expo Go** 앱만 설치하면 된다 (App Store / Play Store). `react-native-webview`는 Expo Go에 포함되어 있어 별도 네이티브 빌드가 필요 없다. | ||
|
|
||
| 1. `pnpm start` | ||
| 2. 터미널의 QR 코드를 스캔 — iOS는 기본 카메라 앱, Android는 Expo Go 앱 안에서 | ||
| 3. 기기와 PC가 같은 와이파이에 있어야 한다 | ||
|
|
||
| ### iOS 시뮬레이터 | ||
|
|
||
| **Xcode가 필요하다** (App Store에서 설치, 용량이 크고 시간이 오래 걸린다). Command Line Tools만으로는 시뮬레이터가 없다. | ||
|
|
||
| ```bash | ||
| xcode-select -p # /Applications/Xcode.app/... 이 나와야 한다 | ||
| xcrun simctl list devices available # 사용 가능한 시뮬레이터 목록 | ||
| pnpm ios | ||
| ``` | ||
|
|
||
| `xcode-select -p`가 `/Library/Developer/CommandLineTools`를 가리키면 Xcode 설치 후 아래를 실행한다. | ||
|
|
||
| ```bash | ||
| sudo xcode-select -s /Applications/Xcode.app/Contents/Developer | ||
| ``` | ||
|
|
||
| ### Android 에뮬레이터 | ||
|
|
||
| **Android Studio가 필요하다.** 설치 후 Device Manager에서 가상 기기(AVD)를 하나 만든다. | ||
|
|
||
| ```bash | ||
| emulator -list-avds # 만든 AVD 목록 | ||
| pnpm android | ||
| ``` | ||
|
|
||
| ### 웹 (`pnpm web`) | ||
|
|
||
| 브라우저에서 `react-native-web`으로 렌더링된다. 화면 확인용으로는 쓸 수 있지만 **하드웨어 백 버튼, 외부 링크 처리 같은 네이티브 동작은 검증되지 않는다.** 최종 확인은 기기나 시뮬레이터에서 한다. | ||
|
|
||
| --- | ||
|
|
||
| ## 확인할 것 | ||
|
|
||
| 셸이 제대로 동작하는지 보려면 아래를 확인한다. | ||
|
|
||
| - [ ] 웹 화면이 뜨는가 | ||
| - [ ] 로드 중 스피너가 보이고, 로드되면 사라지는가 | ||
| - [ ] Bottom Nav로 화면을 옮긴 뒤 **Android 하드웨어 백 버튼**이 앱 종료가 아니라 웹 뒤로 가기로 동작하는가 (Android 전용) | ||
| - [ ] 네트워크를 끊고 앱을 다시 열면 오류 화면과 `다시 시도` 버튼이 뜨는가 | ||
| - [ ] 외부 도메인 링크가 웹뷰 안이 아니라 시스템 브라우저로 열리는가 | ||
|
|
||
| > 현재 웹의 `ScreenLayout`이 `375x812` 고정 프레임이라 화면이 꽉 차지 않고 가운데 정렬된 채 여백이 생긴다. 알려진 사항이며 web 레포에서 별도로 대응한다. | ||
|
|
||
| --- | ||
|
|
||
| ## 잘 안 될 때 | ||
|
|
||
| | 증상 | 원인 / 해결 | | ||
| | --- | --- | | ||
| | "웹 주소가 설정되지 않았습니다" 화면 | `.env.local`에 `EXPO_PUBLIC_WEB_URL`이 없다. 채운 뒤 Expo 서버를 **재시작**한다 | | ||
| | "페이지를 불러오지 못했습니다" 화면 | 웹 dev 서버가 꺼져 있거나, 주소가 실행 환경과 맞지 않는다(위 표 확인) | | ||
| | 실제 기기에서만 안 닿는다 | 웹을 `pnpm dev --host`로 띄웠는지, 기기와 PC가 같은 네트워크인지, 맥 방화벽이 막고 있지 않은지 확인 | | ||
| | `.env.local`을 고쳤는데 그대로다 | `EXPO_PUBLIC_*`은 번들 시점에 주입된다. Expo 개발 서버를 재시작한다 | | ||
| | LAN IP가 자꾸 바뀐다 | 공유기가 DHCP로 새 IP를 준 것이다. `ipconfig getifaddr en0`로 다시 확인해 `.env.local`을 갱신한다 | | ||
|
|
||
| > 로컬 `http://` 접속은 Expo Go에서 동작한다. 나중에 자체 개발 빌드(EAS)로 넘어가면 iOS ATS 예외 설정이 필요할 수 있다. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
Repository: billilge/stream-client-app
Length of output: 6655
🏁 Script executed:
Repository: billilge/stream-client-app
Length of output: 4901
Replace the machine-specific LAN address with an empty value.
.env.exampleis copied to.env.local, andsrc/constants/config.tspasses this value directly toWEB_URL. If a developer does not replace192.168.0.2, the WebView targets that LAN host and skips the missing-configuration screen. The repository documentation requires developers to set an address for their execution environment.Proposed fix
📝 Committable suggestion
🤖 Prompt for AI Agents