Metro 설정 · 공유 패키지 소비 · 의존성 함정

apps/native-app은 turborepo 모노레포 안의 Expo/RN 프로젝트로, web(apps/app, Next.js)과 같은 공유 패키지(@howmuchhome-web/*)를 무수정으로 재사용합니다. 그 공유 패키지들은 web/node 전용 모듈(crypto, datadog 브라우저 SDK, @sentry/nextjs 등)을 transitive dependency로 끌고 오는데, RN 번들에는 이것들이 없거나 동작하지 않습니다. 이 간극을 메우는 곳이 Metro resolver·Babel 플러그인·patch-package입니다.

이 문서는 다음 파일을 근거로 합니다:

• apps/native-app/metro.config.js
• apps/native-app/babel.config.js, apps/native-app/plugins/babel-plugin-rn-svg-icons.js
• apps/native-app/src/shims/ (datadogMobile.ts, tty.js, os.js)
• 루트 patches/ (patch-package)
• apps/native-app/tsconfig.json

관련 문서: 크로스플랫폼 UI · native 컨벤션 · 로깅

1. 모노레포 Metro 구성

metro.config.js의 기본 골격입니다.

const projectRoot = __dirname;                       // apps/native-app
const workspaceRoot = path.resolve(projectRoot, '../..'); // 레포 루트
 
const config = getSentryExpoConfig(projectRoot);
 
config.watchFolders = [workspaceRoot];
config.resolver.nodeModulesPaths = [
  path.resolve(projectRoot, 'node_modules'),
  path.resolve(workspaceRoot, 'node_modules'),
];
config.resolver.disableHierarchicalLookup = true;

cacheVersion 은 EXPO_PUBLIC_STORYBOOK 값('storybook'/'app')으로 분리합니다. 앱 Metro 와 on-device Storybook Metro 를 동시에 띄울 때 캐시가 서로를 오염시키지 않도록 하기 위함입니다.

2. resolveRequest shim 표

공유 패키지가 끌고 오는 web/node 전용 의존을 커스텀 resolver.resolveRequest 에서 native 호환으로 처리합니다. 공유 패키지와 web 소스는 무수정입니다.

resolveRequest 는 다음 순서로 분기하고, 어디에도 걸리지 않으면 기본 resolver 로 위임합니다.

주의(적용 순서): REDIRECTS 를 먼저 적용한 뒤(const target = REDIRECTS[moduleName] ?? moduleName) isSentryJsSdk(target) 를 검사합니다. require.resolve 가 실패하는 경우(예: v10 트리에 없는 구버전 모듈)는 try/catch 로 삼켜 기본 해석으로 fallback 합니다.

shim 계층은 왜 이 구조인가

• 버전 스큐가 아니라 Metro 한계. 모노레포의 @sentry JS SDK 는 web @sentry/nextjs·native @sentry/react-native 모두 v10 으로 통일돼 있습니다. @sentry exports 보정은 버전 충돌 해결이 아니라 순전히 Metro 의 exports-서브패스 미해석 때문입니다.
• stub vs 어댑터. crypto/@tanstack/react-query-next-experimental 는 native 에서 실제로 호출되지 않아 빈 모듈로 충분합니다. datadog 은 native 에서도 실제 로깅이 필요하므로 동작하는 어댑터(datadogMobile.ts)로 브리지합니다.

3. 아이콘 Babel 치환 (babel-plugin-rn-svg-icons.js)

@howmuchhome-web/icon(packages/icon/libs)의 아이콘은 web DOM SVG(<svg>/<path> …)로 작성돼 있어 RN 에서 그대로 렌더되지 않습니다(Unimplemented component: svg). native 빌드에서만 동작하는 커스텀 Babel 플러그인이 이를 react-native-svg 컴포넌트로 치환합니다.

babel.config.js 에 등록:

plugins: [
  require('./plugins/babel-plugin-rn-svg-icons.js'),
  'react-native-worklets/plugin', // Reanimated 4 worklet 변환 — 반드시 배열 마지막
],

플러그인 동작:

• 파일 스코프: (^|/)(packages/icon|@howmuchhome-web/icon)/libs/ 정규식으로 매칭되는 파일에만 적용(소스 경로 + node_modules 심링크 경로 모두). web 소스·타 파일은 무영향.
• 엘리먼트 치환: ELEMENT_MAP 으로 소문자 SVG 엘리먼트를 컴포넌트명으로 (svg→Svg, path→Path, linearGradient→LinearGradient …). 사용된 컴포넌트명으로 import { … } from 'react-native-svg' 를 파일 상단에 주입.
• 속성 처리: fill/d/viewBox/fillRule/stopColor 등은 react-native-svg 가 동일 camelCase 로 받으므로 그대로. xmlns* 만 제거(미지원 경고 방지).

결과적으로 web 소스는 DOM svg 그대로 두고, native 빌드에서만 아이콘 파일이 react-native-svg 로 렌더됩니다.

react-native-svg 는 아이콘을 소비하는 공유 패키지(packages/ui)의 package.json 에 선언되어 있습니다(§5의 “RN 전용 dep 는 hoist 안 됨” 규칙).

4. patch-package 로 처리하는 것들

패치는 루트 patches/ 에 있고 patch-package 로 적용됩니다(앱 하위 patches/ 가 아님). native 에 영향 있는 항목:

expo-realtime-ivs-broadcast+0.2.8.patch 도 루트에 있으나 방송 기능 전용입니다.

5. 공유 패키지를 native 가 소비하는 규칙

.native.tsx / .shared.ts 분리

공유 UI 는 컴포넌트별로 native 구현(*.native.tsx)과 web 구현, 그리고 공유 로직(*.shared.ts)을 따로 둡니다.

packages/ui/v2/RadioGroup/
  RadioGroup.tsx          # web
  RadioGroup.native.tsx   # native (Metro 가 .native 우선 해석)
packages/ui/v2/Button/
  Button.shared.ts        # 양쪽 공유 로직/타입

/native 배럴 진입점

native 는 전용 배럴에서 import 합니다. 각 패키지 package.json exports 에 ./native 가 있습니다.

import {Button, Form} from '@howmuchhome-web/ui/native';
import {Funnel, useFunnel} from '@howmuchhome-web/funnel/native';

• packages/ui/package.json → "./native": "./native/index.ts"
• packages/funnel/package.json → "./native": "./native/index.ts" (web funnel 은 @use-funnel/browser+next+react-dom+window.history 의존이라 RN 불가 → native 는 memory 라우터 기반 구현)

customConditions: ["react-native"] (tsconfig)

apps/native-app/tsconfig.json 은 customConditions: ["react-native"] 로, tsc 도 Metro 와 동일하게 package.json exports 의 "react-native" 조건을 해석합니다(예: react-native-css/components). 이게 없으면 타입체크와 런타임 해석이 어긋납니다.

RN 전용 dep 는 루트에 hoist 되지 않는다

RN 전용 패키지가 앱(apps/native-app)의 package.json 에만 선언돼 있으면, 공유 패키지(packages/*)에서 import 할 때 tsc·Metro 가 못 찾습니다. 공유 패키지가 쓰는 RN dep 는 그 패키지의 package.json 에 선언해야 합니다.

• 예: react-native-svg, react-native-css, react-native-reanimated 등은 packages/ui/package.json 에 선언됨.
• 반대로 앱 레벨에서만 필요한 것(@datadog/mobile-react-native, @sentry/react-native)은 앱에서 주입/설정하고, 공유 패키지는 Metro shim 을 통해 간접적으로 연결됩니다(§2).

6. 문제 진단 지도 (native 모듈 해석/의존성)

native 빌드에서 모듈 해석·의존성 오류를 만났을 때 참고합니다.

CI 캐시 stale 함정(재강조): 공유 패키지의 소스만 바꾸고 의존성은 안 추가하면 yarn.lock 이 그대로라, lockfile 해시로 키를 만드는 node_modules/설치 캐시가 이전 상태를 그대로 복원합니다. 소스 변경은 watch/번들 그래프에는 반영되지만, “설치물 자체가 stale” 한 상황(patch-package 재적용 누락 등)은 lockfile 로 감지되지 않으니 주의합니다.