로컬 개발

설치, 데이터베이스, dev 서버, 테스트/린트/빌드, 그리고 모바일(Capacitor) 실행

사전 준비

Node (저장소는 Node 22 기준으로 동작) · pnpm (packageManager: pnpm@10.x)
Docker (로컬 Postgres)
모바일 작업 시: Xcode(iOS), Android Studio + JDK 21(Android, cap 8.3.4 요구)

한 번에 따라하기

pnpm install
pnpm db:up                      # docker compose postgres (:60000)
pnpm db:push && pnpm db:seed    # Drizzle 스키마 + 데모 시드 (5 students)
pnpm dev:api                    # http://localhost:8787  (vite + @cloudflare/vite-plugin, workerd)
pnpm dev:web                    # http://localhost:5173

pnpm db:up 은 포트 60000 으로 Postgres 를 띄웁니다(일반적인 5432 가 아닙니다). pnpm db:seed 는 런타임(Workers=UTC)과 날짜 경계를 맞추기 위해 TZ=UTC 를 강제합니다.

주요 스크립트

명령	설명
`pnpm install`	워크스페이스 전체 의존성 설치
`pnpm db:up` / `pnpm db:down`	로컬 Postgres 컨테이너 시작/중지 (`docker compose`)
`pnpm db:push`	Drizzle 스키마를 DB 에 반영
`pnpm db:seed`	데모 시드(학생 5명) 삽입
`pnpm db:reset`	`push:force` 후 재시드
`pnpm db:studio`	Drizzle Studio
`pnpm dev:api`	API dev 서버 (`http://localhost:8787`)
`pnpm dev:web`	웹 dev 서버 (`http://localhost:5173`)
`pnpm dev:docs`	이 문서 사이트 dev 서버 (`http://localhost:4321`)
`pnpm test`	vitest 유닛 (`packages/shared`)
`pnpm test:integration`	API 통합 테스트 (`TZ=UTC`, 로컬 Postgres 필요)
`pnpm lint`	eslint (flat config)
`pnpm build`	turbo build (web + api + docs)
`pnpm build-storybook`	`storybook-static` 생성

이 문서 사이트(apps/docs)의 dev 포트는 4321 로, 웹(5173)·API(8787) 와 충돌하지 않습니다. pnpm dev:docs 또는 pnpm --filter @neul/docs dev 로 실행합니다.

API 의 로컬 환경변수는 apps/api/.dev.vars 에 둡니다. 이는 Cloudflare Workers 의 로컬 .env 에 해당하는 wrangler 규약 파일입니다 — Worker 는 .env 가 아니라 이 파일을 읽습니다. 키 목록은 루트의 .env.example 을 참고하세요. dev/prod 환경의 시크릿은 wrangler secret 으로 원격 주입합니다(배포 참고).

모바일 (Capacitor)

Capacitor CLI 는 apps/web 에서 실행하며, webDir 은 dist 입니다.

pnpm --filter @neul/web build                              # dist 생성

# dev 라이브리로드 모드: 앱을 http(server.url)로 로드
CAPACITOR_SERVER_URL=http://localhost:5173 pnpm cap:sync
pnpm cap:run:ios       # 또는 pnpm cap:run:android
pnpm e2e:ios           # Appium e2e (네이티브)

모바일 dev 네트워킹 한눈에

번들(capacitor://)에서 http API 를 직접 fetch 하면 mixed-content 로 차단됩니다. 그래서 dev 에서는 CAPACITOR_SERVER_URL 로 앱 자체를 http 로 로드합니다.

호스트: iOS 시뮬레이터 = localhost, Android 에뮬레이터 = 10.0.2.2(호스트 loopback alias).
API URL 은 apps/web/src/lib/api.ts 가 location.hostname 으로 유추하므로, 한 번의 빌드로 localhost / 10.0.2.2 / LAN 을 모두 대응합니다.
클리어텍스트 허용(dev): iOS Info.plist ATS 예외, Android AndroidManifest.xml usesCleartextTraffic="true".
Android 빌드는 JDK 21 필요. 에뮬레이터는 emulator -avd <name> -gpu swiftshader_indirect 로 띄웁니다.

자세한 CORS/PNA 처리는 아키텍처 › CORS와 모바일 네트워킹에서 설명합니다.