---

name: bungae-bundler description: Bungae React Native 번들러 개발 가이드. 번들링 구현, 설정 시스템, 개발 서버, Babel 통합 등 번들러 개발 작업 시 참조. Resolution, Transformation, Serialization 파이프라인 구현 및 Metro 호환성 유지에 활용. license: MIT metadata: author: ohah version: '0.0.1'

Bungae Bundler Development Guide

Bun 기반 React Native 번들러 개발을 위한 종합 가이드. Metro 호환성을 유지하면서 Bun의 성능 이점을 최대한 활용.

When to Apply

다음 작업 시 참조:

• 번들링 파이프라인 구현 (Resolution, Transformation, Serialization)
• 설정 시스템 구현 또는 수정
• 개발 서버 및 HMR 구현
• Babel 선택적 통합 작업
• 캐싱 및 최적화 구현
• Metro 호환성 관련 작업

Rule Categories

Quick Reference

기술 스택

⚠️ Bunup 사용 시 주의사항

bunup 관련 작업(설정, 옵션, 플러그인 등)을 할 때는 반드시 공식 웹 스펙 문서를 참조하세요:

• 공식 문서: https://bunup.dev/docs/guide/options.html
• bunup의 옵션, 설정, 플러그인 시스템 등은 공식 문서를 기준으로 사용해야 합니다.
• 프로젝트 내부 문서보다 공식 스펙 문서가 최신이고 정확합니다.

번들링 3단계

CopyEntry → [Resolution] → [Transformation] → [Serialization] → Bundle

1. Resolution: 모듈 경로 해석 (플랫폼별 확장자, node_modules)
2. Transformation: 코드 변환 (Bun 내장 우선, Babel 선택적)
3. Serialization: 번들 생성 (Plain, RAM Bundle)

Transformer 전략: Metro 호환 변환 순서

Metro의 변환 파이프라인을 따르되, 각 도구가 가장 잘하는 작업을 담당:

Copy1. Hermes Parser Plugin - Flow + JSX 파싱 (Babel only)
2. Flow Enum Transform   - Flow enum 처리 (Babel only)
3. Flow Type Stripping   - Flow 타입 제거 (Babel only)
4. ESM → CJS Conversion  - 모듈 변환 (SWC - fast)
5. JSX Transformation    - JSX 변환 (SWC - fast)

점진적 Babel 제거 계획

현재 Flow 처리를 위해 Babel을 사용하지만, 장기적으로 Babel 의존성을 최소화할 계획:

• Phase 1 (현재): Flow 파일용 Babel + SWC로 나머지 변환
• Phase 2: Hermes Parser 직접 통합 - Babel 없이 Hermes Parser AST 조작으로 Flow 타입 제거 구현
  • 참고: https://github.com/facebook/hermes/tree/main/lib/Parser
  • Hermes Parser는 React Native의 공식 파서로, Flow 구문을 네이티브 지원
  • Babel 의존성 제거 및 성능 향상 기대
• Phase 3: SWC Flow 지원 대기 (대안) 또는 전체 파이프라인을 SWC로 통합
• Phase 4: Babel은 특수 플러그인 필요 시에만 사용 (reanimated, styled-components 등)

Babel이 필수인 케이스

주요 Bun API

CopyBun.file(); // 파일 I/O
Bun.serve(); // HTTP 서버
Bun.build(); // 번들링
Bun.Transpiler; // 코드 변환

Implementation Roadmap

Phase 1: 핵심 번들링

• Config 시스템 (플랫폼 정보 등 설정)
  • ✅ Config 로딩 (bungae.config.ts/js/json, package.json)
  • ✅ Config 병합 및 기본값 처리
  • ✅ Config 검증 로직
  • ✅ Server config 추가
  • ✅ Metro-compatible API (loadConfig({ config, cwd }))
  • ✅ Metro 스타일 테스트 코드 (11개 테스트 케이스)
• Platform Resolver Plugin (.ios.js, .android.js 해석)
  • ✅ Bun Plugin으로 플랫폼 확장자 처리
  • ✅ .ios.js, .android.js, .native.js 지원
  • ✅ TypeScript 확장자 지원 (.ios.tsx, .android.ts 등)
  • ✅ preferNativePlatform 옵션 지원
