<div id="readability-page-1" class="page"><div aria-label="Content">
                    
            
                    <p>Nx가 Bun을 공식 지원하기 전에 도입했다면 마주칠 수 있는 문제들과 해결 방법</p>
            
                    
                    <ul id="markdown-toc">
  <li><a href="#들어가며" id="markdown-toc-들어가며">들어가며</a></li>
  <li><a href="#배경" id="markdown-toc-배경">배경</a>    <ul>
      <li><a href="#nx-버전별-bun-지원-범위" id="markdown-toc-nx-버전별-bun-지원-범위">Nx 버전별 Bun 지원 범위</a></li>
    </ul>
  </li>
  <li><a href="#마주친-문제들" id="markdown-toc-마주친-문제들">마주친 문제들</a>    <ul>
      <li><a href="#문제-1-nx가-bun-대신-yarn을-사용하려-함" id="markdown-toc-문제-1-nx가-bun-대신-yarn을-사용하려-함">문제 1: Nx가 Bun 대신 Yarn을 사용하려 함</a>        <ul>
          <li><a href="#문제-상황" id="markdown-toc-문제-상황">문제 상황</a></li>
          <li><a href="#원인" id="markdown-toc-원인">원인</a></li>
          <li><a href="#해결-과정" id="markdown-toc-해결-과정">해결 과정</a></li>
        </ul>
      </li>
      <li><a href="#문제-2-webpack-빌드-시-lock-file-파싱-실패" id="markdown-toc-문제-2-webpack-빌드-시-lock-file-파싱-실패">문제 2: webpack 빌드 시 lock file 파싱 실패</a>        <ul>
          <li><a href="#문제-상황-1" id="markdown-toc-문제-상황-1">문제 상황</a></li>
          <li><a href="#재현-조건" id="markdown-toc-재현-조건">재현 조건</a></li>
          <li><a href="#원인-1" id="markdown-toc-원인-1">원인</a></li>
          <li><a href="#해결-과정-1" id="markdown-toc-해결-과정-1">해결 과정</a></li>
          <li><a href="#bunlockb--bunlock-전환-배경" id="markdown-toc-bunlockb--bunlock-전환-배경">bun.lockb → bun.lock 전환 배경</a></li>
        </ul>
      </li>
    </ul>
  </li>
  <li><a href="#결과" id="markdown-toc-결과">결과</a></li>
  <li><a href="#배운-점" id="markdown-toc-배운-점">배운 점</a>    <ul>
      <li><a href="#공식-미지원-도구-조합을-쓸-때-확인할-것" id="markdown-toc-공식-미지원-도구-조합을-쓸-때-확인할-것">공식 미지원 도구 조합을 쓸 때 확인할 것</a></li>
    </ul>
  </li>
  <li><a href="#마치며" id="markdown-toc-마치며">마치며</a></li>
</ul>

<p><img src="http://thefarmersfront.github.io/post-img/nx-bun-migration/nx-bun-thumb.png" alt="Nx에서 Bun을 더 잘 사용하기 - 썸네일 이미지"></p>

<p>
  로고 출처: <a href="https://nx.dev/brands" target="_blank">Nx</a> © Nx | <a href="https://bun.sh/press-kit" target="_blank">Bun</a> © Anthropic
</p>

<h2 id="들어가며">들어가며</h2>

<p><strong>이 글의 핵심</strong>: 공식 지원 시작이 곧 프로덕션 준비 완료를 의미하지는 않습니다. Nx 문서에는 19.5부터 Bun 공식 지원이라고 적혀 있지만, 실제로 안정적으로 사용하려면 21.4+가 필요했습니다. 이 글에서는 그 과정에서 마주친 문제들과 해결 방법을 공유합니다.</p>

<h2 id="배경">배경</h2>

<p>핀테크그룹 프론트엔드에서는 모노레포 관리 도구로 <strong>Nx</strong>를 사용하고 있습니다. 2024년 3월에 패키지 매니저를 pnpm에서 <strong>Bun</strong>으로 변경했고, 이후 계속 사용 중입니다. 런타임은 Node.js를 그대로 유지하고 있어 Bun은 순수하게 패키지 매니저로 활용하고 있습니다.</p>

