메뉴
이 프로젝트 고유의 Expo·NativeWind·RN 함정과 패키지 도입 기준 (자동 트리거). Use when writing/modifying app-web UI code, when a style works on web but not native (or vice versa), when adding a new package, or when upgrading expo/nativewind/react-native-css. 일반 Expo API 사용법은 expo 공식 플러그인 skill 을 쓴다. 익스텐션 코드에는 해당 없다.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
TanStack Query 쿼리 정의·훅을 팀 컨벤션대로 스캐폴드한다. Use when connecting an API or creating useQuery/useMutation hooks (예:"API 연동해줘", "쿼리 훅 만들어줘", "서버 데이터 불러와줘"). 폼 상태는 /new-form, 로컬 UI 상태(useState)·익스텐션 코드에는 사용하지 않는다.
react-hook-form + zod 폼을 팀 컨벤션대로 스캐폴드한다. Use when creating a form or adding input validation (예:"폼 만들어줘", "입력 검증 추가해줘", "로그인 폼 구현", "검색 입력 구현"). 검색어 같은 단일 입력도 폼 상태(RHF)로 구성한다. 서버 상태 조회는 /new-query, 익스텐션 코드에는 사용하지 않는다.
NativeWind 기반 React Native 컴포넌트를 팀 컨벤션대로 스캐폴드한다. Use when creating a new UI component for the app/web. 익스텐션 UI 에는 사용하지 않는다.
expo-router 화면(라우트)을 팀 컨벤션대로 추가한다. Use when adding a new screen/route to the app/web. app/ 은 라우팅 껍데기로 두고 로직은 features 로 분리한다.
Creates a GitHub Pull Request by analyzing branch changes and filling in the project PR template. TRIGGER when: user invokes /pr directly, or says 'PR 만들어줘', 'PR 작성해줘'.
Analyzes staged/unstaged changes and performs atomic commits separated by concern. TRIGGER when: user invokes /commit directly, or says '커밋해줘', '커밋', 'commit'.
| name | expo-pitfalls |
| description | 이 프로젝트 고유의 Expo·NativeWind·RN 함정과 패키지 도입 기준 (자동 트리거). Use when writing/modifying app-web UI code, when a style works on web but not native (or vice versa), when adding a new package, or when upgrading expo/nativewind/react-native-css. 일반 Expo API 사용법은 expo 공식 플러그인 skill 을 쓴다. 익스텐션 코드에는 해당 없다. |
일반 문서에 없는, 이 레포에서 실측·디버깅으로 확인된 사실만 모은다. 일반 규칙은 docs/conventions/app-web.md.
새 기능에 패키지가 필요하면 탐색 순서를 지킨다:
expo-*) 우선 — https://docs.expo.dev/versions/v56.0.0/ 에서 먼저 찾는다. SDK 버전과 함께 관리되어 업그레이드 리스크가 가장 작다.cssInterop()/remapProps() 를 제거했다. babel transform 이 모든 컴포넌트의 className 을 자동 처리하므로 수동 등록 금지.style prop 이 className 을 이긴다.@expo/html-elements 의 H1~H6 처럼 내부에서 style={[styles.x, props.style]} 로 기본값을 주입하는 컴포넌트는 네이티브에서 className 이 무력화된다 (웹은 RNW 가 class vs class 경합으로 만들어 className 이 이김 → 같은 코드가 플랫폼별로 다르게 렌더).
styled(컴포넌트, { className: 'style' }) 로 className 을 style prop 슬롯에 매핑 — 내부 배열 마지막에 들어가 정당하게 덮는다. !important 불필요. 적용례: src/components/ui/heading/Heading.tsx.bold: { true: 'font-bold', false: 'font-normal' }).metro.config.js 의 inlineRem: 16 + patches/react-native-css.patch (옵션이 무시되는 업스트림 버그 1줄 수정) 세트로 고정 중.jest-expo 환경에는 className→style 해석기가 없다. className 스타일은 jest 렌더로 검증 불가 → tv 매핑 함수(예: headingStyles)를 export 해 클래스 문자열을 직접 단언하고, 실제 적용은 device/web 으로 확인한다 (/new-test 참조).
ios:/android:/native:/web: variant 는 src/global.css 에 @custom-variant 로 발췌돼 있다. nativewind/theme.css 전체 import 금지 — 미설치 의존성(tailwindcss-safe-area 등)이 딸려온다. 새 variant 가 필요하면 같은 방식으로 발췌 추가.
TextInput 의 placeholder·커서·선택 색은 RN 특성상 prop 전용 (placeholderTextColor 등) — 토큰 hex 를 상수로 두고 prop 지정. 적용례: src/components/ui/input/Input.tsx.src/components/ui/icon/Icon.tsx 래퍼로만 — className→color 매핑 + WeakMap 캐시가 들어 있다. 아이콘을 직접 styled 로 재래핑하지 않는다 (매 렌더 재생성 → native 크래시 이력).patches/react-native-css.patch 적용 가능 여부 확인 (§4).pnpm test + 주요 화면 웹/네이티브 육안 대조.