• 코드 변환 (Transformation) - Bun.Transpiler 기본 + 선택적 Babel
  • ✅ Bun.Transpiler 기반 변환 구현
  • ✅ TypeScript/TSX/JSX → JavaScript 변환
  • ✅ 의존성 추출 (require, import, dynamic import)
  • ✅ Babel 선택적 통합 스켈레톤 (Phase 2에서 구현)
  • ✅ Metro 스타일 테스트 코드 (10개 테스트 케이스 모두 통과)
• Serialization - Metro 호환 번들 형식
  • ✅ baseJSBundle 구현 (Metro 호환)
  • ✅ metro-runtime 번들 포함
  • ✅ prelude, polyfills 지원
  • ✅ **d(), **r() 형식 지원
  • ✅ 모듈 ID 생성 및 정렬
  • ✅ Source map URL 지원
  • ✅ SerializerOptions에 Metro 호환 옵션 추가 (inlineSourceMap, shouldAddToIgnoreList, includeAsyncPaths, modulesOnly, asyncRequireModulePath, getSourceUrl)
  • ✅ modulesOnly 옵션 구현 (prelude/runtime 제외)
  • ✅ inlineSourceMap 옵션 스켈레톤 추가 (Phase 2에서 완전 구현 예정)
  • ✅ InitializeCore 자동 감지 및 runBeforeMainModule 처리
  • ✅ sourceUrl, sourceMapUrl 옵션 사용 (개발 서버)
  • ✅ Metro 스타일 테스트 코드 (6개 Metro 테스트 통과, 2개 skip, InitializeCore 테스트 포함)

⚠️ Resolution 구현 전략:

• Bun.build()의 기본 해석을 활용
• 플랫폼 확장자만 Plugin으로 추가 처리
• 완전히 새로 구현할 필요 없음

Phase 2: 개발 환경 (증분 빌드 포함)

• 증분 빌드 시스템 (핵심)
  • 의존성 그래프 (Graph)
  • 델타 계산기 (DeltaCalculator)
  • 변환 캐시 (TransformCache)
  • 순환 참조 GC
• 개발 서버 (Bun.serve)
• 파일 감시 (fs.watch)
• HMR (WebSocket + 증분 업데이트)

📌 증분 빌드를 Phase 2에 넣는 이유:

• 개발 서버와 HMR의 핵심 의존성
• 파일 변경 → 변경분만 재빌드 → HMR 전송
• Phase 3 최적화와 별개로 필수 기능

상세 구현: rules/incremental-build.md

Phase 3: 최적화

• 영구 캐싱 (디스크)
• Minification
• Tree Shaking

Phase 4: 고급 기능

• RAM Bundle
• Fast Refresh
• 플러그인 시스템
• require.context
• Lazy/Async 모듈

Metro 호환성 및 제외된 기능

Phase 1-3에서 구현하지 않은 기능 (Phase 2 또는 Phase 3에서 구현 예정)

다음 기능들은 Metro에 있지만 Phase 1-3에서는 구현하지 않았으며, Phase 2 또는 Phase 3에서 구현할 예정입니다:

1. inlineSourceMap 옵션 (스켈레톤 완료, 완전 구현 예정)

   • Metro에서의 용도: Source map을 번들 파일에 인라인으로 포함 (base64 인코딩)
   • 현재 상태: 옵션 타입 및 스켈레톤 구현 완료, 실제 source map 생성 로직은 Phase 2에서 구현 예정
   • 구현 시점: Phase 2 또는 Phase 3
   • 관련 테스트: should add an inline source map to a very simple bundle (Metro 테스트, skip 상태)

2. x_google_ignoreList 생성 (옵션 완료, 생성 로직 예정)

   • Metro에서의 용도: Chrome DevTools에서 특정 소스 파일을 디버깅에서 제외하기 위한 source map 메타데이터
   • 현재 상태: shouldAddToIgnoreList 옵션 추가 완료, x_google_ignoreList 생성 로직은 Phase 2에서 구현 예정
   • 구현 시점: Phase 2 또는 Phase 3
   • 관련 테스트: emits x_google_ignoreList based on shouldAddToIgnoreList (Metro 테스트, skip 상태)