<p>최근 의존성 업그레이드와 빌드 최적화를 위해 다음과 같이 마이그레이션했습니다.</p>

<table>
  <thead>
    <tr>
      <th>항목</th>
      <th>Before</th>
      <th>After</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Nx</td>
      <td>18.3.3</td>
      <td>21.4+</td>
    </tr>
    <tr>
      <td>Bun</td>
      <td>1.0.33</td>
      <td>1.2.x</td>
    </tr>
    <tr>
      <td>Lock file</td>
      <td>bun.lockb (바이너리)</td>
      <td>bun.lock (텍스트)</td>
    </tr>
  </tbody>
</table>

<h3 id="nx-버전별-bun-지원-범위">Nx 버전별 Bun 지원 범위</h3>

<table>
  <thead>
    <tr>
      <th>Nx 버전</th>
      <th>Bun 지원</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>18.x</td>
      <td>미지원</td>
    </tr>
    <tr>
      <td>19.5+</td>
      <td>공식 지원</td>
    </tr>
    <tr>
      <td>21.4+</td>
      <td>bun.lock 파싱 개선</td>
    </tr>
  </tbody>
</table>

<p>Nx 18 + Bun 조합은 당시로서는 꽤 도전적인 선택이었습니다. <strong>Nx가 Bun을 공식 지원하기 시작한 건 19.5부터</strong>였기 때문입니다. 그럼에도 <a href="https://bun.sh/" target="\_blank">Bun 공식 벤치마크</a>에서 pnpm 대비 17배, npm 대비 29배, Yarn 대비 33배 빠른 의존성 설치 속도를 주장하고 있어 충분히 시도해볼 만한 가치가 있다고 판단했습니다. 벤치마크는 환경에 따라 달라질 수 있으며, 우리 프로젝트에서는 실제로 약 60% 빌드 시간 단축을 확인했습니다.</p>

<table>
  <thead>
    <tr>
      <th>측정 항목</th>
      <th>pnpm</th>
      <th>Bun</th>
      <th>개선</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>의존성 설치 + 빌드 (<code>nx build web</code>)</td>
      <td>1분 46초</td>
      <td>42초</td>
      <td><strong>약 60% 단축</strong></td>
    </tr>
  </tbody>
</table>

<blockquote>
  <p>측정 환경: MacBook Pro (M2 Pro, 32GB RAM), Nx 및 node_modules 캐시 삭제 후 cold start 기준 10회 측정 평균값</p>
</blockquote>

<p>도입 전 POC에서 큰 이상이 없었고, 리그레션 QA도 무난히 통과했습니다. 공식 지원이 아니라는 리스크보다 Bun의 빠른 설치 속도라는 이점이 훨씬 컸기에 프로덕션에도 적용했습니다.</p>

<p>다만 공식 미지원이라는 점은 여전히 리스크였습니다. Nx가 Bun을 공식 지원하는 버전이 나오면 마이그레이션해야겠다는 백로그를 늘 가지고 있었고, 이번에 드디어 진행하게 되었습니다.</p>

<h2 id="마주친-문제들">마주친 문제들</h2>

<h3 id="문제-1-nx가-bun-대신-yarn을-사용하려-함">문제 1: Nx가 Bun 대신 Yarn을 사용하려 함</h3>

<h4 id="문제-상황">문제 상황</h4>

<p>우리 프로젝트는 패키지 매니저로 <strong>Bun</strong>을 사용하고 있었습니다. 로컬 머신에도 Yarn은 설치되어 있지 않았죠.</p>

<p>그런데 <code>nx migrate</code>를 실행하니 <strong>Nx가 Yarn으로 패키지를 설치하려고 시도</strong>했습니다. Yarn이 설치되어 있지 않으니 당연히 실패했고, <strong>yarn을 찾을 수 없다는 에러</strong>가 발생했습니다.</p>

<p>분명 Bun을 쓰고 있는데, 왜 Nx는 Yarn을 사용하려고 했을까요?</p>

<h4 id="원인">원인</h4>

