nook-client

취향 기반 장소 아카이빙 서비스, nook — 앱 클라이언트.

스택

항목	선택
빌드/패키지	pnpm workspace + Vite (web)
크로스플랫폼	Expo(RN) 셸 + react-native-webview (원격 웹)
서버 상태	TanStack Query
클라 상태	zustand
라우팅	React Router v7 (SPA)
언어	TypeScript
린트/포맷	Biome
테스트	Vitest + Testing Library
CI	GitHub Actions

얇은 Expo 셸이 원격 웹(app.nook.com)을 WebView 로 띄우고, 웹이 서비스 본체다. 셸은 WebView 가 못 하는 네이티브 접점만 담당한다.

구조 (모노레포)

apps/
├── web/                     # Vite SPA — 서비스 본체 (화면 전부)
│   └── src/
│       ├── app/             # 진입 배선: App, router, providers, queryClient
│       ├── features/        # 기능 단위 폴더 (home/ …)
│       ├── native-bridge/   # 셸 통신 클라이언트 (postMessage 프로토콜)
│       ├── shared/api/      # http 래퍼 (BE 호출 기반)
│       │   └── generated/   # Orval 생성 DTO·API 함수
│       ├── shared/config/   # env 게이트
│       └── styles/
└── mobile/                  # Expo(RN) 셸 — WebView + 네이티브 공유 대상

packages/
├── api-contracts/           # OpenAPI 스냅샷과 Orval 생성 설정
├── bridge-contracts/        # 셸 ↔ 웹 메시지 계약 (SSOT, 타입 전용)
└── icons/                   # Web·iOS·Android 공용 SVG와 코드 생성기

docs/                        # 아키텍처 결정 기록 / 브리지 문서

• pnpm 워크스페이스: apps/* + packages/* (web·mobile·계약을 한 락으로 관리).
• 웹↔셸 통신은 packages/bridge-contracts 의 { v, type, payload } postMessage 프로토콜. 상세는 docs/native-bridge.md.
• API 계층과 플랫폼별 인증·생성 코드 경계는 docs/[NOOK-55] 01.API_통신_구조.md를 따른다.
• OpenAPI 명세와 Orval 설정은 packages/api-contracts에서 관리하고 생성 코드는 Web의 shared/api/generated에 둔다. pnpm api:refresh로 재생성하며, 상세 규칙은 docs/[NOOK-56] 01.OpenAPI_스키마_DTO.md를 따른다.
• 공용 아이콘은 packages/icons/src의 SVG를 기준으로 플랫폼 코드를 생성한다. 상세는 docs/icons.md.
• @/ 는 web 의 src/ alias (Vite·tsc·Vitest 공통).

실행

web

pnpm install
cp apps/web/.env.example apps/web/.env.local   # BE 주소 필수

pnpm web:dev               # http://localhost:5173
pnpm web:build             # tsc --noEmit + vite build → apps/web/dist/
pnpm api:refresh           # 개발 서버 명세 + Orval 코드 재생성
pnpm check                 # 생성물 + lint + typecheck + test 검증
pnpm typecheck             # web + mobile tsc --noEmit
pnpm lint                  # biome check
pnpm format                # biome format --write
pnpm test                  # vitest run

mobile (Expo 셸)

cd apps/mobile
cp .env.example .env.local  # EXPO_PUBLIC_WEB_URL: 웹뷰가 로드할 원격 웹 URL

pnpm start                  # Expo dev
pnpm ios                    # 시뮬레이터/실기기
pnpm android                # 에뮬레이터/실기기

실기기에서는 dev 서버 대신 vite preview(빌드본 서빙)로 확인한다 — dev 서버의 재연결 리로드가 웹뷰 상태를 날린다.

환경변수 / 앱 variant

env 파일은 앱별로 둔다. 루트에는 두지 않는다(Vite·Expo 모두 각 앱 디렉터리를 기준으로 읽는다).

위치	용도
apps/{web,mobile}/.env.example	예시값, 커밋
apps/{web,mobile}/.env.local	로컬 전용, gitignore
EAS environment	mobile 배포 환경(development/production) 값
배포 플랫폼 환경변수	web 배포 값

• VITE_* 는 번들에 인라인, EXPO_PUBLIC_* 는 앱 번들에 포함된다. 둘 다 공개값만 넣는다.
• 앱 식별자는 APP_VARIANT 로 갈린다 (apps/mobile/app.config.ts). 미설정·오타는 production 으로 떨어진다.

APP_VARIANT	iOS App ID	Android App ID	App Group
development	com.nook.app.dev	com.nook.app.dev	group.com.nook.app.dev
production(기본)	kr.com.nook.app.dev	com.nook.app	group.kr.com.nook.app.dev

variant 별로 ID 가 달라 개발 앱과 운영 앱을 한 기기에 함께 설치할 수 있다. EAS 빌드 프로필은 apps/mobile/eas.json 참고.