3. Asset 지원

   • Metro에서의 용도: 이미지, 폰트 등 정적 자산을 번들에 포함
   • 현재 상태: 기본 번들링 테스트에서는 asset 없이도 핵심 기능 검증 가능
   • 구현 시점: Phase 3 또는 Phase 4 (필요 시)
   • 관련 테스트: Metro의 basic_bundle/Foo.js는 require('./test.png')를 사용
   • 참고: 현재는 JavaScript/TypeScript 모듈 번들링에 집중

4. TypeScript 모듈 통합 테스트

   • Metro에서의 용도: TypeScript 파일을 번들에 포함하고 실행 검증
   • 현재 상태: TypeScript 변환은 지원하지만, Metro의 TypeScript.ts 모듈 통합 테스트는 미구현
   • 구현 시점: Phase 3 또는 Phase 4 (필요 시)
   • 관련 테스트: Metro의 basic_bundle/TypeScript.ts는 복잡한 TypeScript 기능 테스트
   • 참고: 현재는 기본 TypeScript 변환만 테스트 (별도 테스트 케이스 존재)

테스트 일치성 관련 이슈

현재 통합 테스트는 Metro와 동일한 스타일(execBundle + toMatchSnapshot())을 사용하지만, 테스트 파일이 다르기 때문에 snapshot 결과가 다릅니다:

1. 테스트 파일 차이

   • Metro: TestBundle.js가 {Foo, Bar, TypeScript}를 export
   • Bungae: TestBundle.js가 {Foo, Bar}만 export (TypeScript 모듈 없음)
   • 영향: Snapshot 결과가 다름 (Metro는 3개 모듈, Bungae는 2개 모듈)

2. Asset 의존성 차이

   • Metro: Foo.js가 require('./test.png')를 사용하여 asset을 포함
   • Bungae: Foo.js가 간단한 객체만 export (asset 없음)
   • 영향: Metro의 snapshot에는 asset 객체가 포함되지만, Bungae에는 없음

3. 의존성 구조 차이

   • Metro: Bar.js가 Foo.js를 require하여 Foo.type을 참조
   • Bungae: Bar.js와 Foo.js가 독립적
   • 영향: Metro의 snapshot은 Bar.foo: "foo"를 포함하지만, Bungae는 독립적인 구조

참고: 현재 테스트는 핵심 번들링 기능(의존성 해석, 변환, 직렬화, require 경로 변환)을 검증하는 데 충분합니다. Asset과 TypeScript 모듈 통합 테스트는 위의 백로그 항목으로 관리됩니다.

구현하지 않는 Metro 기능

다음 기능들은 Metro에 있지만 Bungae에서는 구현하지 않습니다:

1. cacheStores (callback 패턴)

Metro에서의 용도:

• 변환 결과 캐싱을 위한 커스텀 캐시 백엔드 지원
• cacheStores: (MetroCache) => [new CustomStore()] 형태로 MetroCache를 주입받아 커스텀 스토어 생성
• FileStore 외에도 메모리 캐시, Redis 등 다양한 캐시 백엔드 지원

Bungae에서 제외하는 이유:

• Bun은 자체 캐시 시스템을 제공하거나 다른 방식으로 캐시를 관리할 수 있음
• 롤리팝도 자체 캐시 시스템(FileSystemCache)을 사용하며 Metro의 cacheStores 패턴을 사용하지 않음
• Bun의 내장 기능을 활용하는 것이 더 효율적

2. YAML config 지원

Metro에서의 용도:

• 레거시 프로젝트 호환성: 과거에 YAML config를 사용하던 프로젝트 지원
• Deprecated 상태: 경고 메시지를 표시하며 JavaScript config로 마이그레이션을 권장

Bungae에서 제외하는 이유:

• 레거시 지원이 필요 없음 (새로운 프로젝트)
• JavaScript/TypeScript config만 지원해도 충분
• 롤리팝도 YAML을 지원하지 않음
• Metro에서도 deprecated 상태이므로 새 프로젝트에서 구현할 필요 없음

참고: Metro 코드에서 YAML 지원은 다음과 같이 deprecated 처리되어 있습니다:

Copyconsole.warn(
  'YAML config is deprecated, please migrate to JavaScript config (e.g. metro.config.js)',
);

Reference

• Metro: reference/metro/packages/
• Rollipop: reference/rollipop/packages/rollipop/