<p>Nx는 <strong>루트의 lock file 존재 여부</strong>로 패키지 매니저를 감지합니다.</p>

<p>문제는 두 가지였습니다:</p>

<ol>
  <li><strong>Nx 18.x는 Bun을 공식 지원하지 않음</strong>
    <ul>
      <li>감지 우선순위: <code>yarn.lock</code> → <code>pnpm-lock.yaml</code> → <code>package-lock.json</code> (<a href="https://github.com/nrwl/nx/blob/18.3.3/packages/nx/src/utils/package-manager.ts" target="\_blank">소스 코드</a>)</li>
      <li><code>bun.lockb</code>는 감지 대상에 포함되지 않음</li>
    </ul>
  </li>
  <li><strong>우리 프로젝트에</strong> <code>yarn.lock</code>이 존재
    <ul>
      <li>Bun 도입 초기, 호환성 이슈에 대비해 <code>yarn.lock</code>도 함께 생성하도록 설정해둔 상태</li>
    </ul>
  </li>
</ol>

<div><pre><code><span># bunfig.toml</span>
<span>[install.lockfile]</span>
<span># whether to save a non-Bun lockfile alongside bun.lockb</span>
<span># only "yarn" is supported</span>
<span>print</span> <span>=</span> <span>"yarn"</span>  <span># bun install 시 yarn.lock도 함께 생성 (호환성 이슈 대비)</span>
</code></pre></div>

<p>실제 패키지 매니저는 Bun이었지만, <code>yarn.lock</code> 파일이 존재했기 때문에 Nx는 "이 프로젝트는 Yarn을 사용한다"고 판단한 것입니다.</p>

<h4 id="해결-과정">해결 과정</h4>

<p>Bun을 공식 지원하는 Nx 19.5 이상으로 올라가야 권장 방법에 가까운 마이그레이션이 가능합니다. 하지만 그러려면 일단 18 → 19를 넘어가야 했죠.</p>

<p>그래서 <strong>마이그레이션 당시에만</strong> <code>yarn.lock</code>을 임시로 제거했습니다. 실제 의존성 트리는 <code>bun.lockb</code>가 관리하고 있었고, <code>yarn.lock</code>은 Bun 호환성 문제 발생 시를 대비한 fallback용으로만 유지하던 파일이었습니다. 따라서 제거해도 의존성 관리에는 영향이 없었습니다.</p>

<p>Nx가 감지할 lock file이 없으니 npm으로 fallback되어 마이그레이션을 정상 진행했고, 19.5+까지 올린 뒤에는 Bun 공식 지원을 받을 수 있게 되었습니다. Nx 19.5+에서는 <code>bun.lock</code> 또는 <code>bun.lockb</code>만 있으면 자동으로 Bun을 인식하기 때문에, 별도의 설정 없이도 정상 동작합니다.</p>

<h3 id="문제-2-webpack-빌드-시-lock-file-파싱-실패">문제 2: webpack 빌드 시 lock file 파싱 실패</h3>

<h4 id="문제-상황-1">문제 상황</h4>

<p>Nx 19로 마이그레이션 후 webpack 기반 애플리케이션 빌드에서 다음 오류가 발생했습니다.</p>

<div><pre><code>HookWebpackError: Cannot <span>read </span>properties of undefined <span>(</span>reading <span>'data'</span><span>)</span>
</code></pre></div>

<h4 id="재현-조건">재현 조건</h4>

<ul>
  <li>Nx 19.x</li>
  <li>Bun 1.0.33 (<code>bun.lockb</code> 사용)</li>
  <li><code>@nx/webpack</code> executor + <code>generatePackageJson: true</code></li>
</ul>

<div><pre><code><span>// project.json</span><span>
</span><span>{</span><span>
  </span><span>"build"</span><span>:</span><span> </span><span>{</span><span>
    </span><span>"executor"</span><span>:</span><span> </span><span>"@nx/webpack:webpack"</span><span>,</span><span>
    </span><span>"options"</span><span>:</span><span> </span><span>{</span><span>
      </span><span>"generatePackageJson"</span><span>:</span><span> </span><span>true</span><span> </span><span>// 이 옵션이 문제 유발</span><span>
    </span><span>}</span><span>
  </span><span>}</span><span>
</span><span>}</span><span>
</span></code></pre></div>

<h4 id="원인-1">원인</h4>

<p>Nx는 빌드 산출물의 <code>package.json</code>을 생성하기 위해 <strong>프로젝트 그래프의 External Node 메타데이터</strong>를 읽습니다. External Node란 프로젝트 의존성 그래프에서 외부 npm 패키지를 나타내는 노드로, 버전 정보와 의존 관계를 담고 있습니다. 구 버전 Bun의 <code>bun.lockb</code>(바이너리 형식)에서 이 메타데이터 해석이 누락되는 경우가 있었습니다.</p>

<h4 id="해결-과정-1">해결 과정</h4>

<p>해당 문제를 빠르게 조치하기 위해 몇 가지 우회 방법을 검토했습니다:</p>

<ul>
  <li><code>generatePackageJson: false</code>로 변경 → 배포 환경에서 별도 스크립트로 package.json 생성 필요</li>
  <li>커스텀 webpack 플러그인으로 메타데이터 주입 → 유지보수 부담 증가</li>
</ul>

<p>우회는 가능했지만, 별도 스크립트 유지보수와 Nx 업그레이드 시 호환성 검증 부담을 고려하면 기술 부채 리스크가 더 컸습니다. 마침 팀에서 <strong>Storybook 9 마이그레이션</strong>도 검토하고 있었습니다. Storybook 9의 Nx 공식 지원 최소 버전이 <a href="https://nx.dev/blog/nx-21-2-release" target="\_blank">Nx 21.2</a>였고, Bun과 Nx를 함께 올리면 자연스럽게 해결되는 이슈였습니다. 여러 상황이 맞아떨어진 덕분에, 우회하기보다 마이그레이션하기로 결정했습니다.</p>

<p>결과적으로 해결 방법은 다음과 같습니다:</p>

<ol>
  <li><strong>Bun 업그레이드</strong>: 1.2.x로 올려 <code>bun.lockb</code> → <code>bun.lock</code> 전환</li>
  <li><strong>Nx 업그레이드</strong>: 21.4+로 업그레이드 (bun.lock 파싱 개선 포함)</li>
</ol>

<blockquote>
  <p>참고: <a href="https://github.com/nrwl/nx/issues/32656#issuecomment-3265846484" target="\_blank">nrwl/nx#32656</a></p>
</blockquote>

<h4 id="bunlockb--bunlock-전환-배경">bun.lockb → bun.lock 전환 배경</h4>

<p>Bun 1.2.x로 업그레이드하면 lock file이 <code>bun.lockb</code>(바이너리)에서 <code>bun.lock</code>(텍스트, JSONC 형식)으로 바뀝니다. 기존 바이너리 형식은 속도를 위한 선택이었지만 여러 문제가 있었습니다:</p>

<table>
  <thead>
    <tr>
      <th>문제</th>
      <th>설명</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>PR 리뷰 불가</td>
      <td>바이너리라 diff를 볼 수 없음</td>
    </tr>
    <tr>
      <td>Merge 충돌</td>
      <td>수동 해결이 거의 불가능</td>
    </tr>
    <tr>
      <td>도구 호환성</td>
      <td>Nx, Dependabot 등이 파싱 불가</td>
    </tr>
  </tbody>
</table>

<p>텍스트 형식으로 전환되면서 외부 도구들이 lock file을 정상적으로 파싱할 수 있게 되었고, Nx의 External Node 메타데이터 해석 문제도 해결됩니다.</p>

<blockquote>
  <p>흥미롭게도 텍스트 형식 전환 이후에도 내부 최적화(Structure of Arrays, Streaming Parsing 등) 덕분에 약 30% 성능을 개선했다고 합니다. 자세한 내용은 <a href="https://bun.com/blog/bun-lock-text-lockfile" target="\_blank">Bun 블로그</a>를 참고하세요.</p>
</blockquote>

<h2 id="결과">결과</h2>

<p>마이그레이션 완료 후 측정한 수치입니다.</p>

<table>
  <thead>
    <tr>
      <th>항목</th>
      <th>Before</th>
      <th>After</th>
      <th>개선</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>CI 파이프라인</td>
      <td>13분 30초</td>
      <td>11분 40초</td>
      <td><strong>-14%</strong></td>
    </tr>
    <tr>
      <td>Artifact 크기</td>
      <td>330MB</td>
      <td>280MB</td>
      <td><strong>-15%</strong></td>
    </tr>
  </tbody>
</table>

<blockquote>
  <p>측정 환경: GitLab Runner, 5회 실행 평균. 수치는 10 단위에서 반올림.</p>
</blockquote>

<p>정량적 개선 외에도 다음과 같은 변화가 있었습니다:</p>

<ul>
  <li>기존 <code>bun.lockb</code> + <code>yarn.lock</code> 이중 관리에서 <code>bun.lock</code> 단일 파일로 통합</li>
  <li><code>bun.lock</code>이 텍스트 형식으로 바뀌면서 Dependabot PR의 diff 확인 가능</li>
  <li>Bun 공식 지원으로 향후 Nx 업그레이드 시 호환성 걱정 감소</li>
  <li>Storybook 9 마이그레이션을 위한 Nx 버전 요구사항 충족</li>
</ul>

<h2 id="배운-점">배운 점</h2>

<p>막히는 지점에서는 오픈소스 코드를 직접 확인하는 게 답일 때가 있었습니다. Nx의 패키지 매니저 감지 로직을 직접 보고 나서야 왜 <strong>bun.lockb가 있는데도 Yarn으로 fallback하는가</strong>를 이해할 수 있었습니다. 예전이라면 코드를 찾아보거나 검색하는 데 시간이 오래 걸리고 진입 장벽도 있었겠지만 AI를 활용해서 실제 소스 코드와 issue tracker 등을 더욱 빠르게 탐색할 수 있었습니다.</p>

<p>메이저 업그레이드는 미루지 않는 게 낫습니다. 안정화 시점이 확인되면 백로그에 넣어 주기적으로 진행하면, 여러 이슈가 한꺼번에 터지는 것을 막을 수 있습니다. 이번 마이그레이션 과정은 쉽지 않았지만, 빌드 시간 60% 단축, CI 파이프라인 14% 개선 같은 정량적 성과와 함께 PR 리뷰가 가능해진 점, Dependabot이 정상 동작하게 된 점 같은 부수적 개선도 얻을 수 있었습니다.</p>

<h3 id="공식-미지원-도구-조합을-쓸-때-확인할-것">공식 미지원 도구 조합을 쓸 때 확인할 것</h3>

<p>공식 지원되지 않는 도구 조합을 사용하면서 예상치 못한 엣지 케이스를 많이 만났습니다. 다음에 비슷한 선택을 할 때는 이런 것들을 미리 확인하려고 합니다:</p>

<ul>
  <li>공식 지원 로드맵이 있는가? (GitHub Discussions, 블로그 등)</li>
  <li>관련 GitHub 이슈가 얼마나 있는가? 해결되고 있는가?</li>
  <li>lock file 호환성이 보장되는가?</li>
  <li>롤백 플랜이 있는가?</li>
</ul>

<p>다음에 또 비슷한 도전을 하게 된다면, 이번 경험을 토대로 더 신중하고 체계적으로 접근할 수 있을 것 같습니다.</p>

<h2 id="마치며">마치며</h2>

<p>이 글이 Nx와 Bun을 함께 사용하시는 분들께 도움이 되었으면 합니다. 리스크가 있는 작업임에도 마이그레이션을 허락하고 지원해주신 핀테크그룹의 김현홍 님, 안재민 님께 감사드립니다. 또한, 매번 글 작성 시 기술 내용 정리에 늘 도움 주시는 최진호 님께도 감사의 말씀을 전하며 글을 마칩니다.</p>

                </div></div>

컬리 기술 블로그

Nx가 Bun을 공식 지원하기 전에 도입했다면 마주칠 수 있는 문제들과 해결 방법

Nx에서 Bun 더 잘 사용하기: Nx 18 -> 21 마이그레이션

댓글