• "캐시 hit"이 성공 신호가 아닐 수 있다는 것과, 그것을 대조군으로 증명하는 방법을 배웁니다
• Next.js 빌드 캐시가 basePath 같은 config 변화에 어떻게 반응하는지 이해합니다
• 파일이 아닌 입력(환경변수)이 왜 캐시 키에서 구조적으로 누락되는지 알게 됩니다

들어가며

CI 로그의 캐시 복원 스텝은 초록불이었습니다. 캐시 hit, 67MB 복원 완료. 그런데 빌드 시간이 전혀 줄지 않았습니다. 캐시가 있는 빌드가 4.0분, 캐시가 아예 없는 빌드가 3.9분이었습니다.

캐시는 매번 내려왔고, 매번 통째로 버려지고 있었습니다. 저는 이 두 줄을 한참 그냥 지나쳤습니다.

이 글은 그 원인을 좁혀 캐시 키 한 조각으로 고치기까지의 기록입니다(facebook/astryx #3864).

제일 느린 job이 이미 캐시를 쓰고 있었습니다

문제의 job은 sandbox라는 Next.js 앱을 정적 export하는 빌드입니다. PR CI에서 제일 느렸고, 약 4분이 걸렸습니다. 이걸 줄이는 게 과제였습니다.

그런데 이 job은 이미 캐시를 쓰고 있었습니다. apps/sandbox/.next/cache를 actions/cache로 복원했고, 복원은 매번 성공했습니다. 캐시가 있는데, 왜 매번 4분인가.

"캐시 hit"은 성공 신호가 아닙니다

가설을 세우기 전에 숫자부터 모았습니다. 세 개의 실제 run을 비교했습니다.

같은 캐시 키에 같은 hit인데 main은 64초, PR은 4.0분입니다. 그리고 PR의 4.0분은 캐시가 아예 없는 대조군 3.9분과 구분되지 않습니다.

캐시가 죽었는지 살았는지는 hit/miss 로그로 알 수 없습니다. hit 이후의 실제 컴파일 시간을 콜드 run과 비교해야 알 수 있습니다.

main과 대조군은 비교의 양 끝입니다. 64초는 복원된 캐시가 실제로 재사용된 시간이고, 3.9분은 캐시 없이 콜드로 컴파일한 시간입니다. PR의 4.0분이 어느 쪽에 붙는지만 보면 됩니다. 둘 중 하나만 있었다면 진단이 안 됐을 겁니다. 콜드만 있으면 "이 프로젝트는 원래 4분짜리군"으로 끝나고, main만 있으면 "PR은 뭔가 더 하니까 느리겠지"로 끝납니다.

캐시는 두 단계를 거칩니다

여기서 "캐시 키가 어긋났다"고 읽으면 방향이 반대가 됩니다. 키는 정확히 맞았습니다. 맞은 것이 문제였습니다.

캐시를 확인하는 곳이 두 군데이기 때문입니다.

actions/cache는 tarball을 풀어주는 일만 합니다. 그 안의 내용이 이번 빌드에 쓸모 있는지는 알지 못하고, 알 방법도 없습니다. 유효성 판단은 전적으로 키를 짠 사람의 몫입니다.

Next.js는 압니다. webpack의 persistent cache에는 그 캐시를 구울 때의 resolved config(설정 파일이 아니라, 환경변수까지 반영된 빌드 시점의 최종 설정값) 지문이 함께 저장되고, 복원본을 열 때 지금 값과 대조합니다.

그래서 로그에 에러가 한 줄도 없었던 겁니다. 두 단계 모두 명세대로 정확히 동작했습니다. 고장난 부품은 하나도 없고, 문제는 두 단계 사이에 있었습니다.

basePath가 다르면 Next.js는 캐시를 버립니다

캐시 키는 이랬습니다.

nextjs-sandbox-<pnpm-lock 해시>-<packages/core/dist 해시>

빌드 입력을 잘 반영한 키처럼 보입니다. 의존성이 바뀌면 갈리고, core 산출물이 바뀌면 갈립니다. 그런데 키에 안 들어간 입력이 하나 있었습니다. PR 빌드와 main 빌드는 basePath가 다릅니다.

• PR: SANDBOX_BASE_PATH=/<repo>/pr/<n>/sandbox
• main: /<repo>/sandbox

이건 실수가 아니라 필연입니다. PR 프리뷰는 GitHub Pages의 <owner>.github.io/<repo>/pr/<n>/sandbox/ 경로에 배포됩니다. 그 prefix 없이 빌드하면 루트 절대 경로로 나가는 에셋 URL이 전부 404가 나서 프리뷰의 스타일과 JS가 통째로 깨집니다.

앞에서 말한 "지문"의 실체가 이것입니다. Next.js는 config 전체가 아니라 컴파일 결과를 바꾸는 값들만 골라 버전 문자열로 이어 붙이는데, basePath가 그 한 항목입니다.

cache.version = <Next.js 버전>|{"basePath":"/<repo>/sandbox","trailingSlash":true,…}

main이 구운 캐시에는 main의 basePath가 박힌 문자열이 기록돼 있으니, PR이 여는 순간 대조가 어긋납니다 — 한 글자라도 다르면 통째로 버리고, 부분 재사용은 없습니다. 복원한 67MB는 처음부터 순수한 다운로드 낭비였습니다.

이 폐기는 버그가 아니라 안전장치입니다. Next.js가 config 지문을 대조하지 않았다면 결과는 느린 빌드가 아니라 잘못된 배포였을 겁니다. main용 basePath로 컴파일된 에셋이 PR 프리뷰로 나가 링크가 전부 404가 나는데, CI는 4분이 아니라 40초에 끝나서 "최적화가 잘 됐다"는 인상까지 줬을 겁니다. 느린 쪽이 오히려 다행이었습니다.

hit으로 기록되면 저장도 못 합니다

여기서 끝이었으면 "쓸데없이 67MB 받는 낭비" 정도였을 겁니다. 진짜 문제는 두 번째였습니다. actions/cache는 primary key에 hit이 나면 이 로그를 남기고 저장 단계를 건너뜁니다.

Cache hit occurred on the primary key, not saving.

캐시 액션 입장에선 합리적입니다. 이미 그 키로 캐시가 있으니 다시 올릴 이유가 없으니까요. 그런데 이 상황에서는 결과가 최악입니다.

PR은 main의 죽은 캐시로 "hit"을 받습니다. → 저장 단계가 건너뛰어집니다. → PR은 자기 basePath에 맞는 캐시를 영원히 만들 수 없습니다. → 다음 푸시에서도 똑같이 죽은 캐시를 받고 콜드 컴파일을 합니다.

CI 러너는 매 run 새 기계라, run 사이에 살아남는 유일한 통로는 캐시 업로드뿐입니다. 콜드 컴파일의 부산물로 러너 디스크에는 PR basePath에 맞는 진짜 캐시가 생기지만, 저장이 스킵되니 러너와 함께 증발합니다. 다음 푸시는 빈 디스크에서 또 main의 캐시를 받습니다.

캐시가 있는데 없는 것보다 나쁜 상태가 됐습니다. 내려받는 시간은 쓰고, 빌드는 매번 콜드로 돌고, 올바른 캐시가 생기는 것까지 막습니다.

main이 멀쩡했던 이유도 여기서 자명해집니다. main은 자기가 구운 것을 자기가 꺼내 씁니다. basePath가 같으니 Next.js의 대조를 통과하고, 그래서 64초입니다. 뒤집어 말하면 miss를 내고 저장할 기회는 사실상 main에게만 있었으니, main만 쓸 수 있는 캐시가 공유 키라는 공용 이름으로 모두에게 배포되고 있던 셈입니다.

예외는 있었습니다. PR이 의존성이나 core 산출물을 바꾸면 키가 main이 점유하지 않은 새 값이 돼 저장이 실행됩니다. 그래서 core를 건드리는 PR은 다음 푸시부터 웜이었고, sandbox나 문서만 고치는 PR만 영원히 콜드였습니다 — 증상이 PR마다 달라 이 버그가 오래 눈에 띄지 않은 이유입니다.

파일이 아닌 입력은 키에서 저절로 빠집니다

그런데 왜 basePath는 키에 없었을까요. 부주의라기보다, 키를 짜는 기본 방식이 원래 놓치는 입력이기 때문입니다.

key: nextjs-sandbox-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('packages/core/dist/**') }}

캐시 키는 관습적으로 hashFiles()로 짭니다. 그런데 hashFiles()는 파일 시스템만 봅니다. SANDBOX_BASE_PATH처럼 환경변수로 들어오는 입력은 빌드 결과를 아무리 좌우해도 여기 잡히지 않습니다. 사람이 손으로 적어 넣지 않는 한 구조적으로 누락되고, 그 누락은 눈에 보이지도 않습니다 — 키 문자열을 아무리 들여다봐도 "빠진 것이 있다"는 사실 자체를 알 수 없기 때문입니다.

같은 이유로, 이 문제는 의존성 캐시에서는 생기지 않습니다. pnpm store의 내용을 정하는 입력은 lockfile 하나뿐이고 그건 파일이니, hashFiles()만으로 충분합니다. 키가 좀 헐거워도 패키지는 content-addressed라 잘못된 것을 집어올 수 없습니다. 문제가 생기는 쪽은 빌드 산출물 캐시입니다. 컴파일 결과에는 그때의 config·환경변수·플래그가 전부 반영돼 있는데, 키에는 보통 lockfile과 소스 해시만 들어갑니다. 이 버그는 그 차이에서 생깁니다.

빠진 입력을 키에 넣습니다

고치는 diff는 허무할 정도로 짧습니다. +17/−1인데 그중 16줄은 근거를 적은 주석이고, 실제로 바뀐 건 이 한 줄입니다.

- key: nextjs-sandbox-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('packages/core/dist/**') }}
+ key: nextjs-sandbox-pr${{ github.event.pull_request.number }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('packages/core/dist/**') }}

pr<n> 한 조각을 넣은 게 전부입니다. PR 번호는 basePath를 결정하는 값입니다. 키에 저절로 들어가지 않던 입력(환경변수)을, 키에 직접 적을 수 있는 대리 값으로 바꿔 넣은 셈입니다. 이제 각 PR은 첫 푸시에서 자기 캐시를 굽고, 이후 푸시에서 진짜 워밍 캐시를 씁니다. main은 원래부터 자기가 구운 캐시를 자기가 꺼내 쓰고 있었으니 그대로 둡니다.

restore-keys는 넣지 않았습니다

키를 세분화하면 자연스럽게 "그럼 restore-keys로 접두사만 맞는 캐시라도 복원하자"는 생각이 따라옵니다. 일부러 넣지 않았습니다. 이 저장소에는 이력이 있습니다 — Next.js 모듈 캐시에는 @astryxdesign/core의 resolved export graph가 함께 구워지는데, 접두사만 맞는 캐시를 복원하면 다른 export 형태로 빌드된 것이 들어와 조용히 잘못된 빌드가 나옵니다(#2941의 머지 후 배포가 이 방식으로 깨졌습니다). 이 저장소의 정책은 "캐시 hit률 최대화"가 아니라 "틀린 빌드를 절대 만들지 않기" 입니다. 키가 바뀌면 콜드 리빌드가 나는 편이 안전합니다.

고쳤더니 hit률이 떨어집니다

이 수정이 제대로 됐다는 신호는 miss입니다. 각 PR의 첫 푸시는 이제 반드시 miss니까요. 그래서 테스트 플랜에 일부러 체크하지 않은 항목을 하나 남겼습니다 — "첫 푸시의 miss가 수정이 작동한다는 증거다. 재푸시에서 컴파일이 64초 수준으로 떨어지는지 확인할 것." 이걸 적어두지 않으면 다음 사람이 hit률 그래프만 보고 "캐시가 안 먹네" 하며 되돌려 놓습니다.

그 항목은 이 PR 자신에서 닫혔습니다. 첫 푸시(run 29182165678)는 nextjs-sandbox-pr3864-… 키로 miss가 나서 4.2분을 컴파일하고 캐시를 저장했고, 28분 뒤 재푸시(run 29182864149)는 그 키를 복원해 60초에 컴파일했습니다 — main의 64초와 같은 수준입니다.

머지 후, 캐시가 걸린 재푸시 기준으로 PR CI 전체 시간은 8분 56초에서 5분 10초가 됐습니다. 다만 23분 간격으로 머지된 병렬화 PR(#3811)의 효과가 섞여 있어, 캐시 수정만의 몫은 따로 떼어 말할 수 없습니다.

남은 한계: 첫 푸시는 여전히 콜드입니다

pr 키에도 한계가 남습니다. 두 번째 푸시부터는 다시 primary hit이라 저장이 스킵되고, 그 PR의 캐시는 첫 푸시 때 만든 것에 머뭅니다. 흔한 해법은 키에 커밋 SHA를 붙여 hit을 없애고(그러면 매번 저장됩니다) 복원은 restore-keys에 맡기는 것입니다. 접두사에 pr<n>과 core 해시를 남기면(nextjs-sandbox-pr<n>-<lock>-<core>-) 여기서도 쓸 수 있고, #2941 사고와도 부딪히지 않습니다. 이번 PR은 저장소에 적힌 no-restore-keys 정책을 열지 않고 그 안에서 고치는 쪽을 택했습니다.

SHA를 붙였더라도 달라지지 않는 것이 하나 있습니다. basePath가 PR마다 다른 한, 첫 푸시는 어떤 키로도 웜이 될 수 없습니다. GitHub Actions 캐시는 브랜치 단위라 PR run이 읽을 수 있는 건 자기 브랜치와 base 브랜치(main)의 캐시뿐입니다. 첫 푸시에는 자기 캐시가 없으니 남는 건 main 캐시 하나인데, 그건 basePath가 달라 쓸 수 없습니다.

그러니 근본 해법은 키 바깥에 있습니다. main 캐시를 PR 빌드에서도 쓸 수 있게 만드는 것 — basePath를 빌드 입력에서 빼는 것입니다. 에셋을 상대 경로로 내보내거나 프리뷰를 서브도메인으로 배포하면 basePath가 어디서나 같아지고, 키를 가를 이유가 사라집니다. 이번 PR은 워크플로 파일만 고치는 키 수정을 택했고, 첫 푸시의 콜드는 고친 게 아니라 감수한 것입니다. 순서만 기억해 두면 됩니다 — "캐시 키를 어떻게 짤까"보다 "이 입력이 정말 달라야 하나"를 먼저 묻는 것입니다.

이 패턴을 다른 저장소에 옮긴다면

캐시 스텝마다 이 네 가지를 확인하면 됩니다.

• 키에 넣을 것 — 산출물을 바꾸는 입력이 전부 들어갔나. hashFiles()는 파일만 보므로 환경변수·플래그·툴체인 버전은 손으로 넣어야 한다
• 같은 캐시를 쓰면 안 되는 빌드 — PR과 main, OS, 런타임 버전, matrix 조합처럼 서로 캐시를 나눠 써야 하는 빌드가 키 접두사로 구분되나
• restore-keys — 웜을 최대화할지, 정확성을 위해 콜드를 감수할지. 쓴다면 위의 구분이 접두사에도 남아 있나
• 살아 있는지 — Cache restored successfully 다음 줄의 소요 시간이 그 캐시를 지웠을 때와 유의미하게 다른가. 같으면 그 캐시는 죽어 있다

앞의 셋은 키를 읽어서 확인할 수 있지만, 빠진 입력은 키 문자열을 아무리 들여다봐도 보이지 않습니다. 그래서 마지막 항목이 필요합니다.

마치며

캐시 hit은 "키 문자열이 같았다"는 뜻일 뿐이라, 캐시의 생사는 hit 이후의 컴파일 시간을 콜드 대조군과 비교해야 알 수 있습니다. 이번 사례에서 키는 정확히 맞았지만, Next.js가 basePath 다른 캐시를 열어보고 통째로 버리고 있었고, hit으로 기록된 탓에 올바른 캐시가 저장될 기회조차 없었습니다. basePath가 키에서 빠진 것은 부주의가 아니라 hashFiles()가 파일만 보기 때문입니다. 그래서 키에 PR 번호를 넣어, 각 PR이 자기 캐시를 굽게 했습니다.

여러분의 CI에도 캐시 스텝이 있다면, 지금 가장 최근 run의 로그를 열어보세요. 확인은 5분이면 끝납니다. Cache restored successfully 다음 줄의 빌드 시간이 캐시가 없던 시절과 정말로 다른가요. 비슷하게 "hit인데 안 빨라지는" 캐시를 만나신 적 있다면 댓글로 공유해 주세요.

• 근거 PR: facebook/astryx#3864 — perf(ci): key sandbox next cache by PR to stop cross-basepath invalidation · 배경이 된 병렬화 PR: #3811 — perf(ci): build sandbox preview in parallel with storybook (둘 다 2026-07-12 머지)
• 참고 문서: webpack cache.version — 버전이 다르면 캐시를 재사용하지 않는다 · Next.js가 config 값들로 캐시 버전 문자열을 만드는 곳 — build/webpack-config.ts#L2380-L2423 (v16.3.1)

• 매일 쓰는 getByRole('button', {name})이 내부에서 무슨 일을 하는지 알게 됩니다
• "느리다"에서 "무엇이 느린가"로 좁혀가는 방법을 배웁니다
• jsdom의 getComputedStyle이 왜 브라우저와 다르게 비싼지 이해합니다
• 내 프로젝트에서 언제 이 문제를 의심해야 하는지 판단 기준을 얻습니다

병목 좁히기 — 렌더가 아니라 getByRole 쿼리였다

1. 유독 느린 파일 하나

Meta의 디자인 시스템 astryx에서 CI 최적화 작업을 하고 있었습니다.
파이프라인이 오래 걸려서 이것저것 줄여보던 중이었습니다.

이 글의 근거 PR은 facebook/astryx#3816이고, 2026년 7월 12일에 머지되었습니다.
아래 나오는 코드와 수치는 전부 그 PR에서 직접 확인하실 수 있습니다.

그러다 테스트 파일별 실행 시간을 훑어보다가 이상한 걸 발견했습니다.
가장 느린 파일 네 개가 전부 날짜 컴포넌트였습니다.

네 개가 한자리에 몰려 있다는 것부터 우연이 아닌데, 맨 위 파일은 아예 다른 세상에 있습니다. DateInput은 테스트 68개에 5.1초, DateRangeInput은 34개에 34.3초. 테스트 수는 절반인데 시간은 7배입니다.

같은 폴더의, 같은 날짜 입력 컴포넌트입니다. 게다가 이 테스트들은 화면을 그리지 않습니다. jsdom 위에서 마운트하고, 클릭하고, 텍스트를 확인하는 게 전부죠.

그런 일에 1초가 걸릴 이유가 있을까요?

원인은 제가 거의 매일 쓰던 한 줄이었습니다.

2. 렌더 20ms, 쿼리 450ms

느리다는 건 알았지만 무엇이 느린지는 모릅니다. 그래서 테스트 하나를 구간별로 쪼개서 쟀습니다.

const t0 = performance.now();
render(<DateRangeInput />);

const t1 = performance.now();
screen.getByRole('button', {name: 'Open calendar'});

const t2 = performance.now();
console.log('render :', (t1 - t0).toFixed(0), 'ms');
console.log('query  :', (t2 - t1).toFixed(0), 'ms');

render :  20 ms
query  : 450 ms

렌더는 20ms인데 버튼 하나를 찾는 데 450ms. 22배입니다.

컴포넌트를 통째로 만드는 것보다,
이미 만들어진 것 중에서 하나 찾는 게 22배 비싸다?

보통은 반대입니다. 만드는 게 비싸고 찾는 건 쌉니다. 뒤집혔다면 이유가 있습니다. 그 이유는 6장에서 다루고, 지금 확실한 건 하나입니다.

느린 쪽은 렌더가 아니라 쿼리다.

3. 소스를 열어보다

node_modules를 뒤져서 실제 구현을 열었습니다.
@testing-library/dom의 dist/queries/role.js입니다.
다만 아래에는 읽기 편하도록 같은 코드의 원본인 src/queries/role.ts를 인용하겠습니다.

놀랄 만큼 단순했습니다. 그냥 .filter() 체인이었습니다.

// @testing-library/dom v10.4.1 — src/queries/role.ts
Array.from(container.querySelectorAll(makeRoleSelector(role)))
  .filter(/* role 필터 — 이 노드의 role이 정말 맞는가 */)
  .filter(/* aria 필터 — checked, expanded, ... */)
  .filter(element => {
    if (name === undefined) return true;
    return matches(computeAccessibleName(element), element, name, text => text);
    //              ^^^^^^^^^^^^^^^^^^^^ name 필터 — 이름을 계산해서 비교
  })
  .filter(/* description 필터 */)
  .filter(element => {
    return hidden === false ? isInaccessible(element) === false : true;
    //                        ^^^^^^^^^^^^^^ hidden 필터 — 화면에 보이는가
  });

실제 체인은 필터 5개고, 위는 필요한 부분만 남긴 것입니다.

제가 무심코 쓰던 한 줄이 사실은 세 가지 일을 하고 있었습니다.

screen.getByRole('button', {name: 'Open calendar'});
//                ^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^   + 기본값 hidden: false
//                role 필터  name 필터                hidden 필터
//                후보 수집  이름으로 걸러냄          안 보이는 것 제외

여기서 computeAccessibleName은 스크린리더가 읽어주는 그 접근성 이름을 구하는 함수입니다.

그런데 순서가 이상합니다

name 필터가 hidden 필터보다 먼저 옵니다. .filter()는 앞에서부터 실행되니 이런 일이 벌어지죠.

화면에 안 보여서 어차피 hidden 필터에서 걸러질 노드들의 이름을,
안 보인다는 걸 알아내기도 전에 전부 계산한다.

하나 더. .filter()니까 원하는 걸 찾아도 멈추지 않습니다.

그래서 DateRangeInput은요

DateRangeInput
├── 트리거 버튼          ← 내가 찾으려던 것
└── 팝오버 (닫힘)
    └── 2개월치 달력
        └── 날짜 버튼 약 85개   ← 화면에 안 보이지만 DOM에는 그대로

팝오버가 닫혀 있어도 달력은 언마운트되지 않습니다. 그러니 트리거 하나를 찾으려고 getByRole('button', {name})을 부르면, 후보 86개를 모으고 → 전부의 이름을 계산하고 → 이름이 다른 85개를 떨어뜨립니다. 그 85개가 애초에 화면에 없었다는 사실은 어디에도 쓰이지 않습니다.

보이지도 않을 버튼 85개의 이름을, 안 보인다는 걸 알기도 전에 전부 계산하고 있었던 겁니다.

다만 순서가 문제의 전부는 아닙니다. hidden 필터도 결국 후보 하나하나의 스타일을 봐야 하거든요. 이건 4장에서 다시 짚겠습니다.

그럼 450ms를 먹은 건 이름 계산일까요? 확인해봐야죠.

4. 옵션 하나를 뺐더니 450ms가 29ms가 됐다

의심은 의심일 뿐입니다. 재봐야 압니다.

문제는 세 필터가 한 덩어리로 돈다는 겁니다. 프로파일러는 "이 함수가 느리다"까지만 알려주지 셋 중 어느 것인지는 안 갈라줍니다. 방법은 하나뿐입니다. 떼어내고 다시 재는 것.

그래서 하한선부터 만들었습니다. name도 hidden도 없이 후보만 모으면 얼마나 걸리나?

screen.getByRole('button', {name: 'Open calendar'});   // → 450ms
screen.getAllByRole('button', {hidden: true});         // → 29ms  (두 필터 다 끔)

두 옵션이 어떻게 필터를 끄는지는 3장에서 본 소스에 그대로 있습니다. name을 안 주면 이름 계산을 건너뛰고, hidden: true면 가시성 검사를 건너뜁니다. hidden 필터도 결국 스타일을 들여다보는 일이라, 이것까지 꺼야 순수한 바닥값이 나옵니다.

후보 86개를 긁어모으는 것 자체는 29ms면 끝납니다. 나머지 94%는 "이름이 맞는지"와 "보이는지"를 따지는 데 쓰였습니다.

성능 문제를 좁힐 때 제가 배운 게 이겁니다.
한 덩어리로 보이는 것을 쪼개서, 가장 싼 조합의 바닥값부터 만든다.
그 바닥에서 얼마나 올라가는지를 보면 어디가 비싼지 드러납니다.

94%를 한 번 더 쪼개면

방금 그 말대로라면 여기서 멈추면 안 됩니다. 94%를 name과 hidden이 나눠 가졌는데 누가 얼마나 가져갔는지를 아직 모릅니다.

두 옵션이 필터를 따로 켜고 끄니 가를 수 있습니다.

screen.getAllByRole('button', {hidden: true});                        // role만
screen.getAllByRole('button', {name: 'Open calendar', hidden: true}); // role + name
screen.getAllByRole('button');                                        // role + hidden
screen.getByRole('button', {name: 'Open calendar'});                  // 셋 다

같은 구조를 jsdom 27.4.0 · @testing-library/dom 10.4.1로 재현해 넷을 각각 쟀습니다.

이상한 게 보입니다. 셋 다 돌린 261회가 role + name의 256회와 거의 같습니다. 혼자면 176회를 부르는 hidden 필터가 여기선 5회로 끝났다는 뜻이죠.

.filter() 체인이라서 그렇습니다. hidden 필터는 name 필터가 걸러낸 결과를 받는데, 이름이 Open calendar인 버튼은 하나뿐입니다. 86개가 아니라 1개만 검사하는 겁니다.

그 5회는 버튼의 visibility 조기 종료 검사 1회 + 버튼부터 DIV → BODY → HTML까지의 display 4회입니다.

여기서 규칙이 드러납니다.

먼저 오는 필터가 86개 값을 다 치릅니다. 뒤에 오는 필터는 살아남은 것만 봅니다.

그래서 3장의 "순서가 이상하다"에 답이 나옵니다. 순서를 뒤집어봤습니다.

84회가 줄어듭니다. 그런데 3분의 2는 그대로 남습니다. 누가 먼저 오든 86개를 다 훑어야 하니까요.

순서는 낭비를 만들지만, 비용을 만들지는 않습니다.
비용은 "스타일을 봐야 한다"는 사실에서 나옵니다.
그래서 7장의 해법은 순서를 고치지 않습니다. 스타일 조회를 아예 없앱니다.

이름 계산이 비싸다는 것까지는 알았습니다. 그런데 여기서 새로운 질문이 생깁니다.

이름을 구하는 게 왜 그렇게 비싸지?
버튼 안에 있는 글자를 읽어오면 되는 거 아닌가?

저도 그렇게 생각했습니다. 아니었습니다.

원인 — 접근성 이름 계산과 jsdom의 getComputedStyle

5. 접근성 이름은 "보이는 대로 읽은 텍스트"입니다

접근성 이름이 그냥 버튼 안의 글자라면 textContent와 같아야 합니다. 버튼을 하나 만들되 자식 하나를 display: none으로 숨겨두고 확인해봤습니다. jsdom과 dom-accessibility-api(RTL이 내부에서 쓰는 바로 그 라이브러리)만 있으면 직접 돌려볼 수 있습니다.

// npm i jsdom dom-accessibility-api
const {JSDOM} = require('jsdom');
const {computeAccessibleName} = require('dom-accessibility-api');

const dom = new JSDOM(`<!doctype html><body>
  <button id="a"><span style="display: none">지난달</span> <span>15일</span></button>
</body>`);

const button = dom.window.document.getElementById('a');

console.log('textContent     :', JSON.stringify(button.textContent.trim()));
console.log('accessible name :', JSON.stringify(computeAccessibleName(button)));

textContent     : "지난달 15일"
accessible name : "15일"

둘이 다릅니다. 숨겨둔 "지난달"이 접근성 이름에서만 빠졌습니다. 당연한 일이죠. 화면엔 15일만 보이는데 스크린리더가 "지난달 15일"이라 읽으면 틀린 정보니까요.

여기서 하나가 결정됩니다.

접근성 이름을 구하려면 "이 노드가 화면에 보이는가"를 반드시 확인해야 한다.
그리고 그걸 아는 방법은 CSS를 계산해보는 것뿐이다.

display: none이 인라인으로 왔는지, 클래스로 왔는지, 부모에게서 상속됐는지 알 수 없으니까요.

게다가 자식 하나하나를 봐야 합니다

확인 대상은 버튼 자신만이 아닙니다.
dom-accessibility-api 소스를 열어보면 그대로 있습니다.

// dom-accessibility-api v0.6.3 — sources/accessible-name-and-description.ts
function isHidden(node, getComputedStyleImplementation) {
  // ...
  const style = getComputedStyleImplementation(node);
  return (
    style.getPropertyValue('display') === 'none' ||
    style.getPropertyValue('visibility') === 'hidden'
  );
}

// 자식을 순회하면서
const display = isElement(child)
  ? getComputedStyle(child).getPropertyValue('display')
  : 'inline';

isHidden이 스타일 조회를 건너뛰는 건 hidden·aria-hidden 속성이 붙은 노드에서뿐입니다. 그 밖의 노드는 — 멀쩡히 보이는 노드까지 — CSS로 숨겨졌는지 알아내려고 getComputedStyle을 한 번씩 부릅니다. 4장의 256회가 전부 여기서 나옵니다. 다만 8장의 트레이드오프는 CSS로 숨긴 경우에만 발생합니다.

두 번째 조각이 중요합니다. 자식의 display까지 확인하죠. block이면 화면에서 줄이 바뀌니 단어 사이에 공백을 넣어야 하거든요.

즉 이름 계산은 버튼 하나가 아니라 그 안의 모든 노드에게 물어봅니다. 그래서 곱셈이 됩니다.

<button><span>15</span></button>     ← 후보 하나에 3회
   │        │      └─ 자식 display 확인
   │        └─ 자식 isHidden
   └─ 버튼 자신 isHidden

4장에서 쟀던 256회가 이렇게 나온 겁니다. 후보 86개 중 트리거 1개는 자식이 텍스트뿐이라 1회, 나머지 날짜 버튼 85개가 3회씩. 후보 하나당 약 3회입니다. 여기에 hidden 필터가 마지막에 부르는 5회를 더하면 261회가 됩니다.

그런데 아직 이상합니다.
호출이 좀 많다고 450ms가 나올까요? getComputedStyle이 그렇게 비싼 함수였나요?

네. jsdom에서는요.

6. jsdom은 물어볼 때마다 스타일을 새로 조립합니다

먼저 알아둘 게 하나 있습니다. getComputedStyle은 부분적으로 못 만듭니다.

const display = getComputedStyle(el).display;
//              ^^^^^^^^^^^^^^^^^^^^ 표 전체를 만든 다음, 거기서 한 칸을 꺼낸다

개발자도구 Computed 탭에서 "Show all"을 켜면 건드린 적 없는 프로퍼티가 수백 개 나오죠. display 하나가 궁금해도 그 표 전체가 만들어집니다.

jsdom은 그 표를 호출할 때마다 다시 만듭니다

jsdom 구현을 열어봤습니다.

window.getComputedStyle = function (elt) {
  const declaration = new CSSStyleDeclaration();            // 1. 빈 객체를 새로 만들고
  const elementDeclaration = getDeclarationForElement(elt);  // 2. 캐스케이드를 계산해서
  forEach.call(elementDeclaration, p => declaration.setProperty(...));  // 3. 옮겨 담고
  forEach.call(Object.keys(propertiesWithResolvedValueImplemented),
    p => declaration.setProperty(p, getResolvedValue(elt, p)));         // 4. 최종값 계산
  return declaration;
};

2번의 캐스케이드에는 캐시가 있습니다. 그런데 그 바로 옆에 이런 코드가 있습니다.

exports.invalidateStyleCache = elementImpl => {
  if (elementImpl._attached) {
    elementImpl._ownerDocument._styleCache = null;   // 문서 전체 캐시를 통째로 버린다
  }
};

DOM이 바뀌면 문서 전체의 스타일 캐시가 날아갑니다.

테스트는 클릭하고, 입력하고, 리렌더하는 게 일입니다. 그러니까 테스트는 캐시를 계속 부수면서 진행됩니다.

여기서 2장의 의문이 풀립니다

렌더는 20ms인데 쿼리는 450ms. 만드는 것보다 찾는 게 22배 비쌌던 그 이상함이요.

달력과 같은 규모로 버튼 85개를 두고, 스타일시트 규칙 2,000개를 얹어 네 구간을 재봤습니다.

1. 렌더                    9.7 ms
2. 스타일 첫 조회 (콜드)  463.4 ms   ← 렌더의 47배
3. 재조회 (캐시 히트)       8.8 ms   ← 2번의 1/53
4. DOM 한 번 건드린 뒤    266.5 ms   ← 속성 하나 바꿨을 뿐인데 다시 비싸진다

이유는 이겁니다.

브라우저는 화면을 그려야 하니 렌더할 때 스타일을 계산해둡니다.
그래서 나중에 getComputedStyle을 부르면 이미 있는 걸 읽기만 합니다. 거의 공짜죠.

jsdom은 화면을 안 그립니다. 렌더할 때 스타일을 계산할 이유가 없습니다.
그러다 누가 getComputedStyle을 부르면 그제야 처음으로 계산합니다.

비용 청구서가 반대편에 도착하는 겁니다.

그래서 2장에서 render()가 20ms로 찍힌 건 사실이었습니다. 달력 버튼 85개의 스타일 비용이 렌더 청구서에 실리지 않았을 뿐이고, 그 청구서는 처음으로 스타일을 물어본 쪽, 즉 getByRole에게 날아왔습니다.

숫자를 맞춰봅시다

astryx 환경에서 후보 버튼 하나를 처리하는 데 대략 5ms가 들었습니다. 5장에서 셌듯 후보 하나에 getComputedStyle이 약 세 번 불리니, 이 5ms는 그 세 번을 합친 값입니다.

후보 86개 × 후보당 약 5ms ≈ 430ms ≈ 측정값 450ms

다른 걸 고쳐놓고 우연히 빨라지는 일은 생깁니다. 하지만 후보 하나의 비용에서 쌓아올린 값이 전체 측정치와 자릿수까지 맞으면, 그건 우연으로 설명되지 않습니다.

해결 — getComputedStyle을 걷어낸 헬퍼와 그 트레이드오프

7. 같은 알고리즘, 스타일 계산만 제거

원인을 알았으니 방향은 정해집니다. getComputedStyle을 안 부르면 됩니다. 문제는 어떻게 안 부르느냐입니다.

선택지를 셋 놓고 봤습니다.

1. getByTestId로 갈아탄다 — 빨라지지만 접근성 검증을 통째로 포기합니다. 디자인 시스템 테스트에서 이건 후퇴입니다. 탈락.
2. 이름 비교를 직접 구현한다 — 5장에서 봤듯 접근성 이름은 textContent가 아닙니다. aria-label, aria-labelledby, 숨은 자식까지 얹히면 금세 스펙과 어긋납니다. RTL과 다른 답을 내는 헬퍼는 통과해도 믿을 수가 없습니다. 탈락.
3. RTL이 쓰는 라이브러리를 그대로 쓰되 비용만 없앤다 — 채택.

그래서 조건을 이렇게 잡았습니다.

이름을 구하는 알고리즘은 RTL과 똑같이 유지한다.
대신 그 알고리즘이 참조하는 스타일 계산만 갈아끼운다.

다행히 computeAccessibleName은 getComputedStyle 구현을 주입받을 수 있게 열려 있었습니다.

실제로 머지된 코드입니다. (6cfb542에서 보기)

// packages/core/src/__tests__/fastRoleQueries.ts — 핵심만 추린 것

// "전부 다 보인다"고만 대답하는 상수 스텁
const visibleStyleStub: Pick<CSSStyleDeclaration, 'getPropertyValue'> = {
  getPropertyValue: prop =>
    prop === 'display' ? 'block' : prop === 'visibility' ? 'visible' : '',
};

function matchesName(el: Element, name: string | RegExp): boolean {
  const accessibleName = computeAccessibleName(el, {
    getComputedStyle: () => visibleStyleStub as CSSStyleDeclaration,
  });
  return typeof name === 'string' ? accessibleName === name : name.test(accessibleName);
}

export function queryButton(name: string | RegExp): HTMLElement | null {
  return (
    screen
      .queryAllByRole('button', {hidden: true})
      .find(el => matchesName(el, name)) ?? null
  );
}

export function getButton(name: string | RegExp): HTMLElement {
  const el = queryButton(name);
  if (!el) {
    throw new Error(`Unable to find a role=button named ${String(name)}`);
  }
  return el;
}

장치는 셋입니다.

1. {hidden: true} — hidden 필터를 통째로 건너뜁니다. 가시성 검사용 getComputedStyle이 사라집니다.
2. 스타일 스텁 주입 — 이름 계산 안의 getComputedStyle을 상수 응답으로 바꿉니다. 캐스케이드를 계산하는 대신 "block"을 즉시 돌려주니 비용이 0에 수렴합니다.
3. filter가 아니라 find — RTL은 끝까지 다 돌지만 .find()는 찾으면 거기서 멈춥니다. 후보 86개를 끝까지 훑는 대신 첫 매치까지만 봅니다.

호출부는 이렇게 바뀝니다.

- const trigger = screen.getByRole('button', {name: /Range:/});
+ const trigger = getButton(/Range:/);

날짜 컴포넌트 4개 파일에서 41개 호출부를 교체했습니다. 호출부가 짧아진 덕에 테스트 파일 자체는 64줄을 더하고 96줄을 덜어 32줄 줄었지만, 헬퍼 66줄이 새로 생겼으니 저장소 전체로는 늘었습니다(+134 −96). (전체 diff)

같은 파일의 combobox·tooltip·grid 쿼리는 그대로 뒀습니다. 후보가 몇 개 안 되거나 name을 안 쓰면 애초에 싸거든요. 비싼 곳만 바꿔야 팀이 표준 API 대신 사내 헬퍼를 익혀야 하는 부담이 줄어듭니다.

8. 무엇을 포기했나

공짜는 없습니다. 이 헬퍼는 두 가지를 포기했습니다.

포기 1 — 유일성 검사. RTL의 getByRole은 조건에 맞는 요소가 두 개 이상이면 에러를 던집니다. 성가신 기능 같지만 "이 이름의 버튼은 화면에 하나뿐이다"를 테스트가 대신 확인해주는 안전장치죠. .find()는 첫 매치에서 멈추므로 그게 사라집니다. 중복이 생겨도 테스트가 알려주지 않습니다.

포기 2 — 이름의 정확도. 스텁은 display에 항상 "block"이라 대답하니 CSS로 숨긴 노드도 "보인다"고 판정됩니다. 앞서 textContent와 갈렸던 그 버튼을 다시 보죠.

<button><span style="display: none">지난달</span> <span>15일</span></button>

RTL     : "15일"
이 헬퍼 : "지난달 15일"   ← 숨긴 텍스트가 이름에 섞여 들어온다

"접근성 이름은 보이는 대로 읽은 텍스트"라는 원칙이 여기서 깨집니다. getComputedStyle 비용을 없앤 대가로 "보이는 대로"를 포기한 셈입니다.

날짜 버튼은 <button><span>15</span></button> 정도로 단순해서 문제가 없었지만, 다른 코드베이스에 옮길 때는 반드시 확인해야 합니다.

그래서 헬퍼 파일 맨 위 주석에 트레이드오프를 명시해뒀습니다.

Trade-off vs getByRole: first match wins — no tree-wide uniqueness check.

정리하면 이 헬퍼는 "이 파일들에서, 이 조건에서" 안전한 도구입니다.
범용 유틸리티가 아니라 국소 최적화죠. 그래서 테스트 폴더 안에만 두었습니다.

성과와 적용 기준 — 34.3초에서 1.3초로

9. 결과

날짜 컴포넌트 4개 파일, 211개 테스트의 실행 시간입니다.
아래 수치는 PR 본문에 그대로 기록돼 있습니다.

처음의 그 파일은 34.3초에서 1.3초가 됐습니다. 약 26배입니다.

그런데 분모를 봐야 합니다

26배는 파일 하나 이야기입니다. 전체 스위트는 이렇습니다.

26배를 줄였는데 벽시계는 12%만 줄었습니다.

테스트가 여러 워커에 나뉘어 병렬로 돌기 때문입니다. 느린 파일 하나를 34초에서 1.3초로 줄여도, 그 워커가 남는 동안 다른 워커가 여전히 자기 몫을 돌고 있으면 전체는 그만큼 안 줄어듭니다. 가장 오래 걸리는 경로가 따로 있는 거죠.

그러니 이 글의 26배는 "이 병목은 확실히 제거됐다" 는 뜻이지 "CI가 26배 빨라졌다" 는 뜻이 아닙니다.

여기서 강조하고 싶은 게 있습니다.

테스트가 확인하는 동작은 바뀌지 않았습니다.
컴포넌트 코드도 각 테스트의 단언도 손대지 않았고, 전체 5,893개 테스트가 그대로 통과합니다.

바꾼 건 요소를 찾는 방법입니다.
다만 8장에서 적었듯 그 방법에는 대가가 있으니, "검증이 하나도 안 줄었다"고까지 말하면 과장입니다. 유일성 검사가 쿼리에서 빠졌습니다.

그럼 남은 시간은 어디에 있을까요. 그건 쿼리가 아니라 워커에 일을 어떻게 나누느냐의 문제라, 이 글의 범위 밖입니다.

10. 그래서 언제 이걸 의심해야 할까요

여기까지 읽고 getByRole을 걷어내지는 마세요. 대부분의 경우 몇 밀리초면 끝납니다. 문제가 되는 건 특정 조건이 겹칠 때뿐입니다.

RTL이 잘못한 게 아닙니다.
접근성 이름을 스펙대로 정확히 계산하는 것이 RTL의 존재 이유입니다.
비싼 쪽은 jsdom의 getComputedStyle이고, 실제 브라우저에서는 이 비용이 거의 없습니다.

우리가 한 일은 RTL을 고친 게 아니라, {hidden: true}가 허용하는 범위 안에서 테스트 환경에서만 발생하는 비용을 걷어낸 것입니다.

의심 조건

이 네 가지가 동시에 성립하면 확인해볼 만합니다.

1. role 후보가 수십 개 이상 마운트되어 있다 — 달력 그리드, 긴 목록, 데이터 테이블
2. 그중 상당수가 화면에 안 보인다 — 닫힌 팝오버, 접힌 아코디언, 숨긴 탭 패널
3. {name} 옵션을 쓴다 — 이름 계산이 켜지는 스위치입니다
4. 테스트가 자주 리렌더한다 — jsdom의 스타일 캐시가 계속 무효화됩니다

날짜 컴포넌트가 느렸던 건 이 넷이 전부 겹쳤기 때문입니다.
버튼이 다섯 개인 평범한 컴포넌트라면 아무 문제 없습니다.

확인하는 법

두 쿼리를 나란히 재보면 됩니다. 복사해서 느린 테스트에 붙여넣으면 바로 나옵니다.

const t0 = performance.now();
screen.getByRole('button', {name: '내가 찾는 버튼'});
const t1 = performance.now();
screen.getAllByRole('button', {hidden: true});
const t2 = performance.now();

console.log('name 포함 :', (t1 - t0).toFixed(0), 'ms');
console.log('name 제외 :', (t2 - t1).toFixed(0), 'ms');

두 숫자가 비슷하면 이 글과 무관한 문제입니다. 차이가 10배 이상 나면 이름 계산이 원인입니다.

전용 헬퍼는 마지막 선택지입니다

이번에는 1번을 고르지 않았습니다. 컴포넌트 동작을 바꾸는 일이라 테스트만 손보려던 범위를 넘었거든요. 2번은 찾으려는 요소와 숨은 요소가 같은 컨테이너에 있으면 효과가 없습니다.

3번이 첫 번째 선택지가 되면 안 됩니다. 표준 API를 떠나는 건 팀이 치르는 비용이니까요.

마치며

getByRole('button', {name})은 제게 "이름이 이런 버튼을 찾아줘"라는 한 문장이었습니다.
열어보니 .filter() 다섯 개가 줄줄이 있었고, 그중 하나가 트리 전체를 훑고 있었습니다.

편의는 공짜가 아니라 누군가 대신 내주고 있는 비용이었습니다.
평소에는 그 비용이 충분히 작아서 안 보일 뿐이고요.

그러니 도구가 이상하게 느리다면, 한 번쯤 열어보시길 권합니다.
node_modules 안에 답이 있는 경우가 생각보다 많습니다.

이 글의 근거

• PR: facebook/astryx#3816 (2026-07-12 머지) · 전체 diff
• 머지된 헬퍼: fastRoleQueries.ts (6cfb542 — 이 글이 인용한 버전)
• 인용한 라이브러리 소스는 본문 각 코드블록 아래 출처에 버전과 줄 범위를 고정해 달아두었습니다.
• 더 읽을거리: Accessible Name and Description Computation (W3C)

그 왜가 궁금해서, 릴리스 노트만 훑고 넘기는 대신 마침 굴리던 개인 모노레포에 6을 먼저 올려 하나씩 따라 바꿔봤다.

따라가 보니 이건 단순한 '6의 새 규칙들'이 아니었다. 세 변경을 관통하는 줄기는 하나 — 비싸거나 모호한 기본 동작을 걷어내는 '청소'. 다만 그 청소가 향하는 곳은 셋이 제각각이었다.

그래서 '6 업그레이드 기록'으로 시작한 이 글은, 따라가다 보니 정체가 달라졌다. 손에 남은 건 버전 숫자가 아니라 '그래서 무엇이 올바른 설정인가' 라는 질문이었다.

0. TL;DR

이 글은 Turborepo + pnpm 워크스페이스 모노레포에서 TypeScript 5.8.3 → 6.0.3으로 올리며 만난 breaking change들을, "왜 그렇게 바뀌었는지"를 릴리스 노트 → 이슈 → 실제 PR diff까지 따라가며 정리한 기록이다. 아래 표가 그 전부다 — 그 변경의 이유, 해결책 한 줄씩. 바쁘면 표만 보고 가도 된다.

먼저 한 가지 정정부터. 위 표의 TS5101은 baseUrl 전용 에러가 아니다. TypeScript의 범용 "deprecated option" 진단이고, 6.0이 baseUrl을 그 경로에 태웠을 뿐이다. 이 디테일이 왜 중요한지는 #1에서 PR diff로 확인한다.

1. baseUrl은 왜 deprecated 되었나 (TS5101)

마주침: 이미 알던 손님

baseUrl이 deprecated된다는 건 이미 알고 있었다. 내 코드에서 baseUrl을 실제로 쓰는 곳은 React 앱 하나뿐이었고, paths의 접두사 용도였다.

// apps/react/tsconfig.app.json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    // "baseUrl": ".",   ← 삭제
    "paths": {
      "@/*": ["./src/*"],
      "@pages/*": ["./src/pages/*"]
      // ...
    }
  }
}

그냥 지웠다. paths는 TypeScript 4.1부터baseUrl 없이 동작한다.

"As of TypeScript 4.1, baseUrl is no longer required to be set when using paths."

왜 deprecated 됐나: 아무도 모르던 baseUrl의 두 번째 역할

해결은 쉬웠지만, 왜 멀쩡히 동작하던 옵션을 6.0이 하드 에러로 막는지가 궁금했다. 릴리스 노트와 도입 이슈 #62207을 보면 이유가 명확하다. baseUrl은 두 가지 역할을 한다.

"Today, baseUrl performs two functions:

• it acts as a prefix for all entries in paths
• it acts as a potential resolution point for all bare paths

But almost nobody realizes that last part." — issue #62207

문제는 두 번째, 인용문이 말한 _"bare paths"_다. baseUrl이 켜져 있으면 ./로 시작하지 않는 import까지 — 예컨대 import { Button } from "components/Button"처럼 패키지인지 내 파일인지 모호한 경로까지 — baseUrl 폴더 안에서 찾아준다. 그 바람에 번들러/런타임에선 절대 동작하지 않을 import를 타입체커만 "괜찮다"고 통과시킨다.

"...it often meant that many import paths that would never have worked at runtime are considered "just fine" by TypeScript." — 릴리스 노트

즉 첫 번째 역할(paths 접두사)은 4.1 이후 paths가 직접 대체할 수 있으니, 위험한 두 번째 역할을 없애기 위해 baseUrl 자체를 걷어내는 것이다. 7.0에서는 아예 제거된다.

"In TypeScript 7.0, we are not reimplementing baseUrl. ... In TypeScript 6.0, we will be deprecating this behavior. Using baseUrl will lead to an error which can only be resolved by applying one of the above fixes, or using --ignoreDeprecations." — issue #62207

사실 이 분리는 6년 전에 시작됐다

그런데 "두 역할을 떼어낸다"는 발상은 6.0이 처음이 아니다. 이미 2019년, 한 사용자가 이슈 #31869에서 똑같은 불편을 제기했다 — paths는 타입체킹용 별칭으로만 쓰고 싶은데, baseUrl이 딸려 보내는 두 번째 역할(bare 이름의 암묵적 해석) 까지 떠안긴 싫다는 것이었다.

이 요청은 PR #40101로 구현돼 4.1(2020년) 에 출시됐고, 그때부터 baseUrl 없이도 paths가 동작한다.

그러니 6.0의 deprecation은 갑자기 튀어나온 breaking change가 아니다. 2019년 문제 제기(#31869) → 2020년 4.1 구현(#40101) → 2026년 6.0 정리(#62207·#62509) — baseUrl의 두 역할을 떼어내는 일은 6년에 걸친 청소의 마지막 단계인 셈이다.

구현 레벨: TS5101은 baseUrl 전용이 아니다

여기서 PR #62509 "Deprecate baseUrl"의 실제 diff를 보면 재미있는 사실이 드러난다. baseUrl을 위한 새 에러 코드는 만들어지지 않았다. 기존 범용 deprecation 진단(우리가 보는 TS5101)을 재사용하고, 거기에 마이그레이션 안내용 신규 메시지(코드 5111)만 체이닝한다.

먼저 타입 선언에 @deprecated를 단다.

// src/compiler/types.ts
   alwaysStrict?: boolean;
+  /** @deprecated */
   baseUrl?: string;

그리고 핵심은 program.ts의 checkDeprecations("6.0", "7.0", ...) 블록이다. 여기에 baseUrl 분기가 추가됐다.

// src/compiler/program.ts
 checkDeprecations("6.0", "7.0", createDiagnostic, createDeprecatedDiagnostic => {
     if (options.moduleResolution === ModuleResolutionKind.Node10) {
-        createDeprecatedDiagnostic("moduleResolution", "node10");
+        createDeprecatedDiagnostic("moduleResolution", "node10", /*useInstead*/ undefined,
+            Diagnostics.Visit_https_aka_ms_ts6_for_migration_information);
+    }
+    if (options.baseUrl !== undefined) {
+        createDeprecatedDiagnostic("baseUrl", /*value*/ undefined, /*useInstead*/ undefined,
+            Diagnostics.Visit_https_aka_ms_ts6_for_migration_information);
     }
 });

checkDeprecations("6.0", "7.0", ...) — 6.0에서 deprecate, 7.0에서 제거라는 의미가 함수 인자에 그대로 박혀 있다. 그래서 우리가 보는 에러는 이렇게 생겼다.

error TS5101: Option 'baseUrl' is deprecated and will stop functioning in TypeScript 7.0.
  Specify compilerOption '"ignoreDeprecations": "6.0"' to silence this error.
  Visit https://aka.ms/ts6 for migration information.

TS5101은 "Option '{0}' is deprecated..."라는 범용 메시지의 코드고, {0}에 baseUrl이, 안내 링크( Visit https://aka.ms/ts6 ...)에 신규 코드 5111이 related로 붙은 것이다. 그러니 ignoreDeprecations: "6.0"으로 한시적으로 끌 수는 있지만, 그건 그저 문제를 7.0으로 미루는 일이다.

참고로 에러가 가리키는 https://aka.ms/ts6은 마이그레이션 가이드 이슈(#62508)로 리다이렉트되는데, 이 글을 쓰는 시점엔 본문이 아직 Placeholder만 들어 있는 빈 페이지다. 에러는 친절하게 안내하지만 정작 안내처는 공사 중인 셈.

paths도 끝이 아니다: 진짜 대안은 package.json imports

baseUrl을 지우고 paths로 갈아탔지만, paths도 완전한 답은 아니다. paths는 타입체커 전용이라 tsc가 내보내는 JS엔 반영되지 않아, baseUrl이 6.0에서 막힌 그 이유(런타임에 안 맞는 import를 타입체커만 통과)와 정도만 다를 뿐 같은 괴리를 안는다. 그 괴리가 구조적으로 없는 대안이 * Node가 런타임에 직접 읽는 package.json imports* (# subpath)다 — 타입과 런타임이 같은 매핑을 보니 어긋날 수 없고, TS 핸드북도 이를 "a standard replacement for convenience paths aliases" 로 부른다.

// package.json — tsconfig paths 대신 여기에
{
  "imports": {
	"#/*": "./src/*"
  }
}

import { foo } from '#/utils/foo'; // 타입도, Node 런타임도 같은 매핑으로 해석

2. rootDir를 명시하라 (TS5011)

마주침: 빌드의 dts emit 단계

@package/sample-lib의 빌드는 minibundler && tsc --emitDeclarationOnly 두 단계다. 앞 단계(번들)는 통과했는데 tsc가 깨졌다.

tsconfig.json:10:5 - error TS5011: The common source directory of 'tsconfig.json'
  is './src'. The 'rootDir' setting must be explicitly set to this or another path
  to adjust your output's file layout.
  Visit https://aka.ms/ts6 for migration information.

해결은 한 줄.

// packages/@package/sample-lib/tsconfig.json
{
  "compilerOptions": {
    "emitDeclarationOnly": true,
    "outDir": "./dist",
    "rootDir": "./src", // ← 추가
  }
}

그런데 방금 추가한 rootDir: "./src" 한 줄은 정확히 뭘 할까? rootDir은 출력 폴더(dist)의 모양을 어디서부터 베낄지 정하는 '깃발'이라 보면 된다. tsc는 깃발 아래의 폴더 구조를 그대로 dist에 복제한다.

my-lib/
  tsconfig.json
  src/
    index.ts
    utils.ts

깃발을 src/에 꽂으면 → dist/index.js, dist/utils.js. 한 칸 위(my-lib/)에 꽂으면 → dist/src/index.js로 src/가 딸려 들어온다. 위치 한 끗이 산출물 모양을 가른다.

왜 추론하던 걸 이제 명시하라고 하나

릴리스 노트와 이슈 #62194의 논거는 두 가지다.

"Previously, if you did not specify a rootDir, it was inferred based on the common directory of all non-declaration input files. But this often meant that it was impossible to know if a file belonged to a project without trying to load and parse that project. It also meant that TypeScript had to spend more time inferring that common source directory by analyzing every file path in the program." — 릴리스 노트

요점은 결정성이다. 옛 TS는 깃발을 "내 파일을 전부 담는 가장 깊은 공통 폴더"에 자동으로 꽂았다. 위 예제는 파일이 다 src/에 있으니 깃발은 src/. 그런데 루트에 파일 하나(my-lib/build.ts)만 더하면 공통 폴더가 my-lib/로 점프하고, dist/index.js였던 출력이 통째로 dist/src/index.js로 밀린다. 파일 하나 더했을 뿐인데 산출물 구조가 바뀐다 — 이 들쭉날쭉함이 비결정성이다.

비용은 하나 더 있다. "이 파일이 어느 tsconfig 소속인가"를 알려면 그 공통 폴더부터 계산하느라 프로젝트를 통째로 로드·파싱해야 했다. 깃발을 tsconfig.json 폴더(configDir)에 못 박으면 이걸 경로만 보고 즉답한다 — 제안 이슈의 표현 그대로 "trivially determine whether a file could belong to another tsconfig.json" (#62194). 1장 baseUrl이 7.0에서 아예 사라지는 동작이었던 것과 달리, rootDir은 동작은 남고 그 계산만 입력 파일 목록에서 떼어낸 것이다. 그래도 향하는 곳은 같다 — Go로 다시 쓴 7.0(tsgo)의 빠른 언어 서비스다.

그럼 왜 기본값만 슬쩍 바꾸지 않고 굳이 에러를 던질까? 기본 위치를 말없이 옮기면 빌드는 성공하는데 산출물이 dist/file.js에서 dist/src/file.js로 소리 없이 밀리고, 그걸 import하던 패키지가 영문도 모르고 깨진다. 조용한 사고보다 시끄러운 멈춤이 낫다 — 그래서 옛 추론값과 configDir이 어긋나면 멈추고 명시를 요구한다(그 비교 로직이 다음 절의 TS5011이다).

충격은 모노레포에서 더 컸다. 구현 PR의 생태계 테스트에서 mui-docs는 에러가 0 → 11,385개로 튀었고, TS 팀의 jakebailey도 "Ouch, looking bad for pyright and mui-docs" 라 적었다. 원인은 rootDir을 추론에 맡긴 채 프로젝트 참조 대신 "every project emit each other's files into their own dist" 하던 구조였다(#62418).

여기서 증상이 갈린다. 같은 변경(기본 rootDir = configDir)인데, 깃발이 어디로 가느냐에 따라 두 얼굴로 나타난다.

뿌리는 하나 — 깃발을 자동 추측에서 tsconfig 폴더로 못 박은 것이다. 내 프로젝트는 '출력이 밀리는' 얼굴로, 큰 모노레포는 '파일이 루트 밖으로 튕겨나가는' 얼굴로 나타났을 뿐이다.

구현 레벨: 한 줄짜리 조건 완화 + 신·구 비교

PR #62418 "Assume rootDir is the current configuration directory" 은 81개 파일을 건드린 큰 PR이지만, 핵심 로직은 동일한 한 줄이 세 군데에서 완화된 것이다.

// src/compiler/emitter.ts — getCommonSourceDirectory()
-    else if (options.composite && options.configFilePath) {
+    else if (options.configFilePath) {
         // Project compilations never infer their root from the input source paths
         commonSourceDirectory = getDirectoryPath(normalizeSlashes(options.configFilePath));

예전엔 composite 프로젝트만 "configDir를 공통 소스 디렉터리로" 썼는데, 이제 configFilePath만 있으면(=tsconfig 기반 빌드면) 항상 그렇게 한다. 같은 패턴이 utilities.ts, moduleNameResolver.ts에도 동일하게 적용됐다.

그럼 TS5011은 언제 던지나? program.ts에 새로 추가된 블록이 옛 방식과 새 방식의 공통 디렉터리를 비교해서, 출력 레이아웃이 달라질 때만 에러를 낸다( 아래는 핵심만 발췌·정리).

// src/compiler/program.ts
+if (!options.noEmit && !options.composite && !options.rootDir && options.configFilePath &&
+    (options.outDir || (getEmitDeclarations(options) && options.declarationDir) || options.outFile)) {
+    const dir   = getCommonSourceDirectory();            // 새 방식: configDir 기준
+    const files = mapDefined(/* 실제 emit될 입력 파일들 */);
+    const dir59 = getComputedCommonSourceDirectory(files, /* ... */);  // 옛 방식: 입력 파일 기준
+    if (dir59 !== "" && getCanonicalFileName(dir) !== getCanonicalFileName(dir59)) {
+        // 레이아웃이 바뀐다 → TS5011
+        createDiagnosticForOption(/* ... */
+            Diagnostics.The_common_source_directory_of_0_is_1_The_rootDir_setting_must_be_explicitly_set_...);
+    }
+}

여기서 에러 메시지의 친절함이 설명된다. 메시지의 '{1}'(='./src')은 바로 dir59 — 옛 방식으로 계산한 공통 디렉터리다. 우리 sample-lib는 소스가 ./src에 있어 옛 추론값이 ./src였는데, 새 기본값은 tsconfig 위치(.)라 둘이 어긋난다. 그래서 6.0은 "전엔 ./src로 잡혔으니, 그 값을 rootDir에 명시하라"고 정답을 알려주며 멈춘 것이다. rootDir: "./src"는 그 안내를 그대로 따른 것뿐이다.

3. types 기본값이 []가 된 이유 (그리고 왜 우리 빌드는 멀쩡했나)

의심: 타입이 다 빠졌어야 하는 거 아닌가?

baseUrl도 rootDir도 빨간 에러로 멈춰 세웠는데, types는 이상하리만치 조용했다. 그래서 오히려 의문이 들었다. "TS6에선 types: []가 기본이라던데, 그럼 전역 타입이 다 빠졌을 텐데 왜 빌드가 다 되지?" 이건 에러가 아니라 에러가 안 난 게 더 수상한 경우였다.

무엇이, 왜 바뀌었나

먼저 결을 분명히 하자. 1장(baseUrl)·2장(rootDir)이 7.0(tsgo)을 앞둔 정리였다면, 이 types 변경의 동기는 순수하게 빌드 성능 이다 — 제안 이슈 #62195도 이 변경을 네이티브 컴파일러(7.0)와 묶이지 않은, 6.0에 독립적으로 들어가는 성능 개선으로 다룬다. 그 이슈와 릴리스 노트를 보면 이유가 명확하다: 기존 types의 기본값은 사실상 "node_modules/@types를 전부 열거"였다.

"for convenience, TypeScript would also include all packages in node_modules/@types by default... This can be very expensive, as a normal repository setup these days might transitively pull in hundreds of @types packages, especially in multi-project workspaces with flattened node_modules." — 릴리스 노트

flattened node_modules를 쓰는 모노레포에서는 이게 특히 치명적이다. 수백 개의 불필요한 .d.ts가 전이적으로 프로그램에 끌려와 파싱/체크 비용을 잡아먹는다. 그래서 기본값을 []로 바꿨고, 효과는 수치로 제시돼 있다.

"Many projects we've looked at have improved their build time anywhere from 20-50% just by setting types appropriately." — 릴리스 노트 (원 출처는 #54500)

구현 레벨: "기본값 = []" 대입문은 없다

PR #63054 "Set default types array to []; support \"*\" wildcard"을 까보면, 흥미롭게도 options.types = [] 같은 명시적 기본값 대입은 어디에도 없다. 자동 열거를 담당하던 getAutomaticTypeDirectiveNames의 early-return 조건이 뒤집힌 게 전부다(아래 diff는 핵심만 발췌·정리).

// src/compiler/moduleNameResolver.ts
 export function getAutomaticTypeDirectiveNames(options, host): string[] {
-    // Use explicit type list from tsconfig.json
-    if (options.types) {
-        return options.types;
+    if (!usesWildcardTypes(options)) {
+        return options.types ?? [];
     }
     // ... 여기 아래(typeRoots 열거)는 이제 "*"가 있을 때만 실행된다
-    return result;
+    return deduplicate(flatten(options.types.map(t => t === "*" ? wildcardMatches : t)), equateValues);
 }

핵심은 if (options.types) → if (!usesWildcardTypes(options))로 바뀐 한 줄이다. 예전엔 "types를 명시 안 하면( undefined) typeRoots를 뒤져 모든 @types를 자동 포함"했는데, 이제는 types 배열에 "*"가 있을 때만 열거하고, 그 외에는 options.types ?? []를 그대로 돌려준다. [] 기본값은 별도 코드가 아니라 이 early-return의 자연스러운 결과다.

판정 헬퍼도 새로 추가됐다.

// src/compiler/utilities.ts
+export function usesWildcardTypes(options: CompilerOptions): options is CompilerOptions & { types: string[] } {
+    return some(options.types, t => t === "*");
+}

옛 동작(모든 @types 자동 포함)으로 되돌리고 싶으면 "types": ["*"]를 쓰면 된다. 위 diff에서 options.types.map(t => t === "*" ? wildcardMatches : t) — "*"가 있던 위치에 열거 결과를 펼쳐 넣어 순서까지 보존한다.

핵심: 사라지는 건 import 안 한 '전역' 타입뿐

기본값이 []로 바뀌었다니, 내 타입이 우수수 빠지는 건 아닐까? 다행히 영향 범위는 훨씬 좁다. 이 변경은 node_modules/@types 읽기를 멈추는 게 아니다. 내가 직접 import해서 쓰는 타입은 전혀 영향이 없고, 오직 import 없이 전역(global)으로 깔리던 @types — 예컨대 @types/node의 process·Buffer, 테스트 프레임워크의 describe/expect 같은 것 — 만 끊긴다.

"...this does not mean we will stop reading from node_modules/@types, just that the files won't be brought in unless imported, explicitly listed in your tsconfig.json's types array... Typically this will only affect users relying on global values and module names, like those brought in from @types/node (e.g. the "fs" module is globally defined), or a testing framework." — issue #62195

import { foo } from 'some-pkg';   // ← types 설정과 무관하게 타입 붙음
process.env.NODE_ENV;             // ← @types/node 전역. types에 'node' 없으면 에러

답: 빠질 게 없었다 — 이미 명시돼 있어서

답은 싱겁게도 "이미 잘 명시돼 있어서"였다. 전역이 필요한 패키지는 전부 types를 명시하고 있었다.

types를 명시 안 한 곳(ui, 공유 base)은 애초에 ambient 전역에 의존하지 않거나, Next.js처럼 next-env.d.ts의 /// <reference>로 충당돼서 통과했다. 즉 "에러가 안 난 것"은 운이 아니라, TS6가 강제하기 전부터 옳게 적혀 있었던 덕이다.

ignoreDeprecations는 baseUrl 같은 deprecated 옵션용이지, types 기본값 변경을 되돌리는 옵션이 아니다. 옛 동작이 필요하면 "types": ["*"]를 쓰면 된다 — 이건 glob이 아니라 "전부 열거"를 뜻하는 special token이다.

4. 1차 검증: 여기까지 check-types는 통과

세 가지 규칙을 다 맞추고 나니 타입 체크는 깨끗했다.

• pnpm check-types → 5/5 통과

자, TypeScript 자체가 바꾼 규칙들은 다 막아냈다. 그런데 전체 빌드(pnpm build)를 돌리자, 정작 내가 손대지도 않은 곳에서 다시 터졌다. 그것도 방금 작별했다고 생각한 그 이름, baseUrl로.

5. 보너스: 다시 튀어나온 baseUrl — 이번엔 내 코드가 아니었다

pnpm build가 디자인 시스템 패키지의 dts 빌드에 다다르자 또 TS5101 이 떴다. 그런데 @design-system/ui의 tsconfig엔 baseUrl이 없다. #1에서 봤듯 TS5101은 범용 진단이니, 누군가 내 빌드에 baseUrl을 주입하고 있다는 뜻이다.

범인은 dts 번들러로 쓰던 tsup이었다. 소스의 dts 빌드 옵션 구성부에 이 한 줄이 있다.

baseUrl: compilerOptions.baseUrl || '.', // ← 내 tsconfig에 없어도 '.'를 강제 주입

TS 5.x에선 무해했지만 TS6에선 이 주입이 곧장 하드 에러다(tsup #1388, 재현 환경 tsup 8.5.1 + TS 6.0.2). 게다가 tsup은 이미 유지보수 중단 — README 최상단에 박혀 있다.

"This project is not actively maintained anymore. Please consider using tsdown instead." — egoist/tsup README

baseUrl 주입은 내 코드가 아니라 도구의 문제이고, 그 도구가 더는 고쳐지지 않으니 답은 정해져 있었다 — 후속 도구 tsdown으로 갈아탔다. Rolldown 기반이라 baseUrl을 주입하지 않고, peer로 typescript: "^5.0.0 || ^6.0.0"을 선언해 TS6를 공식 지원한다. 마이그레이션 도구(npx tsdown-migrate)로 config도 거의 그대로 옮겨졌고, 전환 직후 TS5101은 사라졌다.

6. 정리: TypeScript 6 마이그레이션 체크리스트

이번 삽질을 한 줄짜리 체크리스트로 압축하면(1~4는 앞에서 다룬 것, 5는 버전을 일괄 갱신할 때 함께 챙기는 곁가지다):

1. baseUrl을 쓰는가? → 직접 쓰면 제거(paths는 4.1부터 baseUrl 불필요). 빌드 도구가 주입한다면 도구를 점검하라. TS5101은 baseUrl 전용이 아니라 범용 deprecated-option 진단임을 기억할 것.
2. emitDeclarationOnly/outDir로 emit하는데 소스가 tsconfig보다 깊은가? → rootDir을 명시. 에러 메시지의 '{1}'이 곧 넣어야 할 값이다.
3. @types/node 같은 전역에 의존하는가? → types: ["node", ...]로 명시. TS6 기본은 []이고, 이는 ambient 전역에만 영향을 준다(import 타입은 무관). 옛 동작은 ["*"].

7. 정작 가장 큰 수확: 6을 올리지 않아도 됐다

표의 #1~#3, 그리고 보너스까지 따라오며 깨달은 게 있다. 이 변화들의 공통점은 결국 '비싸거나 모호한 기본값을 걷어내는 청소'였다 — baseUrl·rootDir은 TS7(Go)을 향한 정리, types는 순수 성능 개선. 그리고 그 청소는 6을 올려야만 할 수 있는 게 아니다. baseUrl·rootDir·types 셋 다 5에서도 오늘 당장 적용할 수 있는 모범 설정이다. 그러니 정작 올릴 첫 커밋은 "6 업그레이드"가 아니라 이 정리다.

6을 안 올려도, 5에서 지금 할 일:

• baseUrl 제거 → paths만 남기거나, 런타임까지 일치하는 package.json imports로.
• rootDir 고정 → 명시해 출력 레이아웃을 결정적으로 묶는다.
• types 좁히기 → types: ["node", ...]로 명시해 자동 @types 열거 비용을 미리 던다.

세 줄 다 5.x tsconfig에서 오늘 커밋할 수 있다. 6은 이걸 '강제' 했을 뿐 '개발' 한 게 아니다.

그래서, 오늘 당신의 tsconfig는?

이 글을 닫기 전에 딱 하나만 하자 — tsconfig.json을 여는 것. baseUrl이 아직 남아 있는지, rootDir이 비어 있는지, types가 통째로 열려 있는지. 셋 다 6을 기다릴 것 없이 오늘 5.x에서 고치고, 그 커밋 하나로 빌드를 더 빠르게 만들 수 있다. 미뤄도 빌드는 돌지만, 미룬 만큼 7.0에서 한꺼번에 청구된다.

그리고 정말 궁금하다 — 여러분의 프로젝트는 이 셋 중 몇 개를 이미 지키고 있었나? 셋 다 비어 있었다면 무엇부터 손볼지, 아니면 "우린 진작 package.json imports로 넘어갔다" 같은 이야기가 있다면 댓글로 남겨 달라. 남의 tsconfig가 어디서 새는지는, 의외로 서로의 댓글에서 가장 빨리 배운다.

참고 링크

• TypeScript 6.0 릴리스 노트 — https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html
• baseUrl deprecation: issue #62207 · PR #62509
• baseUrl/paths의 런타임 안전 대안 package.json imports: TS 핸드북 Modules Reference · Node.jsimports 필드 · TS 4.7 릴리스 노트(imports 지원)
• types 기본값 []: issue #62195 · PR #63054 · 원 rationale #54500
• rootDir 기본값: issue #62194 · PR #62418
• tsup: README · TS5101 이슈 #1388 · TS6 지원 #1389
• tsdown: 공식 문서 · tsup → tsdown 마이그레이션 · rolldown-plugin-dts

팀원: "OO님, Post 타입에서 id가 없다고 에디터에서 빨간 줄이 뜨는데, 새 글 작성할 땐 서버 id가 없으니까 그냥 ? 붙여도 될까요?"

프론트엔드 개발을 하다 보면 슬랙이나 코드 리뷰에서 심심치 않게 보게 되는 질문입니다. 저 역시 예전에는 빠른 기능 구현을 위해 무심코 ?를 붙이며 타입 에러를 '지우는 데' 급급했던 시절이 있었습니다. 십중팔구 이런 타입을 작성해 보셨을 겁니다.

interface Post {
  id?: string; // 새로 작성 중일 땐 서버 id가 없으니까 옵셔널 처리
  title: string;
  content: string;
}

당장 에러는 안 나니 편합니다. 하지만 이 작은 ? 하나 때문에 우리는 프로젝트 내내 고통받습니다.

분명히 DB에서 방금 조회해 온 글이라 100% ID가 존재하는데도, 타입스크립트는 "ID가 없을 수도 있잖아?" 라며 끊임없이 딴지를 겁니다. 결국 우리는 울며 겨자 먹기로 컴포넌트 곳곳에 if (post.id)나 post.id! 같은 무의미한 방어 코드를 도배하게 되죠. 코드는 지저분해지고, 개발자의 피로도는 급증합니다.

왜 이런 일이 발생할까요? 우리가 타입스크립트에게 "도메인의 현실"을 제대로 알려주지 않고 거짓말을 했기 때문입니다.

2. 왜 프론트엔드에 도메인 모델링이 필요한가

'도메인 모델링'이라고 하면 보통 백엔드나 DDD의 영역으로 생각하기 쉽습니다. 하지만 잠깐 생각해 봅시다. 사용자의 행동 흐름을 가장 충실하게 코드로 표현해야 하는 곳이 어디인가요? 바로 프론트엔드입니다.

사용자는 글을 '작성'하고, '저장'하고, '수정'하고, '삭제'합니다. 이 모든 흐름에서 데이터의 상태는 끊임없이 변합니다. 그런데 우리가 이 상태 변화를 타입으로 제대로 표현하지 않으면, 결국 런타임에서 undefined 에러로 돌아옵니다.

도메인 모델링은 유비쿼터스 언어, 엔티티 설계, 바운디드 컨텍스트 정의 등 넓은 영역을 포괄합니다. 하지만 그 첫 번째 원칙은 상태를 타입으로 정확히 표현하는 것 입니다. 이 글에서는 바로 그 첫걸음에 집중합니다.

우리의 비즈니스 규칙을 가만히 들여다봅시다.

1. 작성 중인 글: 제목과 내용만 있습니다. ID는 절대 없습니다.
2. 발행된 글: 서버에 안전하게 저장되었습니다. 반드시 고유한 ID를 가집니다.

즉, 이 도메인에서 "ID가 생겼다" 는 것은 단순히 데이터에 문자열 필드 하나가 추가된 것이 아닙니다. 객체의 신분이 '임시'에서 '정식'으로 완전히 바뀌었음을 의미합니다.

그런데 우리는 귀찮다는 이유로 이 완전히 다른 두 가지 상태를 Post라는 하나의 타입에 억지로 욱여넣고, id?: string으로 퉁쳐버린 겁니다.

3. Tagged Type: 상태를 타입으로 증명하기

이 문제를 해결하는 타입스크립트의 공식 패턴이 있습니다. 바로 Tagged Type, 또는 Discriminated Union 이라고 불리는 패턴입니다.

핵심 아이디어는 간단합니다.

💡 모든 상태가 공유하는 하나의 리터럴 속성(Tag) 을 만들고, 그 값으로 상태를 식별하자.

중복되는 코드는 BasePost로 깔끔하게 묶어내고, status라는 태그(Tag) 속성으로 상태를 명확히 분리해 봅시다.

먼저, 글이라면 무조건 가져야 하는 공통 속성을 정의합니다.

interface BasePost {
  title: string;
  content: string;
}

그 다음, status 태그로 두 가지 상태를 분리합니다.

// 아직 식별자가 없는 '작성 중' 상태
interface DraftPost extends BasePost {
  status: 'draft';
}

// 서버에 저장되어 식별자가 존재하는 '발행 완료' 상태
interface PublishedPost extends BasePost {
  status: 'published';
  id: string; // 발행되었으니 반드시 존재!
}

마지막으로, 이 둘을 합쳐서 완전한 Post 도메인을 만듭니다.

type Post = DraftPost | PublishedPost;

여기서 status가 바로 Tag 입니다. 'draft'와 'published'라는 리터럴 값이 각 상태의 이름표 역할을 하죠. 이제 타입스크립트는 status 값만 확인하면 나머지 데이터의 형태를 자동으로 추론할 수 있게 됩니다.

🤔 id 유무로 구분하면 안 되나요?

여기서 한 가지 의문이 떠오를 수 있습니다. "굳이 status를 만들지 않아도, id가 있으면 >PublishedPost고 없으면 DraftPost 아닌가?"

기술적으로는 가능합니다. id?: never와 id: string으로도 Discriminated Union을 만들 수 있거든요. 하지만 id의 유무는 기술적 사실이고, status는 도메인 개념 입니다. 글 전체의 주장이 "타입으로 도메인을 표현하라" 인데, id의 유무로 상태를 구분하면 그 주장과 어긋납니다. id가 없다는 건 우연히 draft와 일치하는 거지, draft라는 개념 자체 를 표현하는 게 아니기 때문입니다.

그리고 도메인이 성장하면 archived, scheduled, under_review 같은 상태가 생깁니다. 이때 id의 유무만으로는 이 상태들을 구분할 수 없습니다. 확장성은 status 태그를 선택했을 때 자연스럽게 >따라오는 부산물입니다.

4. Before / After: 타입으로 좁히기

이론만으로는 감이 잘 안 올 수 있습니다. 같은 비즈니스 로직을 옵셔널 방식과 Tagged Type 방식으로 나란히 비교해 봅시다.

Before: 옵셔널 타입

function handlePost(post: Post) {
  // post.id가 있는지 확신할 수 없습니다.
  if (!post.id) {
    // 여기가 "새 글 작성"인지 "에러 상황"인지 알 수 없습니다.
    console.log('ID가 없습니다... 새 글인가? 에러인가?');
    api.create(post);
    return;
  }

  // 여기서도 타입스크립트는 post.id가 string | undefined라고 불평합니다.
  api.update(post.id, post);
}

• post.id가 없는 상황이 "새 글 작성"인지 "진짜 에러"인지 구분이 안 됩니다.
• 개발자가 매번 if (post.id) 같은 방어 코드를 직접 작성해야 합니다.

After: Tagged Type

function handlePost(post: Post) {
  if (post.status === 'draft') {
    // 이 블록 안에서 post는 DraftPost입니다.
    // id 필드 자체가 존재하지 않으므로 실수할 여지가 없습니다.
    console.log(`임시저장 글을 새로 생성합니다: ${post.title}`);
    api.create(post);
    return;
  }

  // 여기서 post는 자동으로 PublishedPost!
  // post.id는 무조건 string. 옵셔널 체이닝도 느낌표도 필요 없습니다.
  console.log(`기존 글(${post.id})을 업데이트합니다.`);
  api.update(post.id, post);
}

post.status === 'draft'라는 조건 하나로, 타입스크립트가 나머지 모든 타입을 자동으로 좁혀냅니다. 개발자는 더 이상 id가 있는지 없는지 런타임에서 의심할 필요가 없습니다. "발행된 글은 id가 반드시 있다" 는 도메인의 규칙이 타입 시스템에 완벽하게 녹아들었기 때문입니다.

5. 한 걸음 더: 타입 가드로 의도를 명시적으로 드러내기

한 가지 더 욕심을 부려봅시다. 컴포넌트 곳곳에 if (post.status === 'published')가 반복되고 있지 않나요? 타입 좁힘 의도를 함수로 빼내세요. 조건의 의미가 명시적으로 드러나고, 변경 포인트가 한 곳에 모입니다.

// 타입 좁힘 의도를 명시적으로 드러내는 타입 가드 함수
function isPublished(post: Post): post is PublishedPost {
  return post.status === 'published';
}

여기서 반환 타입이 boolean이 아니라 post is PublishedPost인 점이 눈에 띌 겁니다. 이것은 타입스크립트의 타입 서술어 문법입니다. 의미는 간단합니다. "이 함수가 true를 반환하면, 매개변수 post를 PublishedPost 타입으로 좁혀도 안전하다" 고 컴파일러에게 알려주는 것이죠.

만약 반환 타입을 그냥 boolean으로 쓰면, 함수 호출 후에도 타입스크립트는 여전히 post를 DraftPost | PublishedPost로 인식합니다. post is PublishedPost라는 한 마디가 if 블록 안에서 자동 타입 좁혀짐을 가능하게 하는 열쇠입니다.

이렇게 하면 post.status === 'published'라는 기술적 조건이 isPublished라는 도메인 언어로 바뀌고, 타입 좁힘 의도가 코드에 명확히 드러납니다.

function updatePost(post: Post) {
  if (isPublished(post)) {
    // isPublished를 통과했으니 post.id는 무조건 존재!
    api.patch(`/posts/${post.id}`, post);
  }
}

그래서 DraftPost는 언제 PublishedPost가 되는가?

"타입을 분리한 건 알겠는데, 실제 코드에서 DraftPost가 PublishedPost로 바뀌는 시점은 언제야?" 라는 의문이 남을 수 있습니다. 답은 명확합니다. 서버가 ID를 부여해서 응답을 돌려주는 바로 그 순간 입니다.

// API 응답 타입: 서버가 ID를 부여한 결과
interface CreatePostResponse {
  id: string;
  title: string;
  content: string;
}

async function createPost(draft: DraftPost): Promise<PublishedPost> {
  const response = await api.post<CreatePostResponse>('/posts', draft);

  // 서버가 부여한 id와 함께, 상태 태그를 'published'로 확정합니다.
  // 이 순간 DraftPost는 사라지고, PublishedPost가 탄생합니다.
  return {
    ...draft,
    status: 'published',
    id: response.id,
  };
}

핵심은 객체를 직접 변환하지 않는다 는 것입니다. 기존 DraftPost의 status를 바꾸는 게 아니라, 서버 응답 데이터를 기반으로 완전히 새로운 PublishedPost 객체를 생성 합니다. status: 'published'와 id가 함께 들어가는 순간, 타입스크립트는 이 객체가 PublishedPost임을 자동으로 인식합니다. 타입의 전환이 곧 도메인 상태의 전환이 되는 셈이죠.

6. 마무리

처음에 우리는 타입스크립트에게 거짓말을 했습니다. id?: string으로 현실을 왜곡했죠. Tagged Type은 그 거짓말을 걷어내는 작업입니다. 도메인의 규칙을 있는 그대로 코드에 옮기면, 타입스크립트는 더 이상 적이 아닙니다.

타입은 단순한 에러 방지용 도구가 아닙니다. 비즈니스의 흐름과 상태의 변화를 코드에 증명 하는 수단입니다.

💡 내 프로젝트에 당장 적용하기 체크리스트

• 내 코드에 무의미한 if (data.id) 체크가 너무 많지 않은가?
• ? 옵셔널 필드들이 사실 특정 '상태'를 대변하고 있진 않은가?
• 상태를 식별할 수 있는 공통 Tag 속성(status, type, kind)을 추가할 수 있는가?
• 상태별로 타입을 명확히 분리하여 유니온(|)으로 묶었는가?
• 타입 가드 함수로 타입 좁힘 의도를 명시적으로 드러냈는가?

"에러 위치: bundle.js 2847번째 줄"

지난 편(Step 3. 번들링과 스코프)에서 우리는 드디어 파일을 하나로 합치는 데 성공했습니다. 수십 개의 파일이 IIFE 안에 질서 정연하게 들어가고, 브라우저에서도 정상적으로 실행됩니다.
그런데 잠깐. 실제 프로젝트에서 이 번들 파일을 배포했다고 상상해 봅시다. 운영 중에 에러가 납니다. 브라우저 콘솔이 이렇게 말합니다.

Uncaught TypeError: Cannot read properties of undefined at bundle.js:2847:23

bundle.js 2847번째 줄. 여러분이 작성한 수십 개의 원본 파일 중 어디에 해당하는 코드일까요? 그 파일의 몇 번째 줄일까요?
번들러가 파일을 합치는 과정에서 원본의 행과 열 정보는 완전히 뒤섞입니다. 소스맵이 없다면, 이 에러를 디버깅하는 것은 사실상 불가능에 가깝습니다.
이번 편에서는 소스맵의 원리를 파헤치고, 우리 번들러에 직접 구현해보겠습니다.

1. 소스맵이란: "번들 좌표 → 원본 좌표" 변환표

소스맵을 가장 쉽게 설명하자면 좌표 변환표입니다.

flowchart LR
    A["📦 bundle.js<br/>2847번째 줄 · 23번째 열"]
    B[("🗺️ index.js.map<br/>소스맵 조회")]
    C["📄 src/components/Button.js<br/>15번째 줄 · 8번째 열"]

    A -->|에러 발생| B
    B -->|원본 위치 반환| C

이 변환표가 .map 파일 형태로 번들 파일과 함께 배포됩니다.
브라우저 DevTools는 이 파일을 읽어서, 에러 위치를 자동으로 원본 파일 기준으로 표시해 줍니다.
실제 .map 파일을 열어보면 이런 모양입니다.

{
  "version": 3,
  "file": "index.js",
  "sources": ["src/index.js", "src/components/Button.js"],
  "sourcesContent": ["...", "..."],
  "mappings": "AAAA,SAAS;AACT,IAAIA..."
}

sources는 원본 파일 목록입니다. sourcesContent에는 원본 파일의 코드가 통째로 들어갑니다.
구현 코드의 includeContent: true 옵션이 켜지면 채워지는 필드입니다. 소스 파일이 없는 환경에서도 디버깅이 가능해지지만, .map 파일에 소스 코드 전체가 포함되어 파일 크기가 크게 늘고 소스가 그대로 노출된다는 트레이드오프가 있습니다.
그리고 mappings는... 외계어처럼 보이는 암호문입니다. 이 mappings 필드가 소스맵의 핵심입니다. 여기에 모든 좌표 변환 정보가 압축되어 있습니다. 이걸 이해하려면 VLQ를 알아야 합니다.

2. magic-string의 진짜 목적

잠깐, 본론으로 들어가기 전에 한 가지 물어보겠습니다.
우리는 1편부터 magic-string이라는 라이브러리를 써왔습니다. 단순히 "문자열을 덮어쓰는 도구" 로만 알고 있었죠. 그런데 왜 굳이 String.replace()나 정규식을 쓰지 않고 이 라이브러리를 선택했을까요?

magic-string의 진짜 목적은 소스맵 생성입니다.
일반 문자열 치환은 "무엇이 바뀌었는지" 를 기억하지 못합니다. 하지만 magic-string은 모든 변환 작업의 이력을 내부에 쌓아둡니다.

// Module.ts (line 198)
// import { Button } from './Button.js' → const { Button } = require(1)
this.magicString.overwrite(node.start, node.end, replacement);
//                          ^^^^^^^^^^  ^^^^^^^^
//                          원본에서 어디부터 어디까지를 바꿨는지 기록!

overwrite(start, end, newText)를 호출할 때마다, magic-string은 내부적으로 이런 기록을 남깁니다.

"원본 코드의 0번 인덱스부터 32번 인덱스까지가 'const { Button } = require(1);'로 교체되었다"

이 이력이 쌓이면 쌓일수록, magic-string은 나중에 "원본의 어느 위치가 결과물의 어느 위치에 해당하는지" 역산할 수 있게 됩니다.

flowchart TD
    A["🔧 Module.ts MagicString.overwrite()"]
    B["📦 Graph.ts Bundle.addSource()"]
    C["🗺️ Graph.ts Bundle.generateMap()"]
    D["📄 index.js.map VLQ 인코딩된 소스맵"]

    A -->|변환 이력 기록| B
    B -->|각 모듈의 이력 통합| C
    C -->|생성| D

3. VLQ: mappings 가 외계어인 이유

이제 그 암호문으로 돌아올 차례입니다.

"mappings": "AAAA,SAAS"

이게 뭘까요? 이건 VLQ(Variable Length Quantity) 인코딩으로 압축된 좌표 데이터입니다.

왜 이렇게 압축하나요?

소스맵은 원본 코드의 모든 토큰(변수명, 괄호, 세미콜론 하나하나)에 대한 위치 정보를 담아야 합니다. 수천 개의 좌표를 그냥 숫자로 저장하면 .map 파일이 번들 파일보다 훨씬 커질 수 있습니다. VLQ는 두 가지 트릭으로 이를 해결합니다.

• 트릭 1. 상대 좌표 절대 좌표(100번째 줄) 대신 이전 항목으로부터의 거리(+2줄)를 저장합니다. 대부분의 연속된 코드는 서로 가깝기 때문에, 숫자가 훨씬 작아집니다.

• 트릭 2. 가변 길이 인코딩 + Base64 작은 숫자(0)는 1글자(A)로, 큰 숫자는 여러 글자로 표현합니다. Base64(A-Z, a-z, 0-9, +, /)를 사용해 바이너리 없이 텍스트 파일에 저장합니다.

그런데 왜 굳이 알파벳으로 바꾸나요?

숫자를 줄였으면 됐지, 왜 또 A나 S 같은 글자로 바꾸는 걸까요?

이유는 단 하나입니다. 쉼표나 마이너스 기호 없이 데이터를 다닥다닥 붙여 써서 용량을 극한으로 줄이기 위해서 입니다.

만약 숫자를 그대로 텍스트 파일에 쓴다면 9,0,0,9 = 7글자가 필요합니다. 숫자가 커져서 15,0,-10,5가 되면 11글자입니다. 소스맵에는 이런 좌표가 수십만 개가 들어갑니다. 쉼표나 마이너스 기호조차도 용량 낭비인 셈입니다.

그래서 숫자 여러 개를 알파벳 하나에 욱여넣습니다. 9,0,0,9라는 7글자짜리 데이터가 SAAS라는 딱 4글자로 압축됩니다.

A나 S 자체에는 아무런 특별한 의미가 없습니다. Base64라는 전 세계 공통 암호표에 적힌 기호일 뿐입니다.

A = 0번, B = 1번, C = 2번 ... S = 18번 ... a = 26번 ...

컴퓨터가 소스맵에서 S를 발견하면 "Base64 18번 값이구나!" 하고 읽어들입니다.
그 18이라는 숫자를 6비트 이진수로 펼치면 실제 좌표 값이 나오는 구조입니다.

VLQ 비트 구조

암호문을 해독하기 전에, 각 Base64 문자 안에 담긴 6비트의 역할부터 파악해야 합니다.

[ bit5 | bit4  bit3  bit2  bit1 | bit0 ]
    ↑    ←—— 값 비트 (4비트) ——→    ↑
 연속 비트                       부호 비트
(0=끝, 1=다음 문자도 같은 숫자)  (첫 번째 그룹만)
                                (0=양수, 1=음수)

• bit 5 (연속 비트): 1이면 다음 Base64 문자도 같은 숫자의 일부입니다. 0이면 이 문자가 마지막입니다. 15보다 큰 값을 여러 글자에 걸쳐 표현할 수 있는 핵심 장치입니다.
• bit 4~1 (값 비트): 4비트로 0~15를 담습니다.
• bit 0 (부호 비트): 오직 첫 번째 그룹에만 적용됩니다. 0 = 양수, 1 = 음수. 상대 좌표는 음수가 될 수 있으므로 부호가 필요합니다.

이걸 기차 화물칸으로 비유하면 이렇습니다. 각 Base64 문자는 6칸짜리 기차 화물칸입니다.

• 맨 앞칸(연속 비트): "뒤에 기차칸이 더 연결되어 있나요?" (1이면 연결됨, 0이면 끝)
• 가운데 4칸(값 비트): 실제 짐(숫자)을 싣는 공간 (0~15)
• 맨 뒤칸(부호 비트): "양수인가요, 음수인가요?" (0=양수, 1=음수, 첫 번째 칸에만 적용)

AAAA 직접 해독해보기

mappings의 각 세그먼트는 쉼표(,)로 구분되고, 세미콜론(;)은 번들 파일의 줄 바꿈을 의미합니다.

AAAA라는 가장 단순한 세그먼트를 직접 해독해봅시다.

'A'는 Base64 값 0 = 000000(2진수)입니다. 비트 구조를 적용하면 bit 5 = 0(연속 없음), bit 4~1 = 0000(값 0), bit 0 = 0(양수)이므로 값은 0입니다.

flowchart LR
    S(["AAAA"])

    S -->|"1번째 A"| C1["000000₂ = 0"]
    S -->|"2번째 A"| C2["000000₂ = 0"]
    S -->|"3번째 A"| C3["000000₂ = 0"]
    S -->|"4번째 A"| C4["000000₂ = 0"]

    C1 --> R1["① 생성파일 열 = 0"]
    C2 --> R2["② 소스파일 인덱스 = 0"]
    C3 --> R3["③ 소스 행 = 0"]
    C4 --> R4["④ 소스 열 = 0"]

이 4개의 숫자는 각각 다음을 의미합니다.

따라서 AAAA는 "번들 파일의 0번째 열 → 소스 0번 파일(src/index.js)의 0행 0열" 을 의미합니다.

이제 S가 왜 9인지도 추적해봅시다. 'S'는 Base64 값 18 = 010010(2진수)입니다.

• bit 5 = 0 → 연속 없음
• bit 4~1 = 1001 → 값 = 9
• bit 0 = 0 → 양수

따라서 S는 값 9입니다. SAAS는 [9, 0, 0, 9]이고, 상대 좌표이므로 앞 세그먼트 [0,0,0,0]에 더해 번들 9번째 열 → src/index.js 0행 9열을 가리킵니다.

flowchart LR
    subgraph seg1["세그먼트 ① AAAA"]
        direction TB
        D1["[0, 0, 0, 0]"]
        M1["번들 0열<br>→ src/index.js 0행 0열"]
        D1 --> M1
    end

    subgraph seg2["세그먼트 ② SAAS<br> (상대 좌표 +9, +0, +0, +9)"]
        direction TB
        D2["[9, 0, 0, 9]"]
        M2["번들 9열<br>→ src/index.js 0행 9열"]
        D2 --> M2
    end

    seg1 -->|"다음 세그먼트"| seg2

15를 초과하는 값 — 연속 비트 동작 예시

지금까지는 9 이하 값들만 등장했습니다. 첫 번째 그룹의 4비트 값(0~15)으로 충분했기 때문입니다. 값이 16 이상이 되면 처음으로 연속 비트(bit 5)가 실제로 켜집니다.

값 20을 인코딩해봅시다.

• 하위 4비트 = 0100 (= 4), 남은 값 = 20 >> 4 = 1 → 연속 비트 = 1
• 부호 = 0 (양수)
• 첫 번째 문자: 1|0100|0 = 101000₂ = 40 → Base64[40] = o

남은 값 1을 두 번째 문자로:

• 두 번째 문자부터는 부호 비트 없이 5비트 전체가 값 → 0|00001 = 000001₂ = 1 → Base64[1] = B

값 20 = oB (두 글자). 복원 시: 4 + 1 × 16 = 20.

두 번째 글자의 bit 0은 더 이상 부호 비트가 아닙니다. 두 번째 글자부터는 bit 5만 연속 비트로 쓰고, 나머지 5비트(bit 4~0) 전체가 값을 담습니다. 값이 커질수록 세 번째, 네 번째 글자로 이어지는 구조입니다.

상대 좌표의 기준점은 어떻게 정해지나요?

한 가지 궁금증이 남을 수 있습니다. 상대 좌표라면 기준점이 있어야 하는데, 그 기준점은 어떻게 정해지는 걸까요?

답은 간단합니다. 맨 처음 [0, 0, 0, 0]에서 출발해서, 방금 전까지 계산해 둔 최종 위치가 다음 이동의 기준점이 됩니다. 꼬리에 꼬리를 무는 릴레이 달리기입니다.

세 번째 세그먼트가 있고 해독해보니 [+5, +0, +1, -3]이라면?

• 직전 도착지점: [9, 0, 0, 9]
• 이동 거리: [+5, +0, +1, -3]
• 새 도착지점: [14, 0, 1, 6]

이런 식으로 계속 누적됩니다. 외부에서 기준점을 정해주는 것이 아니라, 항상 직전 세그먼트에서 이어받는 구조입니다.

그리고 세미콜론(;)이 등장하면 번들 파일에서 다음 줄로 넘어갔다는 뜻입니다. 이때 번들 파일의 열(첫 번째 값)만 0으로 초기화되고, 나머지 원본 파일의 위치(파일 번호, 행, 열)는 그대로 유지됩니다. 번들 파일에서 줄이 바뀌어도 원본 코드 기준으로는 아까 읽던 위치 근처일 가능성이 높기 때문입니다.

이 복잡한 비트 연산을 직접 구현하는 건 매우 어렵습니다. 그래서 우리는 magic-string이 이걸 대신해 줍니다. 우리가 할 일은 단지 overwrite()로 이력을 남기고, generateMap()을 호출하는 것뿐입니다.

4. 구현: Graph.ts와 Module.ts

이제 실제 코드를 봅시다. 소스맵 생성은 Graph.ts의 generate() 메서드에서 이루어집니다.

Module.ts: 변환 이력 기록

Module 클래스는 생성 시점에 MagicString을 초기화합니다.

// Module.ts (line 65)
this.magicString = new MagicString(this.content);
// 원본 코드 내용을 MagicString으로 감쌉니다.
// 이후 모든 변환 작업은 이 객체를 통해 이루어집니다.

transform() 메서드에서 ESM → CJS 변환이 이루어질 때마다 이력이 쌓입니다.

// Module.ts (line 198): ImportDeclaration 변환 시
// "import { Button } from './Button.js'" 구간을 교체
this.magicString.overwrite(node.start, node.end, replacement);
// node.start, node.end: AST가 알려준 원본 코드의 정확한 위치
// replacement: "const { Button } = require(1);"

AST가 "어디를 바꿔야 하는지" 를 알려주고, magic-string이 "어디가 어떻게 바뀌었는지" 를 기억합니다. 이 두 도구의 역할 분리가 핵심입니다.

MagicString 초기화 코드 보기 (Module.ts:65)

overwrite() 이력 기록 전체 보기 (Module.ts:198)

Graph.ts: 소스맵 통합 생성

generate() 메서드에서 모든 모듈의 이력을 Bundle로 통합하고 소스맵을 생성합니다.

// Graph.ts (line 97~)
const bundle = new Bundle({
  separator: '\n', // 각 모듈 사이의 구분자
});

// 각 모듈을 Bundle에 추가 (line 155~158)
bundle.addSource({
  filename: path.relative(process.cwd(), module.filePath), // ⭐ 보안 핵심 (아래 설명)
  content: module.magicString, // 변환 이력이 담긴 객체를 통째로 전달
});

// VLQ 인코딩된 소스맵 생성 (line 178~182)
const map = bundle.generateMap({
  file: 'index.js.map', // 소스맵 파일명
  includeContent: true, // 원본 코드도 .map에 포함
  hires: true, // 고해상도 (열 단위 매핑)
});

bundle.generateMap()이 호출되는 순간, magic-string은:

1. 모든 addSource()로 추가된 모듈들의 변환 이력을 수집합니다.
2. 각 변환 이력을 VLQ 인코딩으로 변환합니다.
3. mappings 문자열을 생성해서 .map 파일로 저장합니다.

소스맵 생성 전체 코드 보기 (Graph.ts:92)

5. 보안: 절대 경로 노출 문제

filename 옵션에 주목하세요. 여기에 무심코 절대 경로를 넣으면 보안 문제가 생깁니다.

// ❌ 위험: 절대 경로 그대로 사용
bundle.addSource({
  filename: module.filePath,
  // → "/Users/han/repository/my-company/secret-project/src/index.js"
  content: module.magicString,
});

소스맵의 sources 배열에 이 경로가 그대로 들어갑니다.

{
  "sources": ["/Users/han/repository/my-company/secret-project/src/index.js"]
}

이 .map 파일이 프로덕션 서버에 배포된다면:

• 개발자의 로컬 시스템 구조가 노출됩니다.
• 프로젝트 내부 경로가 외부에 공개됩니다.
• 보안 감사에서 지적 사항이 될 수 있습니다.

해결책: path.relative()

// ✅ 안전: 프로젝트 루트 기준 상대 경로 사용 (Graph.ts line 156)
bundle.addSource({
  filename: path.relative(process.cwd(), module.filePath),
  // → "src/index.js" (프로젝트 루트 기준)
  content: module.magicString,
});

path.relative(process.cwd(), module.filePath)는:

• process.cwd(): 번들러가 실행되는 디렉토리 (보통 프로젝트 루트)
• module.filePath: 모듈의 절대 경로
• 결과: 프로젝트 루트 기준의 상대 경로

소스맵 sources 배열에는 깔끔한 상대 경로만 남습니다.

{
  "sources": ["src/index.js", "src/components/Button.js"]
}

path.relative() 적용 코드 보기 (Graph.ts:156)

더 큰 위험: 소스 코드 자체의 유출

절대 경로 노출보다 더 치명적인 문제가 있습니다. 소스맵 파일 하나만 있어도 원본 코드를 통째로 복구할 수 있습니다.

includeContent: true로 생성된 소스맵에는 sourcesContent 배열에 원본 파일의 코드가 텍스트 그대로 들어갑니다. 누군가 .map 파일을 다운로드하기만 하면 주석 하나까지 완벽하게 원본을 살려낼 수 있습니다. (reverse-sourcemap 같은 도구가 이를 자동화해 줍니다.)

sourcesContent가 없는 경우에도 마찬가지입니다. mappings가 "번들의 이 글자는 원본의 저 변수명이다"를 기억하고 있기 때문에, 번들된 코드를 역추적해서 원래 변수명, 함수명, 파일 구조를 그대로 조립해낼 수 있습니다.

그래서 실무에서는 이렇게 대처합니다.

6. 라이브러리 배포와 소스맵 전략

우리가 만들고 있는 것은 웹사이트가 아니라 라이브러리입니다. 라이브러리 배포 맥락에서 소스맵을 어떻게 다뤄야 할지 살펴봅니다.

sourcesContent의 용량 문제

일반적으로 .map 파일의 크기는 번들된 .js 파일보다 2~3배 더 큽니다. 원본 코드가 텍스트로 전부 들어가기 때문입니다.

그런데도 이 거대한 파일을 만드는 이유는, 일반 사용자는 이 파일을 다운로드하지 않기 때문입니다.

• 일반 사용자: 웹사이트에 접속하면 bundle.js만 다운로드합니다. .map 파일은 전혀 신경 쓰지 않습니다.
• 개발자(디버깅): F12를 눌러 DevTools를 여는 순간, 브라우저가 //# sourceMappingURL=... 주석을 보고 그때서야 .map 파일을 백그라운드에서 다운로드하기 시작합니다.

사용자들의 로딩 속도에는 전혀 영향을 주지 않습니다.

라이브러리 사용자는 원본 코드가 없습니다

npm에 라이브러리를 배포할 때 보통 dist/ 폴더만 올립니다. 라이브러리 사용자의 node_modules/my-lib/ 안에는 dist/index.js와 dist/index.js.map만 존재합니다. 원본이 담긴 src/ 폴더는 없습니다.

소스맵에 sourcesContent가 없다면, 라이브러리 사용자가 디버깅하려고 에러를 클릭해도 브라우저는 원본 코드 파일을 찾지 못합니다. sourcesContent에 원본 코드를 통째로 넣어줘야만 라이브러리 사용자의 DevTools에서 원본 코드를 볼 수 있습니다.

소스맵 체이닝

라이브러리 사용자는 보통 Webpack이나 Vite 같은 자신만의 번들러를 사용합니다. 이 번들러가 node_modules/my-lib/dist/index.js를 가져와 자신의 앱에 합칠 때, 우리의 index.js.map을 발견하고 자신의 소스맵과 연결합니다.

결과적으로 최종 웹앱에서 에러가 나면, DevTools는 수많은 빌드 과정을 역추적해서 "이 에러는 설치한 라이브러리의 src/components/Button.js 15번째 줄에서 났네요!" 라고 정확히 짚어줍니다.

어떤 전략을 선택해야 할까요?

소스맵을 아예 배포하지 않으면? 라이브러리를 설치한 개발자가 에러를 만났을 때, 글 맨 첫 줄의 그 상황이 그대로 재현됩니다.

Uncaught TypeError: Cannot read properties of undefined at node_modules/my-lib/dist/index.js:2847:23

디버깅을 포기하고 GitHub 이슈 탭에 불친절한 리포트를 남기게 됩니다.

7. 결과물 확인

이론은 충분히 다뤘습니다. 실제로 빌드해서 소스맵이 제대로 생성되는지 확인해봅시다.

$ pnpm --filter @package/sample-lib run build

📦 Minibundler started...
📂 Processing: /Users/han/.../src/index.js
📂 Processing: /Users/han/.../src/components/Button.js
🛠️  Generating bundle...
📦 Generated CJS Bundle: dist/index.js
🗺️  Generated SourceMap: dist/index.js.map
✨ Generated Standalone ESM: dist/index.mjs
✅ Bundle built successfully!

dist/ 디렉토리에 세 개의 파일이 생성됩니다.

dist/
├── index.js        ← CJS 번들 (맨 아래에 sourceMappingURL 주석 포함)
├── index.js.map    ← 소스맵
└── index.mjs       ← ESM 번들

index.js 맨 마지막 줄을 확인해보면 소스맵 참조 주석이 붙어 있습니다.

// dist/index.js 마지막 줄
//# sourceMappingURL=index.js.map

브라우저와 Node.js는 이 주석을 읽고 자동으로 소스맵을 불러옵니다.

왜 JS 파일명과 똑같이 만들까요? 다르면 안 되나요?

index.js → index.js.map. 이 패턴이 너무 당연하게 느껴지지 않나요?

사실 이름은 달라도 됩니다. JS 파일과 소스맵 파일을 연결하는 건 파일명이 아니라, JS 파일 맨 아래의 주석 한 줄입니다.

//# sourceMappingURL=index.js.map
//                   ^^^^^^^^^^^^
//                   여기에 적힌 경로로 소스맵을 찾아감

브라우저는 오직 이 주석만 봅니다. 따라서 이렇게 써도 동작합니다.

//# sourceMappingURL=debug-info.map       // 완전히 다른 이름
//# sourceMappingURL=sourcemaps/main.map  // 하위 디렉토리
//# sourceMappingURL=data:application/json;base64,eyJ2Z... // 파일 없이 인라인으로 embed

그렇다면 이름을 바꾸려면 코드의 어디를 수정해야 할까요? 우리 코드에서 index.js.map이 세 군데 등장합니다.

// Graph.ts (line 178~192): 세 곳이 모두 맞물려야 합니다
const map = bundle.generateMap({
  file: 'index.js.map',  // ① 소스맵 내부의 자기 파일명
  ...
});

fs.writeFileSync(path.join(distDir, 'index.js.map'), map.toString()); // ② 실제 저장 파일명

fs.appendFileSync(
  path.join(distDir, 'index.js'),
  '\n//# sourceMappingURL=index.js.map',  // ③ JS 파일에 심는 참조 경로
);

세 곳 중 하나라도 어긋나면 소스맵 연결이 끊깁니다. 예를 들어 ③만 바꾸면 브라우저가 없는 파일을 찾으러 가고, ②만 바꾸면 브라우저가 여전히 index.js.map을 찾으려다 404를 냅니다.

그럼에도 <파일명>.map 관행이 굳어진 이유는 실용적인 이유 때문입니다.

결론적으로, 파일명은 관행이지 규칙이 아닙니다. 세 곳을 일관되게 맞추기만 하면 어떤 이름이든 동작합니다.

sources 상대 경로 확인

소스맵에 절대 경로가 포함되지 않았는지 확인해봅시다.

node -e "
  const fs = require('node:fs');
  const map = JSON.parse(fs.readFileSync('packages/@package/sample-lib/dist/index.js.map', 'utf-8'));
  console.log('sources:', map.sources);
"

정상이라면 아래처럼 상대 경로만 출력됩니다.

sources: [ 'src/index.js', 'src/components/Button.js' ]

절대 경로(/Users/han/...)가 보인다면 path.relative() 처리가 빠진 것입니다.

8. 마무리

이번 편에서 우리가 만든 것을 정리해봅시다.

1. Module 생성 시 — new MagicString(content)으로 원본 코드를 변환 이력 저장소에 담습니다.
2. ESM → CJS 변환 시 — magicString.overwrite(start, end, replacement)로 "원본 N번째 ~ M번째 자리가 새 코드로 바뀌었다"를 기록합니다.
3. 번들 조합 시 — bundle.addSource({ filename: 상대경로, content: magicString })으로 각 모듈의 이력을 통합합니다.
4. 소스맵 생성 시 — bundle.generateMap({ includeContent: true, hires: true })로 이력을 VLQ 인코딩 → mappings 문자열 → .map 파일로 저장합니다.

1편에서 처음 MagicString을 소개했을 때, 단순한 문자열 치환 도구처럼 보였습니다. 하지만 이제는 그 진짜 목적이 보입니다. 변환 이력을 기록하기 위한 장치였던 것입니다. 소스맵을 위해 처음부터 설계된 선택이었습니다.

에필로그: 여기서 더 나아간다면

소스맵까지 완성한 지금, 우리 번들러는 "번들러가 어떻게 동작하는가" 라는 질문에 충분히 답할 수 있는 도구가 됐습니다.
acorn으로 AST를 파싱하고, 모듈 그래프를 따라 의존성을 추적하고, MagicString으로 코드를 합치고, 소스맵으로 원본을 추적하는 것까지.

실제 번들러들은 여기에 더 많은 것을 올려놓습니다.

• Externals — react 같은 peer dependency를 번들에서 제외하고 런타임에 외부에서 주입받는 전략. 라이브러리 배포에 필수적입니다.
• Tree Shaking — ESM의 정적 구조를 분석해 실제로 사용되지 않는 export를 번들에서 제거합니다. import { one } from './math'만 썼다면 two, three는 번들에 들어가지 않습니다.
• Code Splitting — 번들을 여러 청크로 나눠 초기 로딩에 필요한 코드만 먼저 내려받게 합니다. 동적 import()가 분기점이 됩니다.
• Plugin System — webpack의 탭어블 훅, rollup의 플러그인 API처럼, 번들링 파이프라인의 각 단계에 외부 코드가 끼어들 수 있는 확장 지점을 만드는 구조입니다.
• Scope Hoisting — 모듈 경계를 제거해 함수 래퍼를 줄이고 런타임 오버헤드를 낮춥니다.
• HMR — 전체 페이지 리로드 없이 변경된 모듈만 런타임에 교체합니다.

이 중 어느 것을 열어봐도, 우리가 Step 1부터 다뤄온 개념들이 그 안에 있습니다.
acorn, AST, 모듈 그래프, 코드 생성. 실제 도구의 코드베이스가 낯설지 않을 겁니다. rollup이 비교적 읽기 쉽고, esbuild는 성능 관점에서 흥미롭습니다.

체크리스트 (Step 4)

• 소스맵이 "번들 좌표 → 원본 좌표" 변환표라는 개념을 이해했다.
• MagicString.overwrite()가 단순 치환이 아니라 이력 기록임을 이해했다.
• Bundle.addSource() → Bundle.generateMap() 흐름을 설명할 수 있다.
• AAAA VLQ 세그먼트가 [0, 0, 0, 0]을 의미함을 이해했다.
• VLQ가 숫자 대신 Base64 문자를 쓰는 이유(용량 절감)를 설명할 수 있다.
• 상대 좌표가 [0,0,0,0]에서 출발해 누적되는 릴레이 방식임을 이해했다.
• 소스맵을 통한 원본 코드 복구 가능성과 보안 위험을 설명할 수 있다.
• 오픈소스/비공개 라이브러리의 소스맵 배포 전략 차이를 설명할 수 있다.
• path.relative()를 써야 하는 보안 이유를 설명할 수 있다.
• dist/index.js.map의 sources가 상대 경로인지 직접 확인했다.

"지도는 완성됐다. 이제 길을 닦을 차례다."

지난 시간(Step 2. 코드를 데이터로 보는 법), 우리는 코드를 데이터 로 변환하고, 파일들 사이의 복잡한 관계를 그래프 로 그려냈습니다. 이제 우리 손에는 프로젝트의 모든 파일 정보가 담긴 '지도' 가 쥐어져 있습니다.
이제 남은 건 하나입니다. 이 흩어진 파일 조각들을 모아서, 브라우저가 실행할 수 있는 단 하나의 결과물 로 만드는 것입니다.

1. 그냥 텍스트로 합치면 안 되나요?

가장 단순하게 생각해봅시다. 번들링이란 결국 파일을 합치는 것이니, 리눅스의 cat 명령어처럼 파일 내용을 순서대로 이어 붙이면 되지 않을까요?

// a.js
const name = 'Module A';
console.log(name);

// b.js
const name = 'Module B';
console.log(name);

이 두 파일을 합쳐서 브라우저에서 실행해 봅니다. 결과는 어떨까요?

❌ Uncaught SyntaxError: Identifier 'name' has already been declared

처참한 실패입니다. 파일이 나뉘어 있을 때는 각자의 스코프가 보장되었지만, 하나로 합쳐지는 순간 모든 변수가 전역 스코프에 노출되면서 충돌이 발생하기 때문입니다.
이것이 바로 번들러가 단순히 파일을 이어 붙이는 것과 다른 점입니다. 번들러의 첫 번째 임무는 "각 모듈의 독립적인 스코프를 지켜주는 것" 입니다.

2. 해결책: 함수로 벽 세우기

자바스크립트에서 변수를 가두는 가장 확실한 방법은 무엇일까요? 바로 함수 입니다.
우리는 모듈의 코드를 즉시 실행 함수 로 감싸서, 외부와 격리된 스코프를 만들어줄 것입니다.

🏗️ Before & After

[Before: 충돌하는 코드]

const name = 'Module A'; // 💥 전역 변수 충돌!
const name = 'Module B';

[After: 평화를 되찾은 코드]

(function () {
  const name = 'Module A'; // ✅ 이 함수 안에서만 유효함
})();

(function () {
  const name = 'Module B'; // ✅ 안전함
})();

이제 변수 name은 각자의 함수 안에 갇혔습니다. 아무리 많은 파일을 합쳐도 변수 이름이 겹칠 걱정은 없습니다.

💡 기술적 배경

이 방식은 Webpack 1~3 버전 시절의 "고전적인" 방식입니다. 최신 도구들(Rollup, Vite)은 성능을 위해 Scope Hoisting 기술을 써서 함수 없이 합치기도 하지만, 모듈 시스템의 본질인 '격리' 를 이해하기에는 이 방식이 가장 직관적입니다.

3. 그래서 전체 모양은 어떻게 생겼나요?

개별 파일을 함수로 감싸는 건 알겠습니다. 그럼 이 수십 개의 함수들을 어떻게 엮을까요?
우리는 이 함수들을 객체에 담고, 그 위에서 관리자가 하나씩 꺼내 쓰는 구조를 만들 겁니다.

// ✅ 우리가 만들 최종 번들 파일의 구조 (Blueprint)
(function (modules) {
  // 1. 관리자 (Runtime): 모듈을 꺼내서 실행해주는 역할 (다음 섹션에서 구현)
  function require(id) {
    modules[id]();
  }
  require(0); // 시작!
})({
  // 2. 창고 (Module Map): 파일들이 ID표를 달고 대기하는 곳
  0: function () {
    console.log('I am Entry');
  },
  1: function () {
    console.log('I am Button');
  },
});

이제 우리의 목표가 명확해졌습니다. 위쪽의 require 함수를 구현하고, 아래쪽의 모듈을 채워 넣으면 됩니다.

4. 브라우저엔 require가 없다

이제 우리는 각 파일을 함수로 안전하게 감쌌습니다. 그런데 문제가 하나 있습니다. 함수 안에서 다른 모듈을 불러오려면 require가 필요한데, 브라우저에는 require가 없습니다.

// 브라우저 콘솔
require(1); // 🚨 Uncaught ReferenceError: require is not defined

따라서 번들러는 단순히 파일을 합치는 것뿐만 아니라, Node.js의 모듈 시스템(require, module, exports)을 브라우저에서 흉내 내는 런타임 을 직접 주입해 줘야 합니다.

미션: 런타임 심 만들기

우리가 구현해야 할 런타임 함수는 크게 3가지 미션을 수행해야 합니다.

Mission 1. 모듈을 실행하고 값을 반환하라

가장 기본적인 역할입니다. 모듈 ID를 받아서 해당 함수를 실행하고, 그 결과(exports)를 내뱉습니다.

function require(id) {
  const module = { exports: {} };

  // 모듈 함수 실행 (의존성 주입!)
  // 여기서 require, module, exports를 인자로 넘겨줍니다.
  modules[id](require, module, module.exports);

  return module.exports;
}

Mission 2. 두 번 실행하지 마라

이게 핵심입니다. 모듈은 import 할 때마다 실행되는 게 아닙니다. 최초 한 번만 실행되고, 그 뒤로는 저장된 값을 써야 합니다.
약 모듈이 호출될 때마다 매번 새로 실행된다면, 전역 설정이나 상태값들이 계속 초기화되어 버립니다. import는 싱글톤처럼 한 번 만든 객체를 계속 돌려써야 합니다.

const cache = {}; // ✅ 실행 결과를 저장할 메모리

function require(id) {
  // 1. 이미 실행한 적 있나요? 그럼 그거 씁시다.
  if (cache[id]) return cache[id].exports;

  // ... (실행 로직) ...
}

Mission 3. 순환 참조를 막아라

A -> B -> A 구조에서 캐시가 없다면, require가 무한히 호출되어 Stack Overflow가 발생합니다.

빈 객체라도 먼저 캐시에 등록해두면, 두 번째 A를 불렀을 때 루프를 끊고 실행을 이어갈 수 있습니다. 이것이 Node.js가 순환 참조를 버티는 원리입니다.

실제 런타임 구현 코드 보기 (Graph.ts:107)

5. 실행 흐름

번들 코드가 실행될 때, require가 어떻게 모듈을 넘나드는지 시각적으로 확인해 봅시다.

sequenceDiagram
    participant Runtime as Bundler Runtime
    participant Entry as Entry Module (ID: 0)
    participant Dep as Dependency (ID: 1)

    Runtime->>Entry: 1. execute(0) 호출
    activate Entry
    Note over Entry: 코드 실행 중...<br/>require(1) 발견
    Entry->>Runtime: 2. require(1) 요청
    activate Runtime
    Runtime->>Dep: 3. execute(1) 실행
    activate Dep
    Note over Dep: exports.data = 'value'
    Dep-->>Runtime: 4. module.exports 반환
    deactivate Dep
    Runtime-->>Entry: 5. 결과('value') 전달
    deactivate Runtime
    Note over Entry: 나머지 코드 실행
    Entry-->>Runtime: 6. 실행 완료
    deactivate Entry

6. 최종 모습: ESM을 CJS로 통역하기

마지막 퍼즐 조각은 문법 변환입니다.

우리가 작성한 코드는 최신 ESM(import/export) 이지만, 방금 만든 런타임은 CJS(require/exports) 기반입니다. 번들러는 코드를 합치기 전에, import 문을 require 함수 호출로 바꿔치기 해야 합니다.
이 과정은 우리가 지난 시간에 만든 Module.ts가 AST를 분석해서 수행합니다.

Case 1. 가져오기

모듈 ID를 기반으로 값을 가져옵니다.

// Input (ESM)
import { a } from './a';

// Output (CJS)
const { a } = require(1);

Case 2. 이름 내보내기

exports 객체에 속성을 추가합니다.

// Input (ESM)
export const b = 1;

// Output (CJS)
const b = 1;
exports.b = b;

Case 3. 기본 내보내기

default라는 이름의 속성으로 할당합니다.

// Input (ESM)
export default c;

// Output (CJS)
exports.default = c;

Case 4. 전체 내보내기

대상 모듈의 모든 수출항을 복사합니다.

// Input (ESM)
export * from './a';

// Output (CJS)
Object.assign(exports, require(1));

AST 적용하기: import가 require로 바뀌는 순간

"AST를 분석해서 코드를 바꾼다" 는 말이 너무 추상적인가요? 실제 코드 레벨에서 어떤 일이 일어나는지 현미경으로 들여다보겠습니다.

우리의 목표는 아래의 ESM 코드를 CJS 코드로 성형수술하는 것입니다.

// 📄 원본 (src/index.js)
import { sum } from './math.js';

👇 변환 목표

// 📄 결과물 (dist/bundle.js 내부)
const { sum } = require(1); // './math.js'가 ID: 1로 변환됨

이 과정은 Module.ts 내부의 transform 메서드에서 일어납니다. 핵심 로직을 3단계로 쪼개 봅시다.

1단계: AST 탐색

acorn이 파싱한 AST에서 ImportDeclaration 타입을 가진 노드를 찾습니다.

// AST Node (ImportDeclaration)
{
  "type": "ImportDeclaration",
  "start": 0, // "import"가 시작되는 인덱스
  "end": 32, // 세미콜론(;)이 끝나는 인덱스
  "source": {
    "type": "Literal",
    "value": "./math.js" // 👈 우리가 필요한 경로!
  },
  "specifiers": [...]
}

2단계: ID 치환

번들러는 이미 Graph를 만들면서 './math.js'에게 주민등록번호(ID) 1번을 부여했습니다.

// Module.ts의 transform 메서드 내부
const sourcePath = node.source.value; // './math.js'
const moduleId = this.mapping.get(sourcePath); // 1 (Graph가 미리 매핑해둠)

// 이제 우리는 require('./math.js') 대신 require(1)을 쓸 수 있습니다.

3단계: MagicString 조작

이제 magic-string이라는 메스를 들 차례입니다. 원본 코드를 건드리지 않고, 기존 import 문을 덮어쓰기 합니다.

// 실제 구현 로직 (의사 코드)

// 1. 가져올 변수들 문자열 만들기: "{ sum }"
const imported = node.specifiers
  .map(s => `${s.imported.name}: ${s.local.name}`)
  .join(', ');

// 2. require 문 만들기: "const { sum } = require(1);"
const newCode = `const { ${imported} } = require(${moduleId});`;

// 3. 덮어쓰기! (수술 집도)
// 원본 코드의 start(0)부터 end(32)까지를 newCode로 교체합니다.
this.magicString.overwrite(node.start, node.end, newCode);

AST 변환 로직 전체 보기 (Module.ts:121)

💡 참고: ESM 번들링은 안 하나요?

최신 라이브러리들은 CJS뿐만 아니라 ESM 포맷도 함께 지원하는 Dual Package 전략을 사용합니다. 하지만 우리는 번들러의 동작 원리(스코프 격리, 런타임 구현)를 깊이 이해하기 위해, 로직이 가장 명확하게 드러나는 CJS 번들링 구현에 집중했습니다.

7. 직접 돌려봅시다

백문이 불여일견입니다. 우리가 만든 번들러가 실제로 잘 동작하는지 확인해 볼까요?

$ pnpm --filter @package/sample-lib run build

📦 Minibundler started...
🛠️  Generating bundle...
📦 Generated CJS Bundle: dist/index.js
✨ Bundle built successfully!

생성된 dist/index.js를 열어보면, 수십 개의 파일이 하나의 IIFE 안에 질서 정연하게 들어있는 모습을 볼 수 있습니다. 우리는 브라우저 안에 작은 Node.js를 만들어낸 것입니다.

// dist/index.js (생성된 번들 결과물)
(function (modules) {
  // 우리가 만든 런타임 함수 (require, cache 등)
  function require(id) { ... }
  require(0); // 엔트리 실행
})({
  0: function (require, module, exports) { /* ... */ },
  1: function (require, module, exports) { /* ... */ },
});

이제 이 파일이 정말로 동작하는지 실행해 볼까요?

# 2. 결과물 실행 (Node.js 환경에서 테스트)
$ node -e "
  const lib = require('./packages/@package/sample-lib/dist/index.js');
  console.log('1 + 2 =', lib.sum(1, 2));
"

# 1 + 2 = 3 (정상 실행!)

Next Step

이제 파일은 합쳐졌고, 브라우저에서도 잘 돌아갑니다. (bundle.js) 하지만 치명적인 문제가 하나 남았습니다.

에러가 나면 무조건 bundle.js 1번째 줄이라고 뜹니다. 수천 줄로 합쳐진 코드 뭉치 속에서, 도대체 원본 소스 코드의 몇 번째 줄이 문제인지 어떻게 알 수 있을까요?

다음 편, [Step 4. 디버깅의 마법, 소스맵] 에서 번들러가 망가뜨린 코드를 다시 원본으로 되돌리는 기술을 다뤄보겠습니다.

체크리스트 (Step 3)

• 단순히 파일을 합치면 전역 변수 충돌이 일어남을 이해했다.
• IIFE가 어떻게 스코프를 격리하는지 설명할 수 있다.
• 런타임 구현에서 캐시 가 왜 필수적인지(싱글톤, 순환 참조) 이해했다.
• ESM 문법이 CJS 런타임(require)으로 변환되는 과정을 확인했다.

"코드는 텍스트가 아니다. 트리다."

1편에서는 번들러를 왜 만들어야 하는지, 그리고 magic-string이라는 도구를 맛봤습니다. 이제 본격적으로 코드를 분석하고, 여러 파일을 하나로 묶기 위한 준비를 시작해 봅시다.

이번 편의 목표는 "흩어진 파일들을 찾아내어 하나의 지도로 그리는 것" 입니다.

1. 어디서부터 묶어야 할까?

번들러가 가장 먼저 해야 할 일은 무엇일까요? 바로 "진입점" 을 찾는 것입니다.

우리가 작성한 수많은 파일들을 하나로 묶으려면 어떻게 해야 할까요? 무턱대고 폴더의 모든 파일을 합치는 것은 좋은 방법이 아닙니다. 시작점이 되는 파일(보통 index.js나 main.js) 을 읽고, 그 파일이 어떤 다른 파일들을 필요로 하는지(import) 추적해 나가야 합니다. 이것이 바로 의존성 그래프를 그리기 위한 첫 단추입니다.

2. 코드는 단순한 텍스트가 아니다

자, 이제 엔트리 파일의 내용을 읽어왔습니다. 그 다음은 파일 내용에서 import ... from ... 구문을 찾아내야 합니다.

왜 정규표현식을 썼을까?

문자열에서 특정 패턴을 찾는 것. 개발자라면 누구나 가장 먼저 떠올리는 도구가 있죠. 바로 정규표현식 입니다.

직관적으로 생각해보면, import 문은 꽤 단순한 패턴을 가지고 있어 보입니다.

import { a } from './a.js';
import b from './b.js';

"어? 이거 그냥 문자열 검색으로 찾으면 되는 거 아냐?"

그래서 처음에는 정규표현식을 떠올리게 됩니다. 정규표현식은 강력하고, 빠르고, 무엇보다 구현하기 쉽습니다. 복잡한 파서를 도입하는 것보다 String.match() 한 방이면 끝날 것 같았죠.

const regex = /import\s+.*\s+from\s+['"](.*)['"];?/g;
const code = "import { a } from './a.js';";
const result = code.match(regex);
// 오! 찾아졌다! ./a.js

3. 정규표현식은 파서가 아니다

예외 케이스

하지만 코드가 조금만 복잡해져도 정규표현식은 무력해집니다.

// 1. 주석 처리된 코드
// import { a } from './a.js';

// 2. 문자열 내부의 텍스트
const message = "Please import './config.js' first.";

// 3. 줄바꿈이 포함된 import
import { somethingLong } from './utils.js';

정규표현식은 문맥을 모릅니다. 주석인지, 문자열인지 구분하지 못하고 "패턴이 맞네? 가져와!" 라고 외칠 뿐입니다. 결국 우리는 엉뚱한 파일을 import 하려고 시도하다가 에러를 뿜어내는 번들러를 마주하게 됩니다.

결론: 코드를 단순한 텍스트로 처리하려다간 큰코다칩니다. 구조로 봐야 합니다.

4. 도구 1: AST - 코드를 해부하다

그래서 등장하는 도구가 바로 AST(Abstract Syntax Tree, 추상 구문 트리) 입니다.

이름을 하나씩 뜯어보면 이렇습니다.

• Abstract: 세미콜론, 괄호, 공백 같은 표면적인 문법 요소는 버리고, 의미만 남긴다는 뜻입니다.
• Syntax: 코드의 문법적 구조 — 변수 선언인지, 함수 호출인지, import 문인지를 구분합니다.
• Tree: 결과물이 부모-자식 관계를 가진 트리 구조라는 뜻입니다.

결국 AST란, 우리가 작성한 코드를 컴퓨터가 이해하기 쉬운 트리 형태의 데이터 구조로 바꿔놓은 것입니다.

사실 AST는 번들러만의 도구가 아닙니다. ESLint가 코드 규칙을 검사할 때, Prettier가 코드를 포맷팅할 때, Babel이 최신 문법을 변환할 때 — 모두 AST를 기반으로 동작합니다. 이번 편에서 AST를 다루는 관점을 익히면, 이 도구들이 내부에서 뭘 하는지도 보이기 시작합니다.

자바스크립트 파서인 acorn을 사용하면 코드를 다음과 같이 분석해줍니다.

코드가 데이터가 되는 과정

// 입력 코드
import { name } from './name.js';

이 한 줄의 코드는 파서를 거치면 거대한 JSON 객체가 됩니다. 핵심만 요약했습니다.

{
  "type": "Program",
  "body": [
    {
      "type": "ImportDeclaration",
      // "이건 import 선언문이야!"
      "source": {
        "type": "Literal",
        "value": "./name.js"
        // "경로는 이거야!"
      },
      "specifiers": [
        {
          "type": "ImportSpecifier",
          "imported": {
            "name": "name"
          }
          // "name을 가져왔어!"
        }
      ]
    }
  ]
}

이제 우리는 type === 'ImportDeclaration'인 노드만 골라내면 됩니다. 주석이나 문자열은 ImportDeclaration이 아니므로 자연스럽게 무시됩니다. 정확도 100%의 import 탐지기가 생긴 셈입니다.

Code Module.ts 구현

우리의 번들러에서 파일 하나를 담당하는 Module 클래스는 이렇게 AST를 생성합니다.

// packages/@package/bundler/src/Module.ts

import * as fs from 'fs';
import * as acorn from 'acorn';

export class Module {
  constructor(filePath: string) {
    this.content = fs.readFileSync(filePath, 'utf-8');
    // 1. 코드를 AST로 변환
    this.ast = acorn.parse(this.content, {
      ecmaVersion: 'latest',
      sourceType: 'module',
    });
  }

  init() {
    // 2. AST를 순회하며 import 찾기
    this.ast.body.forEach(node => {
      if (
        node.type === 'ImportDeclaration' &&
        typeof node.source.value === 'string'
      ) {
        // 찾았다! 의존성 추가
        this.dependencies.push(node.source.value);
      }
    });
  }
}

전체 코드 보기: Module.ts GitHub

5. 도구 2: Resolve - 진짜 파일 찾기

AST를 통해 './utils'라는 문자열을 찾아냈습니다. 하지만 이건 파일 경로의 힌트일 뿐, 실제 파일 시스템상의 위치는 아닙니다.

• ./utils가 utils.js인가? utils.ts인가?
• 아니면 utils/index.js인가?

이 힌트를 가지고 실제 파일을 찾아내는 과정을 Resolve라고 합니다. Node.js는 꽤 복잡한 Resolve 규칙을 가지고 있지만, 우리는 핵심적인 부분만 구현해 봅시다.

Code 확장자 추론하기

// packages/@package/bundler/src/Graph.ts

resolve(importPath: string, importer: string): string {
  // 1. 현재 파일(importer)이 있는 폴더 기준
  const baseDir = path.dirname(importer);
  let fullPath = path.resolve(baseDir, importPath);

  // 2. 확장자가 없으면 .js 붙여보기 (간단한 버전)
  // (실제로는 .mjs, .json, 디렉토리 내 index.js 등도 고려해야 합니다)
  if (!fullPath.endsWith('.js')) {
    fullPath += '.js';
  }

  return fullPath;
}

이제 './utils'를 요청하면 /Users/.../src/utils.js라는 절대 경로를 얻을 수 있습니다.

6. 도구 3: DFS & Graph - 지도를 그리자

이제 재료는 다 모였습니다.

1. 파일 내용을 읽어서 fs
2. import 문을 찾아내고 AST
3. 그 파일의 절대 경로를 알아냈습니다. Resolve

이제 이 과정을 모든 파일에 대해 반복하면 됩니다. index.js에서 시작해서 꼬리에 꼬리를 물고 찾아 들어가는 방식, 바로 DFS 깊이 우선 탐색입니다.

그래프 구축 과정 Graph.ts

우리의 Graph 클래스는 Map 자료구조를 사용하여 전체 파일들의 관계를 저장합니다.

// packages/@package/bundler/src/Graph.ts

export class Graph {
  // 방문한 모듈을 저장하는 저장소 (Visited Map)
  modules = new Map<string, Module>();

  createModule(filePath: string): Module {
    // 1. 모듈 생성 및 AST 분석
    const module = new Module(this.nextId++, filePath);
    module.init(); // import 구문 추출

    // 2. 저장소에 등록
    this.modules.set(filePath, module);

    // 3. 의존성 재귀 탐색 (DFS)
    module.dependencies.forEach(importPath => {
      const absolutePath = this.resolve(importPath, filePath);
      const childModule = this.createModule(absolutePath);

      // 4. 부모-자식 연결 (Mapping)
      module.mapping.set(importPath, childModule.id);
    });

    return module;
  }
}

이렇게 하면 index.js 하나만 넣어도 연결된 모든 파일이 modules 맵에 담기게 됩니다. 파일 시스템이라는 거대한 미로를 탐험해서 지도를 완성하는 것이죠.

7. 하이라이트: "순환 참조"

하지만 DFS에는 치명적인 약점이 있습니다. 바로 순환 참조입니다.

A -> B -> A 무한 루프

만약 a.js가 b.js를 부르고, b.js가 다시 a.js를 부른다면 번들러 내부에서는 호출 스택 이 계속 쌓이게 됩니다.

이 과정을 시퀀스 다이어그램 으로 보면, 함수가 끝나지 않고 계속 깊어지는 것을 확인할 수 있습니다.

sequenceDiagram
    autonumber
    participant Main as 번들러 (Main)
    participant A as a.js
    participant B as b.js

    Main->>A: createModule('a.js')
    activate A
    Note right of A: "어? b.js가 필요하네?"

    A->>B: createModule('b.js')
    activate B
    Note right of B: "어? a.js가 필요하네?"

    B->>A: createModule('a.js')
    activate A
    Note left of A: ❌ 또 호출됨 (재귀)

    A->>B: createModule('b.js')
    activate B
    Note right of B: ⚠️ 또 호출됨 (재귀)

    Note over A,B: ❌ Call Stack 한계 도달... ❌
    B--x Main: ❌ Stack Overflow Error!
    deactivate B
    deactivate A
    deactivate B
    deactivate A

결국 Stack Overflow가 발생하며 번들러는 장렬히 전사합니다.

해결책: 방명록 Visited Map

이 문제를 해결하려면 "어? 너 아까 왔던 앤데?" 라고 알아볼 수 있어야 합니다. 우리가 Graph 클래스에 만들어둔 modules 맵이 바로 그 방명록 역할을 합니다.

createModule(filePath: string): Module {
  // 0. 방명록 확인: 이미 왔던 파일이면, 기존 모듈 반환하고 끝!
  if (this.modules.has(filePath)) {
    return this.modules.get(filePath)!;
  }

  // ... (새 모듈 생성 로직)
}

이 간단한 체크 하나로 번들러는 무한 루프의 늪에서 탈출할 수 있습니다.

실전 bundler-playground 예제

실제 예제 코드 packages/@package/bundler-playground 에는 a.js -> c.js -> a.js 순환 참조 케이스가 들어있습니다.

// a.js
import { c } from './c.js';

// c.js
import { a } from './a.js'; // 범인!

우리의 번들러는 c.js를 처리할 때 a.js를 다시 만나지만, modules.has() 덕분에 쿨하게 지나갑니다. 덕분에 그래프는 안전하게 완성됩니다.

8. 에필로그: 이제 지도는 완성됐다

우리는 이제 코드를 텍스트가 아닌 데이터 AST로 바라보게 되었습니다. 그리고 그 데이터를 바탕으로 파일들의 복잡한 관계를 그래프 Graph로 그려냈습니다.

하지만 아직 파일들은 제각각 떨어져 있습니다. 다음 단계에서는 이 그래프를 바탕으로 파일들을 하나의 파일로 합치는 Bundling 과정을 다룹니다.

이때 가장 골치 아픈 문제는 "변수 이름 충돌" 입니다. a.js의 const name과 b.js의 const name이 만나면 어떻게 될까요?

다음 편, Step 3. 번들링과 스코프 격리에서 계속됩니다.

🔗 참고 자료

• 전체 소스 코드 Graph.ts
• AST Explorer AST 구조를 눈으로 확인해보세요!

이전에 작성한 하루 만에 끝날 줄 알았던 디자인 시스템 배포가 3주 걸린 이유 에서는 "패키지를 배포하는 과정" 그 자체에 집중했습니다.
이번에는 시선을 조금 더 안쪽으로 돌려보려 합니다. 바로 배포물이 만들어지는 생성 과정 입니다.

배포는 성공적으로 마쳤지만, 정작 결과물이 어떤 원리로 만들어지는지 제대로 이해하지 못한 채 도구에만 의존하고 있다는 의문이 들었습니다. "남들이 다 쓰니까", "이게 표준이라니까" 라며 무심코 넘겼던 설정값들이 실제로는 번들러 내부에서 어떤 판단을 내리게 만드는 걸까요?

STEP 1: 당연한 것에 던지는 질문

npm 배포 과정을 정리하면서 계속해서 들었던 질문들이 있습니다. 이 질문들이 이번 시리즈의 기준이 됩니다.

• 결합의 원리: 소스 코드는 수십 개인데, 왜 결과물은 하나로 합쳐질까요? 그 경계는 누가, 어떤 기준으로 정하는 걸까요?
• 설정의 실체: package.json의 main, module, exports, sideEffects 값들은 번들러의 동작에 어떤 영향을 줄까요?
• 의존성의 선별: 모든 의존성을 번들에 포함해야 할까요? external과 peerDependencies는 어떤 기준으로 분류하는 것일까요?
• 트리 쉐이킹: 코드를 직접 실행해보지도 않고, 어떻게 사용하지 않는 코드라고 판단하여 제거할 수 있을까요?

이 시리즈는 이러한 질문들에 대해 이론적인 답변을 찾는 대신, 직접 구현하며 답을 찾아가는 기록입니다. 라이브러리 번들러를 직접 만들어보며 그 블랙박스를 열어보려 합니다.

STEP 2: "Tsup 쓰면 되는데요?"

맞습니다. Tsup, Vite, Turbopack 같은 좋은 도구가 이미 존재합니다. 그런데 굳이 직접 번들러를 만들어보는 이유는 도구의 원리를 이해하기 위해서입니다.

이 과정을 통해 다음 3가지를 얻을 수 있습니다.

1. 에러 메시지 해석 능력

Uncaught ReferenceError, Module not found 에러를 만났을 때, 번들러가 그래프를 그리는 과정을 알면 원인을 파악하기 쉽습니다.

2. 도구에 대한 적응력

Webpack, Rollup, Esbuild, Turbopack 등 도구의 이름은 바뀌어도 Parsing, Graph, Linking이라는 본질적인 아키텍처는 변하지 않습니다. 원리를 알면 새로운 도구를 익히는 데 도움이 됩니다.

STEP 3: 범위 설정

"프로덕션 레벨의 번들러"를 만드는 것이 목표가 아닙니다. 복잡한 기능은 제외하고, 번들러의 본질적인 역할에만 집중합니다.

다루는 것

'간단한 번들러' 를 목표로 다음 5가지를 직접 구현합니다.

1. Resolve: import 경로를 찾아내는 Node.js의 규칙
2. Dependency Graph: 파일을 읽어 AST로 변환하고, 파일 간 관계 연결
3. Transform: magic-string을 활용한 코드 조작
4. Generate: IIFE로 스코프를 격리하여 하나로 병합
5. Sourcemap: 디버깅을 위해 원본과 번들 연결

다루지 않는 것

번들러의 본질을 이해하는 데 불필요한 기능은 과감히 생략합니다.

• HMR, Dev Server
• Circular Dependency
• JS 이외의 에셋 처리
• 고도화된 Minification

STEP 4: 로드맵

오직 '모듈을 찾아 하나로 합친다' 는 본질에 집중합니다.

Step 1. 개념과 도구

• 번들러의 역사적 맥락
• ESM이 번들링에 유리한 이유
• 코드 조작 도구 Magic String

Step 2. 그래프 그리기

• 파일을 읽어 AST로 변환
• import를 추적해 의존성 그래프 구축
• 파일을 찾는 과정 구현

Step 3. 번들링과 스코프

• 그래프를 순회하며 코드 병합
• IIFE로 스코프 격리
• 브라우저용 require 함수 구현

Step 4. 완성도 높이기

• 소스맵 원리 파악 및 구현
• react 같은 외부 라이브러리 제외 처리

마치며: 이런 분들께 추천합니다

아래 항목 중 하나라도 해당한다면, 이 시리즈가 도움이 될 것입니다.

• tsup.config.ts 설정이 꼬일 때마다 새로 만들고 싶다는 생각이 든다.
• 배포 후 모듈을 찾을 수 없다는 연락을 받으면 당황스럽다.
• CJS와 ESM이 섞여 있을 때 발생하는 에러를 명확히 설명하기 어렵다.
• 단순히 도구를 사용하는 단계를 넘어 원리를 이해하고 싶다.

번들러라는 블랙박스를 함께 열어보겠습니다.

이 글에서는 자바스크립트 모듈 시스템의 발전 과정과 번들러가 필수적인 이유, 그리고 우리가 구현할 번들러의 주요 도구들을 살펴봅니다.

모듈 시스템의 발전

1. 전역 스코프 문제

초기 자바스크립트는 파일 간 스코프 구분이 없었습니다. a.js에서 선언한 변수는 전역 객체 window에 할당되어 b.js에서도 접근 및 수정이 가능했습니다.

<script src="jquery.js"></script>
<script src="slider.js"></script>
<script src="main.js"></script>

서로 다른 파일에서 동일한 변수명을 사용할 경우, 나중에 로드된 스크립트가 이전 값을 덮어쓰는 문제가 발생했습니다. 이를 방지하기 위해 개발자들은 네임스페이스 객체를 사용하거나 복잡한 변수명 규칙을 적용해야 했습니다.

2. IIFE 패턴

전역 스코프 오염을 막기 위해 IIFE 패턴이 널리 사용되었습니다.

(function () {
  var privateVar = 'I am safe';
  window.MyModule = {
    sayHello: function () {
      console.log(privateVar);
    },
  };
})();

함수 스코프를 활용하여 내부 변수를 격리하고, 외부에서 필요한 기능만 명시적으로 노출하는 방식입니다. 우리가 구현할 번들러의 결과물 또한 이 패턴을 사용하여 모듈 간 격리를 보장합니다.

3. CommonJS

2009년 Node.js의 등장과 함께 CommonJS 시스템이 도입되었습니다.

// math.js
const add = (a, b) => a + b;
module.exports = add;

// main.js
const add = require('./math');

파일 단위의 모듈 개념이 확립되었으나, 브라우저 환경에서는 require 함수가 존재하지 않고 동기 로딩 방식으로 인한 성능 문제가 있어 클라이언트 사이드에서 직접 사용하기에는 제약이 있었습니다.

4. ESM

2015년 ES6, 자바스크립트 공식 모듈 시스템인 ESM이 표준화되었습니다. 브라우저에서도 <script type="module">을 통해 모듈 시스템을 네이티브로 지원하게 되었습니다.

번들러의 필요성

최신 브라우저가 ESM을 지원함에도 불구하고 Vite나 Webpack 같은 번들러가 필요한 이유는 다음과 같습니다.

1. 성능 최적화: 수많은 모듈 파일을 개별적으로 로드하면 네트워크 요청 오버헤드가 발생합니다. 번들링을 통해 파일을 하나 또는 소수 로 병합하여 로딩 성능을 개선할 수 있습니다.
2. 생태계 호환성: npm 생태계의 많은 라이브러리는 여전히 CommonJS로 작성되어 있습니다. 번들러는 이를 브라우저가 이해할 수 있는 형태로 변환하고 통합하는 역할을 수행합니다.

우리가 구현할 번들러는 모듈 탐색, 의존성 그래프 구성, 파일 병합 과정을 수행합니다.

기반 기술 1: ESM과 정적 분석

우리가 만들 번들러는 ESM 문법을 기반으로 동작합니다.

정적 분석

CommonJS의 require는 런타임에 실행되는 함수이므로 조건부 호출이 가능합니다. 이는 코드를 실행하기 전에는 의존성을 완벽히 파악하기 어렵게 만듭니다.

반면 ESM의 import 구문은 정적입니다. 파일 최상단에 위치해야 하며, 코드를 실행하지 않고도 의존성 관계를 파악할 수 있습니다. 이는 번들러가 의존성 그래프를 정확하게 구성하고, 사용하지 않는 코드를 제거하는 트리 쉐이킹을 구현하는 기반이 됩니다.

Live Binding

ESM은 값을 복사하지 않고 참조합니다.

• CJS: 모듈 호출 시점의 값을 복사합니다.
• ESM: 원본 변수에 대한 참조를 유지합니다.

이러한 특성은 순환 참조 해결에 유리합니다. CJS에서는 실행 순서에 따라 미완성된 객체를 참조하여 에러가 발생할 수 있지만, ESM은 참조가 유지되므로 모듈 실행이 완료되면 올바른 값에 접근할 수 있습니다.

기반 기술 2: Magic String

번들러 구현의 가장 중요한 작업은 소스 코드 문자열 조작입니다. import 구문을 제거하거나 변환하고, 코드를 하나의 파일로 합치는 작업이 필요합니다.

단순한 문자열 치환은 원본 코드의 인덱스를 변경시키므로, 소스맵 생성이나 추가적인 코드 분석을 어렵게 만듭니다.

Magic String 라이브러리 활용

magic-string 라이브러리는 원본 문자열의 인덱스를 유지하면서 변경 사항을 관리합니다.

// packages/@package/bundler/src/Module.ts 예시

private transformImportDeclaration(node) {
  // 1. 모듈 ID 조회
  const depId = this.mapping.get(node.source.value);
  const requireCall = `require('${depId}')`;

  // 2. 변환 코드 생성
  // import { a } from './file' -> const { a } = require('file')
  const replacement = `const { ${specifierStr} } = ${requireCall};\n`;

  // 3. 원본 인덱스 기반으로 덮어쓰기
  this.magicString.overwrite(node.start, node.end, replacement);
}

이 방식을 사용하면 여러 변환 작업이 중첩되더라도 원본 소스 코드의 위치 정보를 정확하게 추적하여 신뢰성 있는 소스맵을 생성할 수 있습니다.

실습 구조

이 시리즈의 실습 코드는 다음 경로에서 확인할 수 있습니다.

packages/@package/bundler/
    src/index.ts   # 진입점: 설정 -> 빌드 -> 생성
    src/Graph.ts   # 의존성 그래프 구축 및 번들 생성
    src/Module.ts  # 개별 파일 AST 파싱 및 변환

단계별 참조 파일

• Step 1: src/index.ts 전체 파이프라인 이해
• Step 2: src/Module.ts 파일 분석, src/Graph.ts 관계 연결
• Step 3: Graph.generate() 번들링, Module.transform() 코드 변환
• Step 4: dist/index.js.map 소스맵 확인

실습: 최소 기능 번들러 구현

번들러의 기본 구조를 이해하기 위해, 파일을 읽고 출력하는 간단한 코드를 작성해봅니다.

import fs from 'node:fs';
import MagicString from 'magic-string';

// 1. 파일 읽기
const content = fs.readFileSync('./src/index.js', 'utf-8');

// 2. MagicString 인스턴스 생성
const bundle = new MagicString(content);

// 3. 코드 변환 및 추가
bundle.prepend('/* Bundled by Custom Bundler */\n');

// 4. 결과물 출력
fs.writeFileSync('./dist/bundle.js', bundle.toString());
console.log('Build completed.');

이 코드는 단순한 파일 복사에 가깝지만, 추후 3번 단계에 AST 분석, 의존성 그래프 탐색, 코드 변환 로직을 추가하여 완전한 번들러로 발전시킬 것입니다.

다음 단계

다음 글에서는 코드를 데이터로 변환하여 분석하는 AST 분석과 의존성 그래프 구현에 대해 다룹니다.

[Step 2. 그래프 그리기 - Resolve & AST 로 이동] Coming Soon

"만약 내일 당장 '프랑스'가 서비스 국가로 추가된다면? 그리고 한국에서 '사업자 유형'에 따라 결제 수단이 달라져야 한다면?" 이 질문들이 우리 팀의 결제 시스템 설계를 완전히 바꿔놓았습니다.

🎭 Prologue: "팀장님의 무리한(?) 요구"

어느 날 오후, 코드 리뷰 중에 팀장님이 툭 던지신 질문 하나가 뇌리를 스쳤습니다.

"이번에 프랑스(France) 런칭 결정됐어. 기존 PayPal이랑 무통장 입금 은 그대로 쓰고, 프랑스 국민 결제인 'Carte Bancaire' 도 추가해야 돼."

여기까진 괜찮았습니다. 그런데 덧붙이시더군요.

"아, 그리고 한국(KR) 쪽 로직도 바꿔야 해. 사업자 유형이 추가됐거든. '해당 없음'이면 그냥 기존처럼 Toss 쓰면 되는데, '개인/법인 사업자' 를 선택하면 세금계산서 때문에 '신용카드(Toss)' 랑 '법인계좌 송금(무통장)' 만 허용해야 돼."

순간 머릿속이 하얘졌습니다. '국가별 분기도 벅찬데, 국가 안에서 또 조건부 분기라고? if (country === 'KR' && businessType === 'CORPORATE')...'

하지만 대답을 주저했습니다. 직감적으로 알았거든요. "if문 몇 개 추가" 가 쌓이고 쌓여서, 나중엔 "건드리기만 하면 터지는 레거시 코드" 가 된다는 것을요.

그래서 결심했습니다. "복잡한 요구사항? 설정과 규칙만 정의하면 끝납니다." 라고 자신 있게 말할 수 있는 구조를 만들어보자고요.

🛑 1. 평범한 일상: "if문의 지옥" (Before)

초기 결제 시스템은 단순했습니다. 하지만 요구사항이 늘어날수록 코드는 스파게티가 되어갔습니다.

// 😱 흔한_결제_로직.ts
const handlePayment = async (country, businessType, paymentMethod) => {
  if (country === 'KR') {
    if (businessType === 'NONE') {
      // 다 됨 (Toss)
    } else {
      // 사업자는 무통장이랑 카드만 됨
      if (paymentMethod === 'VIRTUAL_ACCOUNT')
        throw new Error('사업자는 가상계좌 안됨');
      // ...복잡한 검증 로직...
    }
    // 토스 호출...
  } else if (country === 'FR') {
    // 프랑스 로직...
  }
};

문제점 분석:

1. 관심사의 혼재: '누가 결제 가능한가(Business Rule)'와 '어떻게 결제하는가(Implementation)'가 한 함수에 뒤섞여 있습니다.
2. 높은 결합도: PG사 API가 변경되면 비즈니스 로직까지 영향을 받고, 반대로 비즈니스 규칙이 바뀌면 결제 호출 코드도 수정해야 합니다.
3. 확장성 부족: 조건이 추가될 때마다 if-else 블록을 찾아 헤매야 합니다.

💡 2. 해결책: "변하는 것과 변하지 않는 것을 분리하라"

무작정 디자인 패턴을 도입하기보다, 문제의 본질을 먼저 파악했습니다. 우리가 겪는 고통의 원인은 "변하는 것(국가별 규칙, PG사 API)" 과 "변하지 않는 것(결제 요청 행위)" 이 섞여 있기 때문이었습니다.

이를 분리하기 위해 우리는 다음 세 가지 패턴을 적재적소에 배치했습니다.

🛠️ 우리가 선택한 도구들

🔌 Step 1: Adapter Pattern (통역사 두기)

Why? Toss는 requestPayment(), PayPal은 createOrder()... PG사마다 메서드명도, 파라미터도 다릅니다. 우리 비즈니스 로직이 이 차이를 다 알 필요가 있을까요?

Solution 우리 시스템은 requestPayment라는 하나의 언어만 쓰기로 하고, 중간에 통역사(Adapter) 를 두어 변환하게 했습니다.

// IPaymentAdapter.ts
export interface IPaymentAdapter {
  requestPayment(params: PaymentRequestParams): Promise<void>;
}

이제 Toss, PayPal, General(무통장) 각각의 어댑터가 내부적으로 지지고 볶든 말든, 우리 코드는 깔끔해집니다.

⚖️ Trade-off:

• (👍 장점) PG사가 변경되거나 추가되어도 클라이언트 코드는 수정할 필요가 없습니다. (OCP)
• (👎 단점) 간접 계층의 복잡성: 단순 함수 호출이면 될 것을 Interface -> Adapter -> Real Implementation으로 거쳐 가야 하므로, 코드 추적이 한 단계 더 깊어지고 초기 구조 잡는 비용이 듭니다.

🏗️ Step 2: Factory Pattern (규칙 자판기)

Why? "한국 사업자는 무통장만 됨" 같은 규칙은 어디에 둬야 할까요? UI 컴포넌트? 훅? 아닙니다. 이런 규칙이 여기저기 흩어지면 유지보수 지옥이 열립니다.

Solution 규칙을 한곳에 몰아넣고, 입력(Context)만 넣으면 결과(Available Providers)를 뱉어주는 자판기(Factory) 를 만들었습니다.

// PaymentFactory.ts
export const PaymentFactory = {
  getAvailableProviders(context: { country: string; businessType?: string }) {
    // 🇰🇷 한국: 사업자 유형에 따른 동적 필터링 (이곳에 분기 로직이 캡슐화됩니다!)
    if (context.country === 'KR') {
      if (['CORPORATE', 'INDIVIDUAL'].includes(context.businessType)) {
        return [PaymentProviderType.TOSS, PaymentProviderType.GENERAL];
      }
      return [PaymentProviderType.TOSS];
    }
    // ...
  },

  getAdapter(providerType: PaymentProviderType): IPaymentAdapter {
    const adapters: Partial<
      Record<PaymentProviderType, new () => IPaymentAdapter>
    > = {
      [PaymentProviderType.TOSS]: TossAdapter,
    };

    const AdapterClass = adapters[providerType];
    if (!AdapterClass) {
      throw new Error(`${providerType}에 대한 어댑터를 찾을 수 없습니다.`);
    }
    return new AdapterClass();
  },
};

⚖️ Trade-off:

• (👍 장점) 복잡한 if-else 로직이 Factory 한곳으로 격리되어 관리가 쉬워집니다.
• (👎 단점) 클래스나 객체가 늘어나고, 코드의 흐름을 따라가려면(Factory -> Adapter) 파일을 이동해야 하는 번거로움이 생깁니다.

🔗 3. 통합: "이 모든 것을 하나로 묶는 마법, usePayment Hook"

제아무리 좋은 설계도 사용하기 불편하면 실패합니다. usePayment 훅은 이 모든 복잡성을 감추고 단일 인터페이스를 제공합니다.

sequenceDiagram
    participant UI as Component
    participant Hook as usePayment
    participant Factory as PaymentFactory
    participant Adapter as PaymentAdapter

    UI->>Hook: requestPayment(KR, TOSS, params)
    Hook->>Factory: getAvailableProviders(context)
    Factory-->>Hook: [TOSS, GENERAL]
    Hook->>Hook: Validate Provider (Is TOSS allowed?)
    Hook->>Factory: getAdapter(TOSS)
    Factory-->>Hook: TossAdapter
    Hook->>Adapter: requestPayment(params)
    Adapter-->>Hook: Success

요약: UI가 훅을 호출하면, 훅은 팩토리에 생성을 위임하고, 반환된 어댑터를 실행합니다.

// usePayment.ts
export const usePayment = () => {
  const requestPayment = async (
    context: { country: string; businessType?: string },
    providerType: PaymentProviderType,
    params: PaymentRequestParams,
  ) => {
    // 1. 비즈니스 로직 검증 (Factory에게 위임)
    const allowed = PaymentFactory.getAvailableProviders(context);
    if (!allowed.includes(providerType)) {
      throw new Error('지원하지 않는 결제 수단입니다.');
    }

    // 2. 어댑터 획득 및 실행
    const adapter = PaymentFactory.getAdapter(providerType);
    await adapter.requestPayment(params);
  };

  return { requestPayment };
};

🛡️ 4. 디테일: Zod로 데이터 무결성 철통 방어

설계가 유연해진 만큼, 입력값에 대한 엄격한 검증이 중요해졌습니다. 팩토리가 올바른 객체를 생성하려면 입력값(Context)의 무결성이 보장되어야 하기 때문입니다.

"사업자일 때만 무통장 입금이 가능하다"는 규칙을 UI뿐만 아니라 데이터 스키마 레벨에서도 검증하고 싶었습니다. Zod의 discriminatedUnion이 빛을 발하는 순간입니다.

// schemas.ts

// 1. 일반 유저 (해당 없음)
const KrNormalSchema = z.object({
  businessType: z.literal('NONE'),
  paymentMethod: z.literal(PaymentProviderType.TOSS), // 문자열 대신 enum 사용
});

// 2. 사업자 (개인/법인)
const KrBusinessSchema = z.object({
  businessType: z.enum(['INDIVIDUAL', 'CORPORATE']),
  paymentMethod: z.enum([
    PaymentProviderType.TOSS,
    PaymentProviderType.GENERAL,
  ]), // 문자열 대신 enum 사용
  registrationFile: z.instanceof(File), // 사업자등록증 필수
});

// 3. 통합 스키마
export const KrPurchaseSchema = z.discriminatedUnion('businessType', [
  KrNormalSchema,
  KrBusinessSchema,
]);

이제 잘못된 조합(예: NONE인데 GENERAL 선택)은 아예 타입 에러가 나거나 검증을 통과할 수 없습니다.

⚡️ Strategy Pattern을 활용한 'Lazy Loading UI'

로직만 분리한다고 끝이 아닙니다. UI도 전략 패턴으로 분리할 수 있습니다. 특히 React의 lazy를 활용하면, 한국 유저는 프랑스 결제 폼 코드를 다운로드할 필요가 없게 되어(Code Splitting) 초기 로딩 속도까지 잡을 수 있습니다.

// SelfPurchaseOrder/Create/index.tsx
import { Suspense, lazy } from 'react';

// 1. 전략 정의 (Code Splitting)
const UI_STRATEGIES = {
  KR: lazy(() => import('./KrCreate')), // 한국: 복잡한 사업자 로직 포함
  FR: lazy(() => import('./FrCreate')), // 프랑스: 간소화된 UI
  DEFAULT: lazy(() => import('./GlobalCreate')),
};

// 2. 전략 선택 (Strategy Selection)
const PurchaseFormStrategy = ({ country }: { country: string }) => {
  // UI_STRATEGIES의 키에 대한 타입 가드 함수
  const isUIStrategyKey = (key: string): key is keyof typeof UI_STRATEGIES => key in UI_STRATEGIES;

  const TargetForm = isUIStrategyKey(country)
    ? UI_STRATEGIES[country]
    : UI_STRATEGIES.DEFAULT;
  return <TargetForm />;
};

// 3. 상위 컴포넌트에서 우아한 로딩 처리 (Suspense at Page Level)
export const PurchasePage = ({ country }: { country: string }) => {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <PurchaseFormStrategy country={country} />
    </Suspense>
  );
};

🎉 5. 결론: "복잡성은 숨기고, 유연함은 챙기고"

이제 팀장님의 질문에 자신 있게 대답할 수 있습니다.

"팀장님, 프랑스 추가든 한국 사업자 조건 변경이든 걱정 마세요. 비즈니스 규칙은 Factory에 모아뒀고, 실행은 Adapter가 알아서 하고, 데이터는 Zod가 지키고 있습니다. 요구사항만 말씀해 주세요."

✅ 이번 리팩토링으로 얻은 것

1. 비즈니스 로직 격리: '사업자 유형별 제한' 같은 규칙이 PaymentFactory 한곳에 모였습니다.
2. 안전한 확장: 새 국가나 결제 수단 추가 시 기존 코드를 건드리지 않아도 됩니다. (OCP)
3. 타입 안전성: Zod를 통해 복잡한 조건부 유효성 검사를 선언적으로 해결했습니다.

📝 바로 적용해보기 체크리스트

• 비즈니스 규칙(if)이 UI 컴포넌트에 흩어져 있지 않은지 확인한다.
• 조건에 따라 객체 생성이 달라진다면 Factory Pattern을 도입한다.
• 실행 로직이 다양하다면 Adapter로 인터페이스를 통일한다.
• 복잡한 폼 검증은 Zod Discriminated Union으로 해결해본다.

여러분은 어떠신가요?

혹시 지금 보고 계신 코드에 "국가 코드"나 "유저 타입"을 체크하는 if문이 화면 곳곳에 흩어져 있나요? 그곳이 바로 팩토리 패턴이 필요한 지점일 수 있습니다. 댓글로 경험을 공유해주세요!

태그: #TypeScript #DesignPattern #FactoryPattern #AdapterPattern #Zod #Refactoring #결제시스템

"평소 기술 관련 답변을 잘 해주시는데, 회고에는 기술적인 내용이 하나도 없네요."

그때 깨달았습니다. 개인브랜딩은 말을 잘하는 게 아니라, 내가 어떤 문제를 어떤 방식으로 해결하는지를 검증 가능한 산출물(글/PR/발표) 로 남기는 일이라는 것. 이 글은 그 전환의 기록입니다.

📊 한눈에 보는 2025

블로그: “어떤 글이 읽히는지”를 확인하다

처음엔 "내가 이런 글을 써도 될까?" 가 제일 컸습니다. 하지만 첫 글이 일주일 만에 500회 조회수를 넘기면서(초기 지표), “내가 어떤 고민으로 개발하는지” 를 글로 증명할 수 있겠다는 확신이 생겼습니다.

연말에 조회수 TOP3를 뜯어봤습니다.

• 4시간 만에 Node.js PR 승인받기
• 15줄에서 2줄로: useSyncExternalStore 기반 React Toast 시스템 설계법
• React 에러 구조 설계: throw만으로 선언적 에러 핸들링 하기

세 글의 공통점을 분석해보니, 반응 좋은 글에는 패턴이 있었습니다.

• 제목은 과정이 아니라 결과가 먼저 보인다. (숫자/시간/변화량처럼 “얼마나?”가 즉시 답이 나는 형태)
• 권위 있는 대상 + 나의 실전 경험이 같이 있다. (튜토리얼/이론이 아니라 “충돌/기여/실패/통과”의 신뢰 신호)
• 문제 상황이 한 줄로 선명하다. (“이 상황에서 어떻게 했는지”가 제목만 봐도 보인다)
• 본문은 왜 쓰게 됐는지 → 기존 방식의 한계 → 선택 → 결과 흐름을 가진다.

개념 중심/정리형 글은 검색 유입은 되지만 반응 지표는 약한 편이었습니다. 그래서 앞으로는 제목을 만들 때 숫자 / 실패·충돌 / 특정 대상 / 변화 한 문장 중 3개 이상을 기본 체크리스트로 두려고 합니다.

오픈소스: 레퍼런스를 “외부 검증”으로 만들다

처음 오픈소스에 기여할 때는 "이런 사소한 것을 PR로 올려도 될까?" 망설였습니다. 그런데 한 번 머지/승인을 경험하니 관점이 바뀌었습니다. 개인 프로젝트의 결과는 “내가 잘 됐다고 느끼는 것”에 머물 수 있는데, 오픈소스는 외부 리뷰와 릴리스라는 검증이 붙습니다.

2025년에는 특히 아래 경험이 글/발표의 근거가 됐습니다. (링크는 글 끝에 정리했습니다.)

• Node.js: util.inspect 숫자 포맷팅 버그 재현 → 테스트 작성 → 수정 → 4시간 만에 PR 승인
• Mantine: Slider의 onChangeEnd 동기화 이슈를 useRef로 해결, 머지 후 릴리스 포함
• Next.js: 2번 실패 후, 원인/의도 파악을 거쳐 최종 PR 성공
• gemini-cli: Promise.allSettled() 병렬 처리로 전환해 74% 성능 개선(408ms→107ms)

오픈소스 기여는 단순히 횟수가 아니라, 글과 발표의 밀도를 높여주는 재료가 됐습니다. 특히 실패/거절/리뷰 대응은 문서로 배울 수 없는 실전 경험이었습니다.

컨퍼런스: 무대 위에 서다

쑥떡콘: Panda CSS 1년 사용기

"Panda CSS 1년 사용기" 로 첫 발표를 했습니다. 10건 이상의 질의응답을 주고받으며 사람들이 무엇을 궁금해하는지 알게 되었고, 이 경험이 더 나은 콘텐츠를 만드는 밑거름이 되었습니다.

FEConf 2025: 오픈소스 밥상차리기

그리고 FEConf 2025. 내가 해도 되는 건가? 하는 마음으로 라이트닝 토크에 신청했고, 선정되었습니다. 3개월간 준비해서 35장의 슬라이드를 11장으로 압축하며 핵심만 남겼습니다.

"오픈소스 밥상차리기: 환경설정과 디버깅편" 이라는 주제로 무대에 섰을 때, 다리가 떨렸지만 이 생각을 했습니다. "나는 이미 충분히 준비됐어. 이제 내 이야기를 들려주기만 하면 되는 거야."

발표 후 가장 기뻤던 피드백은 "오늘 집에 가서 바로 PR 하나 올려볼게요!" 였습니다. 누군가의 첫 걸음을 도왔다는 것, 그것이 발표자로서 가장 큰 보람이었습니다.

TeoConf: 3주간의 디자인 시스템 배포 삽질기

세 번째 컨퍼런스인 TeoConf에서는 디자인 시스템 배포 이야기를 꺼냈습니다. 하루면 끝낼 줄 알았던 배포가 3주로 늘어나고, 300KB를 목표로 했던 번들이 20MB까지 불어나는 등 소재는 차고 넘쳤습니다. 문제는 “할 이야기가 많다”는 게 곧 좋은 발표가 아니라는 것이었습니다.

사전 피드백에서 가장 뼈아팠던 말은 이거였습니다.

• 핵심 메시지가 보이지 않는다
• 설명 흐름이 너무 기술적이다
• 청중과의 연결고리가 약하다

리허설에서 “그래서 제일 어려웠던 게 뭐였나요?” 라는 질문에 답을 못한 순간, 내가 발표를 정리하지 못했다는 걸 인정하게 됐습니다. 결국 TeoConf가 내게 남긴 건 번들링/빌드 삽질의 해결책보다, 발표는 기술을 나열하는 자리가 아니라 청중이 가져갈 한 문장을 만드는 과정이라는 깨달음이었습니다.

선순환 구조의 형성

2025년 가장 큰 성과는 개인 브랜딩을 의지가 아니라 구조로 만든 것입니다.

블로그 글은 꾸준히 쓰고 있었고, 그 글을 기반으로 FEConf 같은 곳에 신청하며 발표도 함께 늘려갔습니다. 여기에 오픈소스 기여가 더해지면서 실전 경험과 레퍼런스가 폭발적으로 쌓였고, 글과 발표의 밀도가 올라가며 네트워크가 확장되고 더 많은 기회가 열렸습니다.

(블로그: 기록/정리) ↔ (컨퍼런스: 신청/발표) + (오픈소스: 기여) → 실전 경험·레퍼런스 → 신뢰·네트워크 → 더 많은 기회 → 다시 글/발표/기여

이 선순환이 작동하기 시작하면서, 더 이상 "브랜딩을 위해 무언가를 해야 한다" 는 부담이 사라졌습니다. 그냥 좋아서 하는 일들이 자연스럽게 브랜드를 만들어갔습니다.

배운 것들

• 브랜딩은 ‘자기소개’가 아니라 ‘증명’이다. 신뢰는 “잘할 것 같다”가 아니라 “이미 해본 흔적(글/PR/발표)”에서 나온다.
• 작은 기여도 쌓이면 흔적이 남는다. 27회 기여하니 내 PR 히스토리가 곧 신뢰 지표가 됐다.
• 발표는 청중 중심이다. “할 이야기가 많다”를 버리고 “청중이 가져갈 한 문장”을 먼저 만든다.
• 실패를 숨기지 않을수록 설득력이 커진다. 실패→수정→통과의 과정이 재현 가능한 학습 재료가 됐다.

마치며

처음에는 "내가 공유할 만한 가치가 있을까?" 라고 의심했습니다. 하지만 작은 용기를 내어 글을 쓰고, PR을 올리고, 발표를 하다 보니 생각보다 많은 사람들이 “경험의 맥락”에서 가치를 발견했습니다.

개인 브랜딩의 핵심은 "대단한 무언가" 가 아니라 "진정성 있는 공유" 였고, 시행착오와 꾸준함이 전문성을 만든다는 것을 배웠습니다.

2026년에는 이 선순환 구조를 더 단단하게 만들어, 한국 프론트엔드 커뮤니티에 긍정적인 영향을 주는 개발자가 되고 싶습니다.

💬 여러분의 이야기를 들려주세요

• 2025년 여러분의 가장 큰 성장은 무엇이었나요?
• 오픈소스 기여를 시작하고 싶은데 망설여지시나요?
• 블로그를 시작하려는데 주저하고 계신가요?

댓글로 여러분의 경험과 고민을 나눠주세요! 🙌

링크 모음

• Node.js PR: https://github.com/nodejs/node/pull/59379
• Node.js 글: https://blog.sangwook.dev/posts/nodejs-contribution/
• Mantine PR: https://github.com/mantinedev/mantine/pull/7660
• Mantine Release: https://github.com/mantinedev/mantine/releases/tag/7.17.4
• Mantine 글: https://blog.sangwook.dev/posts/first-open-source-contribution/
• Next.js 실패 PR: https://github.com/vercel/next.js/pull/80428
• Next.js 성공 PR: https://github.com/vercel/next.js/pull/81146
• Next.js 글: https://blog.sangwook.dev/posts/nextjs-contributor/
• gemini-cli PR #1: https://github.com/google-gemini/gemini-cli/pull/3288
• gemini-cli PR #2: https://github.com/google-gemini/gemini-cli/pull/4763
• gemini-cli 글: https://blog.sangwook.dev/posts/ai-opensource-contribution/

이번 테오콘 발표는 내게 하나의 도전이었다.
디자인 시스템 배포라는, 나에게 깊은 경험이지만 청중에게는 다소 생소할 수 있는 주제를 어떻게 풀어낼 것인가.
그리고 그 과정에서 **“발표는 기술을 나열하는 자리가 아니라, 청중이 가져갈 한 문장을 만드는 과정”**임을 뒤늦게 깨닫게 되었다.

1. 신청 — 아쉬움에서 출발한 도전

FEConf가 끝나고 나에게 큰 아쉬움이 남았다.
준비 과정에서는 20분 넘게 하고도 모자랐던 내용이 실제 발표에서는 10분으로 끝났다.

“좀 더 깊게 파고들 수 있었는데…”
이 아쉬움을 해결하고 싶어 테오콘에 신청했다.
그리고 이번에는 디자인 시스템 배포라는, 오랫동안 정리하고 싶던 주제를 발표로 풀어보기로 했다.

2. 사전 미팅 — ‘할 이야기가 많다’는 것이 함정

테오와 1:1 사전 미팅을 하며 내 경험을 시간순으로 설명했다.
삽질도 많았고 배운 것도 많았기에 테오도 “이야기 자체는 좋다”고 했다.
문제는 너무 많다는 것.
이때부터 슬슬 불안함이 스며들기 시작했다.

나는 이 경험을 온전히 전달하고 싶었는데,
그 욕심이 발표의 범위를 걷잡을 수 없이 넓히고 있다는 걸 그때는 몰랐다.

3. 발표 자료 만들기 — 내용은 40페이지, 피드백은 생각보다 혹독했다

먼저 글을 쓰고 그 글을 슬라이드로 옮기는 방식으로 준비했다.
자연스레 슬라이드는 40페이지가 넘어갔다.

사전 녹화를 제출하고 받은 피드백은 예상보다 훨씬 날카로웠다.

• 핵심 메시지가 보이지 않는다
• 설명 흐름이 너무 기술적이다
• 목소리가 너무 차분하다
• 청중과의 연결고리가 약하다

하나하나 곱씹으며 수정했지만 사실 이때도 “어디를 수정해야 하는지” 명확하게 알지 못했다.

4. 리허설 — 무엇이 어렵냐는 질문에 답하지 못했다

사전 리허설에서 테오가 물었다.

“그럼, 이 발표에서 제일 어려운 부분이 뭐였나요?”

그 질문에 나는 정확하게 답하지 못했다.
그 순간 하나를 깨달았다.

“나는 지금 무엇이 문제인지도 모르는 상태로 발표를 준비하고 있었구나.”

다른 스피커들의 발표를 보며 그들은 논리 흐름이 깔끔했고,
청중 집중을 유지하기 위한 장치도 자연스러웠다.
나는 그걸 잘 못하고 있다는 사실만 명확해졌다.

슬라이드는 수정하다보니 어느새 70페이지를 넘어갔고,
당일 아침까지도 수정이 계속됐다.

레이니가 1:1로 피드백을 주었고
그제야 슬라이드의 ‘정렬’이 잡히기 시작했다.

5. 발표 당일 — 슬라이드는 일방향이지만, Q&A는 나를 드러낼 수 있었다

발표 당일 리허설을 한 번 더 했다.
긴장은 되었지만 견딜 만했다.
다른 스피커들과 인사하며 분위기도 좋았다.

하지만 세션 2가 시작되자 압박감이 올라왔다.
앞 발표자가 짤로 분위기를 띄우는 걸 보며
“나도 이런 걸 넣을걸…” 하는 생각이 들었다.

그리고 내 순서가 되었다.

준비한 대로 발표를 진행했지만, 솔직히 내가 무슨 말을 했는지 기억이 잘 나지 않는다.
발표가 약 22분 정도로 끝나고 Q&A 시간이 되자 그제야 정신이 돌아왔다.

놀랍게도 발표보다 Q&A가 훨씬 편했다.

• 서비스와 패키지 분리를 어떻게 보나요?
• 디자인 시스템 적용 시 CSS override 전략은?
• Todo list가 많은데 현재 진행 상황은 어떻게 되었나요?
• 20mb 중에 결국 무엇이 문제였나요?
• 예측 불가능한 문제는 어떻게 해결하고 레퍼런스를 찾으시나요?

이 질문들은 발표에서 다 담지 못한 부분들이었고,
내가 평소 고민하던 문제들이었다.
단방향 발표보다 상호작용 속에서
내 경험의 진짜 맥락을 더 잘 전달할 수 있었다.

6. 뒷풀이 — 해방감, 그리고 다시 생각하게 된 ‘발표의 본질’

발표가 끝나자 안도감이 밀려왔다.
우리 조 사람들과 연락처를 주고받고, 60명 가까이 모인 뒷풀이도 갔다.

운영진분들이 직접 서빙까지 하며 분위기를 살려주었고,
테이블마다 이직 이야기, 회사 이야기, 각자의 고민이 오갔다.

행사가 마무리되고 테오와 잠시 이야기를 나눴다.
나는 “좀 아쉽다, 제대로 전달 못한 것 같다”고 말했다.
그러자 테오는 혼도 내고, 격려도 해주었다.
그리고 “내년에 또 발표하라”고 했다.

그 말을 듣고 생각했다.

다음 발표는 ‘내가 하고 싶은 이야기’가 아니라
‘청중이 한 문장이라도 가져갈 이야기’를 해야겠다.

레이니가 나를 “아픈 손가락”이라 말했다는 이야기를 들었을 때,
미안함과 고마움이 동시에 밀려왔다.

🔍 이번 발표에서 내가 얻은 것, 놓친 것, 다음에 할 것

내가 얻은 것

• 오프라인에서 대중 앞에 서본 경험 자체가 큰 성장이었다.
• 기술적 내용을 발표 형태로 풀어보는 시도가 좋았다.
• 청중과의 Q&A에서 내가 가진 경험의 ‘진짜 가치’를 전달할 수 있었다.

아쉬웠던 점

• 욕심이 많아 발표 범위를 좁히지 못했다.
• 내가 하고 싶은 말이 우선이었고, 청중 메시지가 정리되지 않았다.
• 기술 설명과 스토리텔링의 균형이 어려웠다.
• 슬라이드에 집중하느라 청중과 눈을 잘 맞추지 못했다.

다음 발표에서는 이렇게 할 것

• 청중이 무엇을 가져갈지 먼저 정의하기.
• 전달 범위를 과감하게 줄이기.
• 발표 자료 제작을 더 효율적으로 할 수 있는 도구나 방식을 찾기.

🎯 마지막 한 문장

이번 발표는 완벽하지 않았다.
하지만 덕분에 발표의 본질을 알게 됐다.

좋은 발표는 기술을 나열하는 것이 아니라, 청중이 가져갈 ‘단 하나의 문장’을 찾아가는 과정이다.

이 한 문장을 배웠다는 것만으로도,
이번 발표는 충분히 의미 있었다.

타팀 기획자님이 내 자리로 다가왔다.

"개발자님, 저희 팀에서도 그 디자인 시스템 쓸 수 있을까요? 버튼이랑 인풋 컴포넌트가 정말 예쁘던데..."

당시 디자인 시스템은 완성해둔 참이었다. 모노레포 안에서는 잘 돌아가고 있었다. Button, Input, Card... 약 60개 정도?

"아, 그거요? 별거 아니에요."

나는 자신만만하게 대답했다.

"NPM에 올리기만 하면 되니까 하루면 될 것 같은데요?"

기획자님의 환한 미소가 아직도 기억난다. "정말요? 그럼 이번 주 안에 가능할까요?"

"네, 금방이에요!"

그리고 3주가 지났다.

하루라고 했던 작업은 21일이 걸렸다. 그 사이에 나는:

• 빌드 도구와 10일을 싸웠고
• 20MB 괴물 패키지를 만들어냈고
• CSS 충돌로 머리를 쥐어뜯었고
• 무한 재귀 배포를 중단시켰다

지금 돌아보면 그날의 나에게 말해주고 싶다.

"별거 아닌 일은 없어. 특히 배포는."

그땐 좋아 보였는데...

완벽한 계획 (예상 기간: 1일)

머릿속으로 그린 계획은 완벽했다.

• 트리셰이킹
• CSS 번들
• Type 지원
• 배포 문서
• 자동 배포 시스템

"배포 말고는 이미 잘 되어 있는거니 별 문제 없겠지?"

과연 이 계획대로 될까?

우리 프로젝트 상황

모노레포 구성

• 신규 프로젝트와 디자인 시스템을 동시에 구현
• 코드 공유와 의존성 관리의 효율성 고려
• 향후 다른 팀으로의 확장 가능성

기술 스택 선택: Mantine + Panda CSS

당시 팀 상황을 고려하면 현실적인 선택이었다:

• 개발/디자인 리소스 부족
• 디자인 시스템 구축 경험 부족
• Tailwind 문법에 대한 팀 내 선호도 문제

Mantine의 높은 완성도와 Panda CSS의 유연성이 우리 팀에 적합해 보였다.

현재 프로젝트 구조

monorepo/
├── design-system          # 메인 디자인 시스템
└── packages/
    ├── @package/core      # HTTP 클라이언트, 상태 코드
    ├── @package/constants
    ├── @package/entities
    └── @package/service

디자인 시스템 패키지와 4개의 공통 내부 패키지로 구성.

배포 요구사항

타팀에서 디자인 시스템을 사용하기 위해 충족해야 할 조건들:

1. NPM 패키지 배포: GitHub Packages, 버전 관리, 문서화
2. 외부 설치 가능: 모노레포 외부 서비스에서 손쉬운 설치
3. 환경 호환성:
   • 타팀 환경: Remix + Tailwind
   • 우리 환경: Mantine + Panda CSS
4. 내부 패키지 의존성 처리: 4개 내부 패키지 의존성 관리

"별거 아니겠지"라고 생각한 1일 예상 작업이 3주간의 여정으로 시작됐다.

1주차: 빌드 지옥편 - "나는 라이브러리 번들을 몰랐다"

일단 빌드 부터 해보자!

빌드 도구 선택: tsup

여러 빌드 도구를 검토한 끝에 tsup을 선택했다.

tsup을 선택한 이유:

• 본인이 라이브러리 배포에 대한 지식이 전무
• 간편한 config → 러닝 커브 낮음
• TypeScript 타입 자동 생성 지원 (.d.ts 파일 자동 생성)
• esbuild 기반 → go 기반 가볍고 빠름
• 후처리 파이프라인과 통합 용이 → onSuccess 훅으로 다양하고 편리한 통합 가능

첫 번째 config는 심플했다:

export default defineConfig({
  entry: ['src/index.ts', 'preset.ts'],
  splitting: true,
  sourcemap: true,
  clean: true,
  dts: true,
  format: ['esm'],
  outDir: 'dist',
  minify: true,
});

첫 번째 벽: Panda styled-system

"자, 이제 빌드만 하면 끝이다."

tsup 설정도 했고, entry point도 지정했고. 터미널에 pnpm build를 입력했다.

엔터.

그리고 1초 만에.

[ERROR] Could not resolve '@styles/patterns'

"...뭐?"

빌드가 실패했다. 첫 시도부터 바로 실패.

에러 메시지를 다시 읽어봤다. '@styles/patterns'를 찾을 수 없다고? 분명 개발 환경에서는 잘 동작하고 있었는데...

"아, 빌드 환경에서는 경로가 다른가?"

구글링을 시작했다. tsup styled-system error, panda css build...

30분간의 검색 끝에 알게 된 것:

1. Panda CSS의 styled-system은 인스톨 시점에 생성되는 폴더다
2. tsup이 빌드를 실행할 때는 아직 존재하지 않는다
3. @styles alias도 tsup이 모른다

해결책:

1. 빌드 전에 panda prepare를 먼저 실행 → styled-system 폴더 생성
2. esbuildOptions에 alias 경로 직접 지정

첫 번째 벽은 넘었다. 그런데 이게 끝이 아니었다.

예상하지 못한 SVG 문제

우리는 SVGR을 사용해서 SVG를 리액트 컴포넌트로 변환하고 있었다.

// common
export { default as AddPerson } from '../common/AddPerson.svg';

tsup이 JS 모듈을 기대했지만 svg가 들어있어서 에러 발생.

RollupError: "default" is not exported by "src/assets/svgs/common/AddPerson.svg"

SVG 지옥으로의 입장

Panda 문제를 해결하고 다시 빌드를 돌렸다.

이번엔 다른 에러가 떴다.

RollupError: "default" is not exported by "src/assets/svgs/common/AddPerson.svg"

"이번엔 SVG?"

우리는 SVGR을 사용해서 SVG를 리액트 컴포넌트로 변환하고 있었다. 개발 환경에서는 Vite가 알아서 처리해줬는데, tsup은 몰랐던 것이다.

"이것도 설정 문제겠지. 금방 해결되겠네."

1일차: 타입 설정으로 해결하려 함

svg.d.ts 파일을 만들고, 모듈 타입을 선언했다.

빌드 다시 실행.

같은 에러.

"타입만으로는 안 되나보네..."

2일차: GitHub 이슈 탐색

tsup svg error, rollup svg not exported...

관련 이슈들을 10개쯤 읽었다.

• "이거 써보세요" → 우리 상황이랑 다름
• "플러그인 쓰세요" → 버전이 안 맞음
• "그냥 파일로 처리하세요" → 그럼 컴포넌트는?

"나만 이런 문제 겪는 건가...?"

3일차: esbuild 플러그인 직접 작성

esbuild-plugin-svgr도 써보고, 직접 플러그인도 만들어봤다.

// 이것도 해보고, 저것도 해보고...

결과: 복잡성만 증가하고 새로운 에러만 발생.

"이거... 완벽하게는 안 되는 거 아닌가?"

3일이 지났다. SVG 타입 하나 때문에.

타협 #1: 완벽을 포기하는 순간

3일이 지났다.

SVG 타입 문제는 해결되지 않았다. 더 이상 방법이 떠오르지 않았다.

슬랙 메시지가 왔다. "진행 어떻게 되고 있어요?"

"아... 이거 언제까지 붙잡고 있을 건가?"

선택의 순간

완벽한 타입 지원 vs 일단 돌아가는 빌드

머릿속으로 따져봤다:

• 현재 우리 모노레포에서는 타입이 이미 잘 동작하고 있다
• 외부 팀도 IDE에서 타입 추론은 될 것이다
• SVG 타입 몇 개 누락되는 게 치명적인가?

"일단... 돌아가게 만들자."

결정: 이중 빌드 시스템

• tsup: 번들링만 담당 (dts: false)
• tsc: 타입 정의 파일만 별도 생성

// tsup.config.ts
onSuccess: 'npx tsc --project tsconfig.build.json';

빌드를 다시 실행했다.

✓ Build success
✓ Type declaration files created

"...된다!"

결과 확인:

• ✅ 빌드 성공
• ⚠️ SVG 관련 타입 일부 누락
• ⚠️ 몇몇 컴포넌트 타입 미지원
• ✅ 하지만 일단 돌아간다

완벽하진 않았다. 하지만 완벽을 기다리다간 영영 배포 못 할 것 같았다.

"첫 번째 타협이었다."

2주차: 로컬 테스트와 실제 적용 - "20MB... 하지만 일단 돌아간다"

이젠! 설치 테스트를 해보자!

빌드는 성공했다. 이제 실제로 설치해서 테스트해봐야 했다.

배포 사이클:

로컬 테스트
    ↓
실 서비스 설치
    ↓
코드 수정 및 push
    ↓
GitHub Actions CI & CD

pnpm pack으로 빠른 테스트 환경 구축

배포 전에 로컬에서 테스트하고 싶었지만, npm publish는 번거롭고 시간이 오래 걸렸다. 빠른 피드백 루프가 필요했다.

pnpm pack을 선택한 이유:

• 실제 배포와 동일한 형태의 .tgz 파일 생성
• 빠른 반복 테스트 가능

# 디자인 시스템 패키지에서
pnpm pack

# 다른 서비스에서
pnpm install ../design-system/design-system-0.0.2.tgz

피드백 루프:

1. 코드 수정
2. pnpm pack으로 패키지 생성
3. 테스트 환경에 재설치
4. 테스트 및 문제 발견
5. 반복

실제 배포 환경과 유사한 테스트 환경이 구축됐다.

dist 폴더가 없네?!?!!? 왜지?!?!!?

패키지를 설치하고 확인했더니... dist 폴더가 보이지 않았다.

package.json 스펙 공부 시작:

• exports: 어떤 파일을 외부에 노출할지
• types: 타입 선언 경로
• files: npm publish 시 포함할 파일
• publishConfig: 배포 레지스트리·접근 설정

"dist가 안 보이는 이유는 files 설정 때문일 수도 있다."

결국 package.json을 수정:

{
  "name": "@kit-design/ui",
  "version": "1.0.0",
  "files": ["dist"],
  "exports": {
    ".": {
      "types": "./dist/src/index.d.ts",
      "import": "./dist/index.js"
    },
    "./preset": {
      "types": "./dist/preset.d.ts",
      "import": "./dist/preset.js"
    }
  },
  "publishConfig": {
    "exports": {
      ".": {
        "types": "./dist/src/index.d.ts",
        "import": "./dist/index.js"
      }
    }
  }
}

이젠! 실서비스 설치 테스트를 해보자!

CSS 문제: 스타일 적용이 안 됨

디자인 시스템을 다른 서비스에 설치하고 첫 테스트를 진행했다. 모든 CSS를 지우고 시작했다.

컴포넌트 렌더링 상태:

• 컴포넌트는 정상적으로 렌더링됨
• 버튼, 카드 등 모든 컴포넌트가 Mantine 스타일로 렌더링됨
• 개발자 도구로 확인하니 class는 있지만 전역 CSS class가 없음

문제 원인: Panda CSS의 스타일 시트가 빌드 과정에서 미포함. Panda CSS 함수를 찾을 수 없었다.

Panda CSS 전달 문제 해결 시도

세 가지 방법을 시도했다:

1. 스타일 시트 생성

• 공식문서 따라함
• panda codegen --outfile styles.css
• 결과: 필요한 클래스가 전부 생성되지 않음

2. buildInfo 활용

• 공식문서 따라함
• Panda의 buildInfo
• 클라이언트 설정 필요
• 결과: 원인 불명으로 미동작

3. Styled-system 참조

• 미리 만든 styled-system을 클라이언트에 연결
• 결과: node_modules 참조 문제

모두 실패했다.

타협 #2: "일단 돌아가게"

Panda CSS 스타일이 적용되지 않는 문제. 3가지 방법을 시도했지만 모두 실패했다.

더 이상 방법이 떠오르지 않았다.

"빌드 파이프라인을 처음부터 다시 공부해야 하나...?"

시간과 리소스. 둘 다 부족했다.

결정: 소스코드를 통째로 넣자

{
  "files": ["src"]
}

styled-system도, 소스코드도, 전부. 최적화는 포기하고 일단 돌아가게.

빌드 성공. 스타일도 적용됨.

"무겁지만... 작동한다."

💡 "일단 돌아가게 만들자"

두 번째 타협이었다.

20MB 괴물의 탄생

빌드도 됐고, 타입도 생성됐다.

"이제 진짜 거의 다 왔다."

pnpm pack으로 최종 패키지를 만들었다.

✓ Tarball created: design-system-0.0.2.tgz

"자, 사이즈나 한번 볼까?"

터미널에 ls -lh를 쳤다.

20M design-system-0.0.2.tgz

"...20MB?"

눈을 의심했다.

다시 확인했다. 20MB가 맞았다.

"이게... 정상인가?"

비교해보기

급하게 다른 UI 라이브러리들을 확인했다.

• Mantine (약 120개 컴포넌트): 12MB
• MUI: 5.6MB
• 우리 디자인 시스템 (60개 컴포넌트): 20MB

"...두 배네."

패키지 내용 확인:

압축을 풀어서 들여다봤다.

node_modules/
├── src/ (전체 소스코드)
├── styled-system/ (Panda CSS 전체)
├── assets/ (폰트, SVG 전부)
└── ...

"아... 소스코드를 통째로 넣어서 그런 거구나."

다시 선택의 순간

최적화를 다시 시도할까? 아니면 일단 이대로 진행할까?

시계를 봤다. 벌써 2주가 지났다. 슬랙 메시지도 계속 오고 있었다.

"일단... 돌아가는 게 먼저다."

20MB. 무겁지만, 작동은 한다.

"최적화는... 나중에."

두 번째 타협이었다.

3주차-1: 실제 서비스 적용 - "CSS 충돌은 예상했지만 이 정도일 줄은..."

이제 기존 CSS 통합해보자!

불가능한 조합의 현실

"이제 진짜 거의 다 왔다."

로컬 테스트도 성공했다. 이제 실제 서비스에 적용만 하면 된다.

타팀 환경:

• Remix
• Tailwind CSS
• 레거시 전역 CSS

"환경이 좀 다르긴 한데... 뭐 CSS니까 괜찮겠지?"

기존 CSS 파일을 열어본 순간

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .button {
    background: red !important;
    padding: 10px !important;
  }
}

/* layer 없이 직접 작성된 스타일들 */
.some-legacy-class {
  margin: 20px !important;
  color: blue !important;
}

"...!important 지옥이네."

온갖 하드코딩 CSS가 !important로 도배되어 있었다. 우리 디자인 시스템 스타일이 전부 덮어씌워지고 있었다.

"이거... 어떻게 하지?"

Tailwind의 @layer 문법도 섞여있고, 레거시 스타일도 있고, 우리 Mantine + Panda CSS까지.

세 개의 CSS 시스템이 충돌하고 있었다.

@layer로 우선순위 제어

CSS @layer 문법을 알게 됐다.

/* 레이어 우선순위 설정 - Mantine을 낮은 우선순위로 배치 */
@layer reset, base, tokens, recipes, utilities, tailwind, mantine,
       panda-reset, panda-base, panda-tokens, panda-recipes, panda-utilities;

/* Mantine CSS를 낮은 우선순위 layer에 배치 */
@import '@mantine/core/styles.css' layer(mantine);

/* Tailwind도 별도 layer로 관리 */
@layer tailwind {
  @tailwind base;
  @tailwind components;
  @tailwind utilities;
}

이 방법이 유일하게 원하던 대로 된 해결책이었다.

결과:

• ✅ !important 없이도 스타일 제어 가능
• ✅ Mantine, Tailwind, Panda CSS 모두 공존 가능
• ✅ 우선순위 디버깅이 훨씬 쉬워짐

이러면 전부 다 잘 되나?

타협 #3: 완벽한 호환

현실: 다른 프레임워크 + 다른 CSS 라이브러리 + !important

근거: 서비스가 운영 중이어서 단번에 구조를 뒤엎는 것이 위험. 어쩔 수 없는 레거시는 점진적으로 수정하기로.

결정: 점진적 마이그레이션

디자인 시스템을 적용하면서 수동으로 수정해야 했다.

타협안:

• ⚠️ !important 문제가 남음
• ⚠️ 기존 스타일 일부 깨짐

실용적 결정:

• ✅ 실 서비스에 적용은 가능
• 어쩔 수 없는 레거시 청산으로 하나씩 수정하기로

"완벽하진 않지만, 돌아간다."

3주차-2: 배포 자동화 - "마지막까지 순탄하지 않았다"

이제 배포 파이프라인을 만들자!

로컬 테스트도 성공했다. 실 서비스 적용도 가능해졌다. 이제 자동 배포 시스템을 만들 차례였다.

목표:

1. GitHub Actions 워크플로우가 develop 브랜치 PR 이벤트에 각 패키지의 버전 체크
2. 변경할 버전이 있다면 version update 할 정보를 담아 json에 저장
3. 머지(push) 할 때 version update commit 생성

npm scope 문제 - 대참사의 시작

GitHub npm에 배포를 시도했을 때 예상치 못한 문제가 발생했다.

403 error

권한 부족?

원인: 패키지 이름(name)이 npm scope 규칙에 맞지 않음. @org/packagename 형식이어야 했다.

당당하게 지었던 패키지 이름이 발목을 잡았다.

해결 방법 고민:

1. GitHub 조직 새로 만들기 → 복잡하고 시간 소요
2. 사설 서버 설치 ex) Nexus, etc
3. 패키지 이름 변경 ✅ → 관련 파일의 import 구문 변경

결국 패키지 이름을 scope 규칙에 맞게 변경했다. 모든 import 문을 수정해야 했다.

GitHub Actions 무한 재귀의 공포

자동 배포 시스템도 거의 다 만들었다.

Changeset으로 버전 관리도 하고, GitHub Actions로 자동 배포도 설정했다.

"이제 진짜 끝이다!"

워크플로우 파일을 커밋하고 push했다.

10초 후

GitHub Actions 탭을 열어봤다.

✓ Deploy #1
⏳ Deploy #2
⏳ Deploy #3
⏳ Deploy #4
...

"...뭐지?"

배포가 계속 실행되고 있었다. 멈출 기미가 없었다.

20초 후

✓ Deploy #1
✓ Deploy #2
✓ Deploy #3
⏳ Deploy #4
⏳ Deploy #5
⏳ Deploy #6
⏳ Deploy #7
...

"미치겠다."

급하게 워크플로우를 수동으로 취소했다.

원인 파악

로그를 들여다봤다.

1. Actions가 develop 브랜치 push 이벤트에 반응
2. package.json 버전을 자동으로 수정
3. 수정된 파일을 자동 커밋
4. 새 커밋이 다시 push 이벤트 발생
5. 1번부터 다시 반복

무한 재귀였다.

"아... 자동 커밋이 다시 push 이벤트를 트리거하는구나."

해결:

워크플로우 트리거 조건에 추가:

• Auth가 github[bot]이면 바로 종료

다시 push했다.

이번엔 한 번만 실행됐다.

"...드디어."

드디어 성공한 배포 자동화 시스템!

무한 재귀를 막고 다시 push했다.

GitHub Actions 탭을 열었다. 이번엔 조심스럽게.

⏳ Deploy workflow running...

"제발..."

✓ Build success
✓ Type check passed
✓ Package published to npm

"...드디어."

3주 만이었다.

완성된 시스템:

✅ 버전 관리 자동화

• PR 머지 시 Changeset이 버전 업데이트

✅ 배포 파이프라인

• develop 브랜치 push 시 자동 npm 배포

✅ 문서 자동화

• CHANGELOG 자동 생성
• PR 링크 자동 추가

타팀에 메시지를 보냈다.

"배포 완료했습니다. npm install @org/design-system으로 설치 가능합니다."

기획자님의 답장: "오! 드디어! 고생하셨어요~"

"...하루 걸린다더니 3주 걸렸지만요."

그래도 작동한다. 완벽하진 않지만, 작동한다.

에필로그: 3주간의 타협이 가르쳐 준 것

"별거 아니에요"에서 "해냈습니다"까지

3주 전, 나는 말했다. "별거 아니에요. 하루면 될 것 같은데요?"

3주 후, 나는 완성했다. 완벽하지 않지만, 작동하는 배포 시스템을.

그 사이에 있었던 것:

• 3번의 타협
• 수십 번의 빌드 실패
• 20MB 괴물 패키지
• 무한 재귀 배포

그리고 하나의 깨달음.

타협한 것들 vs 그래도 성공한 것

완벽하지 않다. 하지만 작동한다.

이 시리즈에서 다룰 이야기들

3주간의 여정에서 부딪힌 문제들을 하나씩 깊게 파헤칠 예정입니다:

🔧 빌드 & 번들링

• tsup으로 라이브러리 번들링하기
• SVG 타입 문제 해결기
• 이중 빌드 시스템 구축

📦 패키지 & 배포

• pnpm pack으로 로컬 테스트
• package.json exports 가이드
• 번들 사이즈 최적화

🎨 스타일링 & CSS

• Panda CSS 빌드 결과물 배포
• @layer로 CSS 우선순위 제어
• 세 개의 CSS 시스템 공존시키기

🚀 자동화 & CI/CD

• Changeset + GitHub Actions
• npm 배포 자동화
• 무한 재귀 워크플로우 해결

어떤 주제가 먼저 나올지는... 제 기분 따라 정하겠습니다. (아니면 댓글로 요청해주세요!)

3주간의 타협이 가르쳐 준 것

타협 #1: 완벽한 타입 → 일단 작동하는 타입

• 현실: SVG 타입 생성 불가능
• 근거: 모노레포에서는 이미 타입 지원됨
• 결정: tsc로 타입만 별도 생성

타협 #2: 최적화된 번들 → 일단 작동하는 번들

• 현실: 빌드 최적화 시간 vs 배포 일정
• 근거: 초기 목표는 "작동하는 배포"
• 결정: 최적화는 나중에

타협 #3: 완벽한 호환 → 점진적 마이그레이션

• 현실: 다른 프레임워크 + CSS 라이브러리 + !important
• 근거: 운영 중인 서비스, 한번에 뒤엎기엔 위험
• 결정: 천천히 하나씩 수정

세 번의 타협 덕분에 배포는 완성될 수 있었습니다.

마지막으로

의사결정에서 중요한 건 '정답' 이 아니라 '왜 그렇게 결정했는가' 라는 근거입니다.

"별거 아니에요"라고 말했던 그날로부터 3주.

완벽하지는 않다. 20MB짜리 패키지, 누락된 타입, 수동으로 고쳐야 할 CSS들.

하지만 작동한다. 다른 팀이 사용할 수 있고, 자동으로 배포되고, 점진적으로 개선할 수 있다.

이 과정에서 배운 가장 중요한 것:

"별거 아닌 일은 없다. 하지만 완벽하지 않아도 배포할 수 있다."

누군가는 이 글을 보고 같은 삽질을 하지 않기를, 그리고 혹시 삽질 중이라면 "나만 이런 게 아니구나"라고 위로받기를 바랍니다.

보통은 이렇게 됩니다

• 어디를 수정해야 하는지 찾느라 1주
• 수정하다가 놓친 곳 때문에 버그 발생
• 회귀 테스트에 또 1주
• QA에서 엣지 케이스 발견
• 결국 한 달...

하지만 우리는 2주 만에, 사이드 이펙트 없이 끝냈습니다.

비결은 1년 전 작성한 이 한 줄이었습니다.

type ProfileId = string;

문제 상황

회원 구조가 바뀌었습니다.

[Before]
1 Account → 1 ProfileId (필수)

[After]
1 Account → N ProfileId (옵셔널)

예전에는 항상 ProfileId가 선택되어 있었지만, 이제는 선택하지 않을 수도 있게 되었습니다.

문제의 크기

거의 모든 서비스 기능이 영향을 받았습니다.

영향받은 주요 기능

• 콘텐츠 관리 (업로드, 수정, 삭제)
• 데이터 조회 (통계, 수익, 리포트)
• 권한 관리 (접근 제어, 팀 관리)

이런 코드가 곳곳에 있었습니다:

const profileId = getProfileId(); // 항상 string이라고 가정
api.fetchData(profileId);

기존엔 getProfileId()가 항상 string을 보장했습니다. 하지만 이제는 undefined일 수 있게 되었습니다. 옵셔널이 되어야 합니다.

552개 파일을 수정해야 하는 상황. 어떻게 안전하게 해낼 수 있을까요?

왜 가능했을까? #1: 도메인 분리의 시작점

처음 코드를 작성할 때, 이렇게 할 수도 있었습니다:

// ❌ 의미 없는 원시 타입
const id = cookies.get('ProfileId'); // any 타입
api.fetchData(id); // 타입 체크 없음

하지만 우리는 이렇게 했습니다:

// ✅ 도메인 개념을 표현하는 타입
type ProfileId = string;

const id = cookies.get<ProfileId>('ProfileId'); // ProfileId 타입
api.fetchData(id); // 타입 안전

무엇이 달라졌을까요?

string은 그냥 원시 타입입니다. "문자열" 이라는 것 외에 아무 의미가 없습니다.

하지만 ProfileId는 다릅니다:

• "이 값은 프로필을 식별하는 ID다"
• "이 값은 특정 도메인에 속한다"

코드에 의미 계층을 추가한 것입니다.

이 작은 차이가 대규모 변경을 가능하게 만들었습니다.

해결 전략

핵심은 타입 추상화에 있었습니다.

코드 곳곳에 ProfileId 타입이 명시되어 있었기 때문에, 반환 타입만 바꾸면 컴파일러가 수정이 필요한 모든 곳을 알려줄 수 있었습니다.

// 변경 전
const getProfileId = () => cookies.get<ProfileId>('ProfileId'); // ProfileId 반환

// 변경 후
const getProfileId = () => cookies.get<ProfileId | undefined>('ProfileId'); // ProfileId | undefined 반환

타입 하나만 바꿨을 뿐인데, 타입스크립트 컴파일러가 수정이 필요한 모든 곳을 찾아냈습니다.

왜 가능했을까? #2: 변경 추적 가능한 단위 생성

타입 별칭이 없었다면 어땠을까요?

// 만약 string을 직접 사용했다면
const getProfileId = () => cookies.get<string>('ProfileId');
const fetchData = (id: string) => api.fetch(id);
const userId: string = '123';
const profileId: string = '456';

이 코드의 문제는 의미가 없다는 것입니다.

string만 봐서는:

• 어떤 string이 ProfileId인지 알 수 없음
• 어떤 string이 UserId인지 알 수 없음
• 나중에 코드를 읽을 때 매번 변수명을 확인해야 함

하지만 ProfileId라는 타입을 만들면:

type ProfileId = string;

const getProfileId = (): ProfileId => cookies.get<ProfileId>('ProfileId');
const fetchData = (id: ProfileId) => api.fetch(id);
const profileId: ProfileId = '456';

무엇이 달라지나?

1. 코드 자체가 문서가 됩니다

// Before: 이게 뭔지 알 수 없음
function fetchData(id: string) {}

// After: ProfileId를 받는구나! 명확함
function fetchData(id: ProfileId) {}

2. 변경 추적이 가능해집니다

이제 getProfileId()의 반환 타입만 바꾸면:

// 이 한 줄만 수정
export const getProfileId = () =>
  cookies.get<ProfileId | undefined>('ProfileId');

TypeScript 컴파일러가 영향받는 모든 곳을 찾아냅니다:

❌ Type 'string | undefined' is not assignable to type 'string'
❌ Argument of type 'string | undefined' is not assignable to parameter
❌ Object is possibly 'undefined'

이 에러들이 수정이 필요한 모든 파일의 위치를 정확히 알려줬습니다.

이것이 "변경 추적 가능한 단위"를 만든 것입니다.

ProfileId 타입 덕분에:

1. 검색: 정확히 관련 코드만 찾음
2. 문서화: 코드 읽을 때 의미가 즉시 파악됨

타입 하나만 바꾸면, 그 변경이 자동으로 전체에 전파되고, 컴파일러가 수정이 필요한 모든 곳을 알려줍니다.

단순히 string이 아니라, ProfileId라는 의미를 부여한 것 - 이것이 안전하게 수정할 수 있었습니다.

수정 과정

우선순위별로 분류했습니다:

1. 기획 확인 필요 - ProfileId가 없는 상황을 고려하지 않은 케이스
2. 단순 null 체크 - 옵셔널 체이닝이나 조건문 추가
3. 로직 변경 - 흐름 자체를 수정해야 하는 케이스

패턴 1: 옵셔널 체이닝

// Before
const data = profileId.something;

// After
const data = profileId?.something;

패턴 2: 필수값 보장하기

path parameter처럼 '반드시 있어야 하는' 경우를 위한 훅을 만들었습니다:

const useProfileIdByPath = (): ProfileId => {
  const { profileId } = useParams<{ profileId: ProfileId }>();

  if (!profileId)
    throw new Error(
      'useProfileIdByPath hook must be used within an profileId path',
    );

  return profileId;
};

기획 논의는 이런 식이었습니다:

나: "컴파일 오류를 해결하다 보니 이 상황에서는 추가적인 화면 기획이 필요해요! 에러 화면이나 비어 있는 화면이 필요합니다."

기획: "아, 그 부분은 생각 못 했네요. 로그인 페이지로 보내주세요."

또는

나: "이 기능 자체에 대한 기획이 빠져 있는 거 같아요! 이 부분 추가로 필요합니다."

하나씩 수정하다 보니 총 552개 파일이 변경되었습니다.

결과

552개 파일. 2주. 사이드 이펙트 0건.

타입 시스템이 QA 역할까지 해주었습니다. 컴파일러가 알려주는 에러를 하나씩 해결하다 보니, 놓칠 수 있었던 엣지 케이스까지 모두 처리할 수 있었습니다.

심지어 기획에서 빠진 부분까지 발견했습니다.

추가 효과: 협업 속도 향상

타입 별칭의 효과는 여기서 끝나지 않습니다.

협업할 때도 차이가 납니다.

// ❌ 의미 없는 원시 타입
function updateProfile(id: string, name: string) {
  // id가 UserId인가? ProfileId인가? TeamId인가?
  // name이 displayName인가? userName인가?
}

// ✅ 의미 있는 타입
function updateProfile(id: ProfileId, name: DisplayName) {
  // 명확합니다
}

코드 자체가 문서 역할을 합니다. 주석이나 별도 문서 없이도 "이 함수는 ProfileId를 받는구나" 를 즉시 알 수 있습니다.

하지만 주의하세요

모든 string을 타입으로 만들 필요는 없습니다.

❌ 과도한 적용

type UserName = string;
type ButtonLabel = string;
type ErrorMessage = string;

✅ 의미 있는 적용

type UserId = string; // 식별자
type ProfileId = string; // 도메인 핵심 개념
type ApiKey = string; // 보안/검증 필요

도메인의 핵심 개념이나, 추적이 필요한 식별자처럼 꼭 필요해 보이는 곳에만 적용하세요.

배운 점

타입 설계의 중요성

string 대신 ProfileId를 썼던 과거의 선택이 모든 차이를 만들었습니다.

"나중에 필요할지도 몰라" 하는 막연한 기대가 아니라, 지금 당장 코드의 의미를 명확하게 만들기 위해 타입을 만들었던 것이 1년 후 대규모 변경을 가능하게 만들었습니다.

타입은 단순히 에러를 잡는 도구가 아닙니다. 코드에 의미를 부여하고, 변경을 추적 가능하게 만드는 설계 도구입니다.

당신의 프로젝트에도

지금 바로 확인해보세요.

체크리스트:

□ string, number 같은 원시 타입을 직접 사용하고 있나요?
□ UserId, ProductId, Price 같은 의미 있는 타입으로 바꿀 수 있나요?
□ 도메인 핵심 개념을 타입으로 표현하고 있나요?
□ 제네릭을 활용해서 타입 정보를 유지하고 있나요?

지금 당장 시작하세요:

1. 가장 중요한 식별자 하나를 골라보세요 (userId, orderId, productId...)
2. type UserId = string 한 줄을 추가하세요
3. 해당 타입을 사용하는 모든 곳에 타입을 명시하세요
4. 다음에 변경이 필요할 때, 그 위력을 경험하게 될 것입니다

3개월 후 이 글을 다시 읽는 당신에게

"그때 ProfileId 타입을 만들어둬서 다행이야."

이 문장을 하게 될 순간이 반드시 옵니다.

• API 응답 구조가 바뀔 때
• 권한 시스템을 추가할 때

타입 한 줄은 미래의 당신에게 보내는 선물입니다.

throw를 보던중 문득 깨달았다.

try {
  throw new Error('error');
} catch (error) {
  throw error; // 상위로 전파된다
}

에러는 계층을 따라 전파된다. 그럼 에러 클래스도 계층 구조로 설계할 수 있지 않을까?

깊게: Error → ApiError → HttpError → NotFoundError → StatsNotFoundError
넓게: Error → ApiError → StatsError, ChartError, ActivityError

ErrorBoundary에서 instanceof로 잡으려면 되지 않을까?

1. 에러를 어떻게 설계 할 것인가?

1.1. 문제: 모든 에러가 똑같이 보인다

// 세 개의 API - 각각 다른 섹션 데이터
const getDashboardStats = async () => {
  /* ... */
};
const getChartData = async () => {
  /* ... */
};
const getActivities = async () => {
  /* ... */
};

에러가 발생하면?

componentDidCatch(error: Error) {
  // 😰 이게 통계 에러야? 차트 에러야? 활동 에러야?
  // instanceof Error 하면 전부 true - 구분 불가능
}

문제점: ErrorBoundary에서 섹션별 처리 불가, 디버깅 어려움

1.2. 왜 클래스 설계인가?

프롤로그에서 본 계층 구조를 실제로 구현하려면 클래스 상속이 필요하다.

Error (JavaScript 내장)
  ↓
ApiError (Base)
  ↓
├─ StatsError
├─ ChartError
└─ ActivityError

상속 구조의 장점

1. instanceof로 타입 체크

   if (error instanceof StatsError) {
     // StatsError만 처리
   }
   

2. 계층적 ErrorBoundary 설계

   StatsErrorBoundary: StatsError만 캐치
   GlobalErrorBoundary: ApiError 전체 캐치
   

3. 공통 속성 관리

   ApiError에 statusCode, code 정의
   하위 클래스들이 자동으로 상속
   

클래스 상속이 있어야 얕고 넓은 구조를 만들 수 있다.

const getDashboardStats = async () => {
  try {
    const response = await instance.get('/api/dashboard/stats');
    return response.data;
  } catch (error: unknown) {
    if (isHttpError(error)) {
      throw new StatsError(
        error.response?.data?.message ||
          '통계 데이터를 불러오는데 실패했습니다',
        error.response?.data?.error,
      );
    }
    throw error;
  }
};

개선점: instanceof StatsError로 타입 구분 가능, ErrorBoundary 선택적 처리

핵심: try-catch로 Error을 잡아서, 커스텀 에러 클래스로 변환해서 throw

1.3. throw vs return?

에러를 변환하기로 했다. 그런데 질문이 하나 생긴다.

"변환한 에러를 throw 해야 할까, return 해야 할까?"

나는 throw를 선호한다.
코드 리뷰를 하다 보면, return error 방식에서 자잘한 버그를 너무 자주 봤다.
에러를 return 값으로 넘겼는데 중간에 체크를 빠뜨리거나, 조건문 분기가 복잡해지는 경우가 많았다.

throw는 명료하다. 에러가 발생하면 자동으로 전파되고, 중간 계층은 신경 쓸 필요가 없다.

두 가지 선택지

방식 1: throw

const getDashboardStats = async () => {
  try {
    const response = await instance.get('/api/dashboard/stats');
    return response.data;
  } catch (error) {
    throw new StatsError(/*...*/); // 👈 throw
  }
};

방식 2: return error

const getDashboardStats = async () => {
  try {
    const response = await instance.get('/api/dashboard/stats');
    return { data: response.data, error: null };
  } catch (error) {
    return { data: null, error: new StatsError(/*...*/) }; // 👈 return
  }
};

두 방식 모두 가능하다. 선언적으로 Error을 핸들링하기 위해선 throw가 더 적합하다. 왜 그럴까?

1. 흐름 제어가 간단하다

return error 방식의 문제:

const useStats = async () => {
  const result = await getDashboardStats();
  if (result.error) return result; // 매번 체크

  const processed = processData(result.data);
  if (processed.error) return processed; // 또 체크

  return processed;
};

함수 체인의 모든 단계에서 에러를 체크해야 한다. 코드가 길어지고, 실수하기 쉽다.

throw 방식의 장점:

const useStats = async () => {
  const result = await getDashboardStats(); // 에러나면 자동으로 throw
  return processData(result); // 깔끔!
};

에러가 발생하면 자동으로 상위로 전파된다. 일일이 if (error) 체크할 필요 없다.

2. 계층 간 유연한 통합

React 애플리케이션의 계층 구조를 보자:

Component (ErrorDesignPage)
    ↓
Hook (useDashboardStats)
    ↓
API (getDashboardStats)
    ↓
SectionErrorBoundary
    ↓
ErrorBoundary

throw를 사용하면:

• Component는 에러를 몰라도 된다 (선언적으로 사용)
• Hook도 에러 처리 코드가 필요 없다
• API 레이어에서만 에러를 변환
• ErrorBoundary가 자동으로 캐치

핵심: 중간 계층들이 에러를 props나 return으로 전달할 필요 없이, throw만 하면 ErrorBoundary까지 자동으로 전파된다.

3. React ErrorBoundary와의 시너지

React Query + Suspense + ErrorBoundary 조합을 보자:

// API → Hook → Component → ErrorBoundary 자동 전파
export const useDashboardStats = () =>
  useSuspenseQuery({ queryFn: getDashboardStats });

<StatsErrorBoundary>
  <Suspense fallback={<Loading />}>
    <StatsSection />
  </Suspense>
</StatsErrorBoundary>;

2. 계층 구조 설계하기

커스텀 에러 클래스를 만들기로 했다. 그럼 어떻게 설계해야 할까?

2.1. Base 클래스: 왜 ApiError인가?

먼저 base 클래스가 필요하다.

export class ApiError extends Error {
  code?: string;
  status?: number;

  constructor(
    message: string,
    opts?: { code?: string; status?: number; cause?: unknown },
  ) {
    super(message, { cause: opts?.cause });
    this.name = new.target.name; // 정확한 클래스명
    this.code = opts?.code;
    this.status = opts?.status;
    if (Error.captureStackTrace) Error.captureStackTrace(this, new.target);
  }
}

왜 Error를 직접 상속하지 않고 ApiError를 만들었을까?

JavaScript의 기본 Error 클래스는 message만 있다. 하지만 API 에러는 더 많은 정보가 필요하다:

• statusCode: HTTP 상태 코드 (500, 404, 401 등)
• code: 비즈니스 에러 코드 ('STATS_ERROR', 'AUTH_ERROR' 등)

이 정보들이 있어야:

• 에러별로 다른 처리를 할 수 있고
• 디버깅할 때 원인을 빠르게 파악할 수 있다

2.2 상속 구조와 ErrorBoundary 전략

이제 핵심이다. 앞서 그렸던 계층을 책임 관점으로 정리하면 다음과 같다.

이 구조 덕분에 ErrorBoundary를 설계할 수 있다:

패턴 1: 전역 ErrorBoundary (모든 API 에러 캐치)

if (error instanceof ApiError) {
  // 모든 API 에러를 여기서 처리
  // 공통 로깅, 공통 fallback UI
}

패턴 2: 섹션별 ErrorBoundary (특정 에러만 캐치)

// StatsErrorBoundary
if (error instanceof StatsError) {
  // 통계 섹션만 fallback
  // 다른 섹션은 정상 동작
} else {
  throw error; // 다른 에러는 상위로 전파
}

패턴 3: 계층적 ErrorBoundary

AppErrorBoundary (Error 캐치)
  └─ GlobalErrorBoundary (ApiError 캐치, 선택)
        └─ StatsErrorBoundary (StatsError만 캐치)
             └─ Component

핵심: 상속 구조 = ErrorBoundary 전략. instanceof로 에러 레벨 구분, 특정 에러만 잡고 나머지는 상위로 전파. 통계 섹션이 터져도 다른 섹션은 정상 동작한다.

3. 도메인별 에러 클래스 구현

설계는 끝났다. 이제 구현해보자.

3.1. 간단한 구현

ApiError를 상속받기만 하면 된다.

// 통계 데이터 에러
export class StatsError extends ApiError {
  constructor(message: string, code?: string) {
    super(message, { code, status: 500 });
    this.name = 'StatsError';
  }
}

// 차트 데이터 에러
export class ChartError extends ApiError {
  constructor(message: string, code?: string) {
    super(message, { code, status: 500 });
    this.name = 'ChartError';
  }
}

// 활동 데이터 에러
export class ActivityError extends ApiError {
  constructor(message: string, code?: string) {
    super(message, { code, status: 500 });
    this.name = 'ActivityError';
  }
}

포인트:

• ApiError 상속으로 계층 구조 구축
• super(message, { code, status }) 형태로 옵션 객체 전달
• name 속성으로 에러 타입 구분

3.2. 실제 사용

앞서 본 getDashboardStats 예제에서 catch 블록이 담당하는 역할만 발췌하면 다음과 같다.

catch (error: unknown) {
  if (isHttpError(error)) { // ⭐ HTTP 에러만 StatsError로 변환
    throw new StatsError(
      error.response?.data?.message ||
        '통계 데이터를 불러오는데 실패했습니다',
      error.response?.data?.error,
    );
  }
  throw error; // 예상치 못한 에러는 그대로 던짐
}

흐름: HTTP 에러 발생 → isHttpError 타입 체크 → 커스텀 에러로 변환 → throw

이제 ErrorBoundary에서 instanceof StatsError로 정확히 구분 가능

전체 코드

전체 구현은 GitHub에서 확인할 수 있다:

• 에러 클래스 정의
• API 레이어 적용
• Core 패키지 ApiError

4. ErrorBoundary와 연결하기

에러 클래스를 만들었다. 이제 ErrorBoundary와 연결해보자.

4.1. SectionErrorBoundary: 선택적 에러 캐치

핵심 아이디어는 특정 에러만 캐치하고, 나머지는 상위로 전파 하는 것이다.

type ErrorCtor<T extends Error = Error> = new (...args: any[]) => T;

interface Props<T extends Error = Error> {
  children: ReactNode;
  sectionName: string;
  errorType: ErrorCtor<T>; // 제네릭 생성자 시그니처
}

export class SectionErrorBoundary<T extends Error = Error> extends Component<
  Props<T>,
  State
> {
  state: State = { error: null };

  static getDerivedStateFromError(error: Error): Partial<State> {
    return { error }; // 에러 저장만
  }

  componentDidCatch(error: Error, _info: ErrorInfo) {
    console.error(`[${this.props.sectionName}]`, error, _info); // 로깅만
  }

  private isHandled(error: Error | null): error is T {
    if (!error) return false;
    return error instanceof this.props.errorType;
  }

  render() {
    const { error } = this.state;

    if (error) {
      if (this.isHandled(error)) {
        return <ErrorFallbackUI />; // 담당 에러: 처리
      }
      // 👇 반드시 render에서 재-throw 해야 상위 Boundary로 전파
      throw error; // 담당 아님: 상위로 전파
    }

    return this.props.children;
  }
}

핵심 로직

if (error) {
  if (this.isHandled(error)) {
    return <ErrorFallbackUI />; // 담당 에러만 처리
  }
  throw error; // 다른 에러는 상위로!
}

• StatsErrorBoundary는 StatsError만 캐치
• ChartError가 발생하면? → throw로 상위로 전파
• 담당하지 않는 에러는 관여하지 않는다
• 중요: render에서 throw해야 상위로 전파됨 (componentDidCatch에서는 안됨)

4.2. 에러 전파 전략: 상속 구조 따라가기

⚠️ 중요: 에러 전파는 render()에서만 일어난다

componentDidCatch에서 throw error를 해도 부모 ErrorBoundary로 전파되지 않습니다. 에러를 상위로 전파하려면 반드시 render() 메서드에서 throw 해야 합니다.

왜 다시 throw 하는가?

에러 상속 구조를 따라가기 위해서다

GlobalErrorBoundary (ApiError 캐치)
  └─ StatsErrorBoundary (StatsError만 캐치)
       └─ Component

시나리오 1: StatsError 발생

// Component에서 StatsError 발생
throw new StatsError('통계 실패');

// StatsErrorBoundary에서
if (!(error instanceof StatsError)) {
  // false
  throw error;
}
// 👉 여기서 캐치! fallback UI 표시

시나리오 2: ChartError 발생

// Component에서 ChartError 발생
throw new ChartError('차트 실패');

// StatsErrorBoundary에서
if (!(error instanceof StatsError)) {
  // true!
  throw error; // 👈 상위로 전파
}

// GlobalErrorBoundary에서
if (error instanceof ApiError) {
  // true (ChartError는 ApiError 상속)
  // 👉 여기서 캐치!
}

시나리오 3: 일반 Error 발생 (테스트용)

export const getActivities = async (): Promise<Activity[]> => {
  try {
    // 임시 에러 계층 테스트용 코드 - 이걸 풀면 더 상위 에러 바운더리로 전파됨
    throw new Error('test');

    const response = await instance.get('/api/dashboard/activities');
    return response.data;
  } catch (error: unknown) {
    if (isHttpError(error)) {
      throw new ActivityError(/*...*/);
    }
    throw error; // 👈 일반 Error는 그대로 throw
  }
};

// ActivityErrorBoundary에서
if (!(error instanceof ActivityError)) {
  // true! (일반 Error는 ActivityError가 아님)
  throw error; // 👈 상위로 전파
}

// GlobalErrorBoundary에서
if (error instanceof ApiError) {
  // false (일반 Error는 ApiError가 아님)
  throw error; // 👈 더 상위로 전파
}

// 최상위 ErrorBoundary에서
if (error instanceof Error) {
  // true
  // 👉 여기서 최종 캐치!
}

이렇게 예상치 못한 에러도 계층을 따라 올라가면서 적절한 곳에서 처리된다.

핵심:

• 담당 에러만 처리
• 나머지는 상속 구조를 따라 상위로
• 계층적 에러 처리 가능
• 예상치 못한 에러는 최상위 ErrorBoundary까지 전파

4.3. 실제 사용

각 섹션별 ErrorBoundary wrapper를 만든다:

export const StatsErrorBoundary = ({ children }: { children: ReactNode }) => (
  <SectionErrorBoundary sectionName="통계" errorType={StatsError}>
    {children}
  </SectionErrorBoundary>
);

// ChartErrorBoundary, ActivityErrorBoundary도 동일한 패턴

컴포넌트에서 사용:

<StatsErrorBoundary>
  <Suspense fallback={<Loading />}>
    <StatsSection />
  </Suspense>
</StatsErrorBoundary>

각 섹션이 독립적으로 에러를 처리한다. 한 섹션이 터져도 전체 앱이 죽지 않는다.

전체 코드

전체 구현은 GitHub에서 확인할 수 있다:

• SectionErrorBoundary 구현
• 실제 사용 예시

5. 실전 활용

이제 모든 조각을 조합해보자. React Query + Suspense + ErrorBoundary로 완성된 에러 처리 시스템을 만들어본다.

5.1. 계층별 역할 분리

전체 흐름을 보자:

// 1. API 레이어: 앞서 정의한 getDashboardStats가 StatsError를 throw

// 2. Hook 레이어: React Query
export const useDashboardStats = () =>
  useSuspenseQuery({
    queryKey: ['dashboardStats'],
    queryFn: getDashboardStats, // StatsError를 throw
  });

// 3. Component 레이어: 선언적 사용
const StatsSection = () => {
  const { data: stats } = useDashboardStats();
  return <StatCard title="총 방문자" value={stats.visitors.total} />;
};

// 4. Suspense + ErrorBoundary
<StatsErrorBoundary>
  <Suspense fallback={<Loading />}>
    <StatsSection />
  </Suspense>
</StatsErrorBoundary>;

각 계층의 역할:

• API: 에러 변환 (generic Error → StatsError)
• Hook: 데이터 페칭
• Component: 데이터 렌더링 (에러 처리 코드 없음!)
• Boundary: 에러/로딩 처리 (선언적)

우리가 StatsError로 변환했기 때문에:

1. getDashboardStats에서 StatsError throw
2. React Query가 받아서 다시 throw
3. ErrorBoundary가 캐치
4. instanceof StatsError로 정확히 구분! ✅

5.2. 독립적인 섹션 에러 처리

대시보드 전체 구조:

const ErrorDesignPage = () => (
  <Grid>
    {/* 헤더 */}
    <Header />

    {/* 통계 섹션 - 독립적 */}
    <StatsErrorBoundary>
      <Suspense fallback={<LoadingCard />}>
        <StatsSection />
      </Suspense>
    </StatsErrorBoundary>

    {/* 차트 섹션 - 독립적 */}
    <ChartErrorBoundary>
      <Suspense fallback={<LoadingChart />}>
        <ChartWidget />
      </Suspense>
    </ChartErrorBoundary>

    {/* 활동 섹션 - 독립적 */}
    <ActivityErrorBoundary>
      <Suspense fallback={<LoadingFeed />}>
        <ActivityFeed />
      </Suspense>
    </ActivityErrorBoundary>
  </Grid>
);

결과: 한 섹션이 실패해도 다른 섹션은 정상 동작. 완전히 독립적인 에러 처리.

5.3. 이것이 가능한 이유

앞서 정리한 책임 표 그대로 흐름이 흘러가기 때문이다.

• StatsError · ChartError · ActivityError는 각 섹션 Boundary에서 복구 UI를 보여 준다.
• ApiError는 전역 Boundary가 공통 로깅과 가드 처리를 맡는다.
• 예상 밖 Error는 최상위 Boundary까지 전파되어 전체 보호막이 된다.

설계 단계에서 경계가 명확해졌기에 런타임에서도 자연스럽게 분리된다.

전체 코드

전체 구현은 GitHub에서 확인할 수 있다.

• 대시보드 페이지
• React Query 훅
• 테스트 코드

6. 결론

계층 구조의 핵심 가치

에러 클래스 계층 구조가 가져다준 것들

1. 타입 안전성과 ErrorBoundary 전략

• instanceof로 런타임 타입 체크
• 에러 상속 구조 = ErrorBoundary 계층 구조
• 선택적 캐치와 전파로 유연한 에러 격리

2. 독립적 에러 처리와 디버깅

• 섹션별 독립적 처리: 통계 섹션이 터져도 차트는 정상
• 로그만 봐도 어느 도메인 에러인지 즉시 파악
• 사용자 경험과 개발자 경험 모두 향상

확장 가능한 설계

새로운 섹션 추가는 간단하다.

// 1. 에러 클래스 추가
export class NotificationError extends ApiError {
  constructor(message: string, code?: string) {
    super(message, { code, status: 500 });
    this.name = 'NotificationError';
  }
}

// 2. ErrorBoundary 추가
export const NotificationErrorBoundary = ({ children }) => (
  <SectionErrorBoundary sectionName="알림" errorType={NotificationError}>
    {children}
  </SectionErrorBoundary>
);

// 3. 사용
<NotificationErrorBoundary>
  <Suspense fallback={<Loading />}>
    <NotificationSection />
  </Suspense>
</NotificationErrorBoundary>;

일관된 패턴으로 확장 가능하다.

정리하면

프롤로그의 질문으로 돌아가보자. "에러는 계층을 따라 전파된다. 그렇다면 에러 클래스도 계층 구조로 설계할 수 있지 않을까?"

그 답은 명확하다. 에러의 구조화가 곧 처리 전략이다.

• Error → 최상위 ErrorBoundary
• ApiError → 전역 GlobalErrorBoundary
• StatsError → 섹션별 StatsErrorBoundary

각 에러는 자신이 어디까지 올라가야 하는지 알고, 각 Boundary는 자신의 책임을 안다. HTTP 에러는 도메인 에러로 변환되고, 도메인 에러는 섹션 Boundary가 받아 처리한다. 예외가 예상 범위를 벗어나면 더 높은 Boundary로 전파된다.

이 구조 덕분에 “이 에러는 누가 처리해야 하지?”라는 고민은 사라진다. 타입이 곧 처리 위치이기 때문이다. 한 섹션이 실패해도, 다른 섹션은 영향 없이 정상적으로 동작한다.

이 글을 읽고 나면

• AI와 협업해서 오픈소스 기여하는 방법을 알게 됩니다
• 성능 최적화 PR이 더 좋은 평가를 받는 이유를 이해합니다
• 구글같은 대기업 프로젝트에 기여하는 전략을 배웁니다
• 실제 머지된 PR 사례를 통해 구체적인 노하우를 얻습니다

들어가며

"내 코드를 구글의 프로젝트에 넣을 수 있다니!"

2025년 6월 25일 gemini-cli가 출시되었습니다. CLI 환경의 AI 도구들이 쏟아져 나오는 요즘, 이 프로젝트가 특별했던 이유는:

• JavaScript 기반: 익숙한 기술 스택
• 화제성: 출시 직후부터 관심 집중
• 작은 코드베이스: 아직 분석 가능한 규모
• 개선 여지: 급하게 만들어진 티가 여기저기 보임
• 적극적인 오픈소스: 전세계 개발자들의 참여를 적극 유도

무엇보다 구글러들에게 직접 코드리뷰를 받을 수 있다는 점이 가장 매력적이었습니다.

기여할 것을 찾아보자

설레는 마음으로 코드베이스를 뜯어보기 시작했습니다.
ai와 함께 코드베이스를 분석하고 기여할 점을 부탁 하였습니다.

ex) 사용했던 프롬프트
User

여기는 gemini-cli 프로젝트예요. 함께 개선할 점을 찾아봐요!

AI Assistant

read-many-files.ts에서 파일 처리가 동기적으로 이뤄지고 있어요. 개선 방향은 아래와 같아요:

• for...of 순회를 Promise 목록 기반 병렬 처리로 전환
• detectFileType 함수를 비동기로 변경

User

개선할 코드 제안해주고 이게 어떤 이점을 가져오는지 설명해줘

AI Assistant

(변경 코드 보여주고 설명 하는 중)

이 내용을 보았을 성능관련 기여를 할 수 있다고 생각을 했고 메인테이너의 입장에서는
새로운 기능을 추가하는 PR은 메인테이너 입장에서 고려할 게 많습니다.
프로젝트의 방향성과 맞는지, 다른 기능과 충돌은 없는지, 앞으로 유지보수 비용은 어떨지 등등... 하지만 성능 개선 PR은 빚을 갚아주는 것과 같습니다.
누구도 마다할 이유가 없죠. 프로젝트를 더 건강하게 만드는, 가장 환영받는 기여 중 하나입니다.
하지만 너무 바꿀 범위가 많다고 생각을 했습니다. 그래서 pr을 2개 쪼개어 날리기로 했습니다.
두 번이나 pr을 날릴수도 있고 계획적으로 나만의 로드맵을 그려갈 수 있다고 생각을 했습니다.

1. fileUtils.ts -> 개선
2. read-many-files.ts -> 병렬처리로 전환

기여 시작

1차 기여: fileUtils.ts 비동기 전환

저 파일안에 있는 detectFileType 만 비동기로 만들어도 되었지만 ai는 나에게 좀 더 몇 가지 개선점을 알려주었습니다.

// AS-IS
export function isBinaryFile(filePath: string): boolean {
  try {
    const fd = fs.openSync(filePath, 'r');
    // Read up to 4KB or file size, whichever is smaller
    const fileSize = fs.fstatSync(fd).size;
    if (fileSize === 0) {
      // Empty file is not considered binary for content checking
      fs.closeSync(fd);
      return false;
    }
    const bufferSize = Math.min(4096, fileSize);
    const buffer = Buffer.alloc(bufferSize);
    const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, 0);
    fs.closeSync(fd);

    if (bytesRead === 0) return false;

    let nonPrintableCount = 0;
    for (let i = 0; i < bytesRead; i++) {
      if (buffer[i] === 0) return true; // Null byte is a strong indicator
      if (buffer[i] < 9 || (buffer[i] > 13 && buffer[i] < 32)) {
        nonPrintableCount++;
      }
    }
    // If >30% non-printable characters, consider it binary
    return nonPrintableCount / bytesRead > 0.3;
  } catch {
    // If any error occurs (e.g. file not found, permissions),
    // treat as not binary here; let higher-level functions handle existence/access errors.
    return false;
  }
}

// TO-BE
export async function isBinaryFile(filePath: string): Promise<boolean> {
  let fileHandle: fs.promises.FileHandle | undefined;
  try {
    fileHandle = await fs.promises.open(filePath, 'r');

    // Read up to 4KB or file size, whichever is smaller
    const stats = await fileHandle.stat();
    const fileSize = stats.size;
    if (fileSize === 0) {
      // Empty file is not considered binary for content checking
      return false;
    }
    const bufferSize = Math.min(4096, fileSize);
    const buffer = Buffer.alloc(bufferSize);
    const result = await fileHandle.read(buffer, 0, buffer.length, 0);
    const bytesRead = result.bytesRead;

    if (bytesRead === 0) return false;

    let nonPrintableCount = 0;
    for (let i = 0; i < bytesRead; i++) {
      if (buffer[i] === 0) return true; // Null byte is a strong indicator
      if (buffer[i] < 9 || (buffer[i] > 13 && buffer[i] < 32)) {
        nonPrintableCount++;
      }
    }
    // If >30% non-printable characters, consider it binary
    return nonPrintableCount / bytesRead > 0.3;
  } catch (error) {
    // Log error for debugging while maintaining existing behavior
    console.warn(
      `Failed to check if file is binary: ${filePath}`,
      error instanceof Error ? error.message : String(error),
    );
    // If any error occurs (e.g. file not found, permissions),
    // treat as not binary here; let higher-level functions handle existence/access errors.
    return false;
  } finally {
    // Safely close the file handle if it was successfully opened
    if (fileHandle) {
      try {
        await fileHandle.close();
      } catch (closeError) {
        // Log close errors for debugging while continuing with cleanup
        console.warn(
          `Failed to close file handle for: ${filePath}`,
          closeError instanceof Error ? closeError.message : String(closeError),
        );
        // The important thing is that we attempted to clean up
      }
    }
  }
}

fs.promises 를 붙인 것만으로도 아래와 개선 효과를 볼 수 있다는 걸 ai와 함께 정리 했습니다.

주요 차이점

1. 동기 vs 비동기 처리

• AS-IS: 동기 함수 (function)
• TO-BE: 비동기 함수 (async function)

2. 파일 시스템 API

• AS-IS: 동기 메서드들
  • fs.openSync(), fs.fstatSync(), fs.readSync(), fs.closeSync()
• TO-BE: 비동기 Promise 기반 메서드들
  • fs.promises.open(), fileHandle.stat(), fileHandle.read(), fileHandle.close()

3. 에러 처리

• AS-IS: 간단한 catch 블록
• TO-BE: 상세한 에러 로깅 + finally 블록으로 리소스 정리

4. 리소스 관리

• AS-IS: 명시적 fs.closeSync(fd) 호출
• TO-BE: finally 블록에서 안전한 파일 핸들 정리

장단점 비교

AS-IS 장점

✅ 간단함: 코드가 직관적이고 이해하기 쉬움
✅ 동기 처리: 순차적 실행으로 디버깅이 용이
✅ 가벼움: 추가 Promise 오버헤드 없음

AS-IS 단점

❌ 블로킹: 파일 읽기 중 다른 작업 불가
❌ 에러 정보 부족: 디버깅 시 구체적 오류 정보 없음
❌ 리소스 누수 위험: 예외 발생 시 파일 디스크립터 정리 불완전

TO-BE 장점

✅ 논블로킹: 다른 작업과 병렬 처리 가능
✅ 상세한 에러 처리: console.warn으로 디버깅 정보 제공
✅ 안전한 리소스 관리: finally 블록으로 확실한 정리
✅ 확장성: 비동기 생태계와 잘 맞음

TO-BE 단점

❌ 복잡성: 코드가 길어지고 이해하기 어려움
❌ Promise 오버헤드: 작은 성능 비용 발생
❌ 호출부 변경 필요: await 키워드 추가 필요

권장사항

대량 파일 처리나 웹 서버 환경에서는 TO-BE 방식을, 간단한 CLI 도구나 소규모 스크립트에서는 AS-IS 방식이 적합합니다.

fs.promises API 설명

기본 개념

fs.promises 는 Node.js의 파일 시스템 모듈에서 Promise 기반의 비동기 API를 제공하는 네임스페이스입니다.

주요 차이점

fs.openSync() - 동기 방식

const fd = fs.openSync('/path/file', 'r');
// ✅ 즉시 파일 디스크립터 반환
// ❌ 파일이 열릴 때까지 코드 실행 중단 (블로킹)
// ❌ 이벤트 루프 차단

fs.promises.open() - Promise 방식

const fileHandle = await fs.promises.open('/path/file', 'r');
// ✅ Promise 반환으로 논블로킹
// ✅ 다른 작업과 병렬 처리 가능
// ✅ FileHandle 객체 반환 (더 안전한 API)

fs.promises API의 핵심 특징

1. FileHandle 객체

// 기존: 단순 숫자 파일 디스크립터
const fd = fs.openSync('file.txt', 'r'); // 3 (숫자)

// fs.promises: FileHandle 객체
const fileHandle = await fs.promises.open('file.txt', 'r');
// { fd: 3, read: Function, write: Function, close: Function, ... }

2. 자동 리소스 관리

// 위험한 패턴 (동기)
const fd = fs.openSync('file.txt', 'r');
// 에러 발생 시 close 안됨
const data = fs.readSync(fd, buffer, 0, buffer.length, 0);
fs.closeSync(fd);

// 안전한 패턴 (Promise + try/finally)
let fileHandle;
try {
  fileHandle = await fs.promises.open('file.txt', 'r');
  const data = await fileHandle.read(buffer, 0, buffer.length, 0);
} finally {
  await fileHandle?.close(); // 항상 정리됨
}

3. 병렬 처리 지원

// 동기: 순차 처리만 가능
const file1 = fs.readFileSync('file1.txt');
const file2 = fs.readFileSync('file2.txt');
const file3 = fs.readFileSync('file3.txt');

// Promise: 병렬 처리 가능
const [file1, file2, file3] = await Promise.all([
  fs.promises.readFile('file1.txt'),
  fs.promises.readFile('file2.txt'),
  fs.promises.readFile('file3.txt'),
]);

언제 사용해야 할까?

fs.promises 사용 권장

• 웹 서버, API 서버
• 대량 파일 처리
• 사용자 상호작용이 있는 앱
• 다른 비동기 작업과 함께 사용

fs.openSync 사용 권장

• 빌드 스크립트, CLI 도구
• 간단한 일회성 작업
• 성능보다 단순함이 중요한 경우

이런 내용을 기반으로 공부도 되었고 다음 작업을 위해서 1차 이슈와 PR을 작성했습니다.

실제 이슈 & PR 작성법 공개

구글러들을 설득한 실제 문서를 보여드리겠습니다:

이슈 #3286

# Convert synchronous file binary detection to async to eliminate event loop blocking

## 🚨 Problem

Current file binary detection uses synchronous file operations that:

- Block Node.js event loop causing UI freezing
- Prevent concurrent file processing
- Create poor scalability for large projects

## 📊 Expected Benefits

- 20-80% performance improvement depending on project size
- Improved UI responsiveness
- Enables concurrent file processing foundation

## 🎯 Technical Solution

- Convert `isBinaryFile()` and `detectFileType()` to async
- Use `fs.promises` API for non-blocking operations
- Update all callers to use `await`

PR #3288

# feat: Make file type detection and binary checks asynchronous (#3286)

## 🔧 Changes Made

- Converted sync file operations to async implementations
- Used `fs.promises` for non-blocking file I/O
- Enhanced resource management with proper cleanup
- Updated test cases for async compatibility

## 💡 Why This Matters

"The original sync file operations were blocking the Node.js event loop,
causing UI freezes and poor performance when processing multiple files."

## 🎯 Next Steps

This lays the foundation for parallel file processing (coming in next PR)

리뷰어 반응:

• Gemini Code Assist: "clean and thorough implementation"
• NTaylorMullen: "Thanked for the contribution" ✅ 승인

첫 PR이 성공적으로 머지되었을 때의 기쁨은 정말 컸습니다.
이슈 등록부터 시작해 제 코드로 직접 성능 개선에 기여했다는 성취감, 그리고 다음 기여를 위한 발판까지 마련했다는 생각에 뿌듯했습니다.

2차 기여: 병렬 처리로 성능 개선

1차 PR 머지 후, 바로 2차 이슈와 PR을 진행했습니다.

📈 2차 작업: 74% 성능 개선

🎯 이슈 #4712

# Implement batch/parallel file processing for performance optimization

## 🚀 Goal

Improve file processing performance for large projects by implementing parallel processing

## 📊 Expected Impact

- 20-80% performance improvement
- Better UX for large projects
- Leverage async foundation from previous PR #3288

💥 PR #4763

# perf(core): implement parallel file processing for 74% performance improvement

## 🔥 Performance Results

- **Before**: 408ms (sequential processing)
- **After**: 107ms (parallel processing)
- **Improvement**: 74% faster! 🚀

## 🛠️ Technical Implementation

- Replaced sequential for-loop with Promise.allSettled()
- Maintained error isolation for individual files
- Added comprehensive performance test coverage

리뷰어들의 극찬:

• jacob314: "Praised the performance optimization and test coverage" ✅ 승인
• SandyTao520: 머지 완료

이과정에서 약간의 코드리뷰가 있었는대

리뷰어는 ! non-null assertion이 잠재적 버그를 가릴 수 있다고 지적했습니다.
파일 처리 중 실패하는 엣지 케이스에서 에러를 던지는 대신 undefined를 반환하며 조용히 넘어가버릴 수 있기 때문입니다.
그의 지적에 따라, 성공과 실패 케이스를 명확히 구분하는 Result 타입을 도입하여 코드의 안정성을 한층 높일 수 있었습니다.
작은 기호 하나에도 깊은 뜻이 있다는 것을 배운 순간이었습니다.
그래서 이렇게 타입을 만들어 성공과 실패 케이스를 나누어서 처리를 하였습니다.

/**
 * Result type for file processing operations
 */
type FileProcessingResult =
  | {
      success: true;
      filePath: string;
      relativePathForDisplay: string;
      fileReadResult: NonNullable<
        Awaited<ReturnType<typeof processSingleFileContent>>
      >;
      reason?: undefined;
    }
  | {
      success: false;
      filePath: string;
      relativePathForDisplay: string;
      fileReadResult?: undefined;
      reason: string;
    };

그리고 성능이 중요하다고 생각 하여 병렬 처리에대한 속도 처리 테스트를 만들어 넣었습니다.

it('should process files in parallel for performance', async () => {
  // Mock detectFileType to add artificial delay to simulate I/O
  const detectFileTypeSpy = vi.spyOn(
    await import('../utils/fileUtils.js'),
    'detectFileType',
  );

  // Create files
  const fileCount = 4;
  const files = createMultipleFiles(fileCount, 'Batch test');

  // Mock with 100ms delay per file to simulate I/O operations
  detectFileTypeSpy.mockImplementation(async (_filePath: string) => {
    await new Promise(resolve => setTimeout(resolve, 100));
    return 'text';
  });

  const startTime = Date.now();
  const params = { paths: files };
  const result = await tool.execute(params, new AbortController().signal);
  const endTime = Date.now();

  const processingTime = endTime - startTime;

  console.log(`Processing time: ${processingTime}ms for ${fileCount} files`);

  // Verify parallel processing performance improvement
  // Parallel processing should complete in ~100ms (single file time)
  // Sequential would take ~400ms (4 files × 100ms each)
  expect(processingTime).toBeLessThan(200); // Should PASS with parallel implementation

  // Verify all files were processed
  const content = result.llmContent as string[];
  expect(content).toHaveLength(fileCount);

  // Cleanup mock
  detectFileTypeSpy.mockRestore();
});

성능 테스트가 게임 체인저였다!

구글러들이 특히 좋아한 부분은 구체적인 성능 측정 테스트였습니다.

// 실제 성능 개선을 증명하는 테스트
it('should process files in parallel for performance', async () => {
  // 4개 파일 처리 시간 측정
  const startTime = Date.now();
  const result = await tool.execute(params, signal);
  const endTime = Date.now();

  const processingTime = endTime - startTime;

  // 🎯 병렬 처리 효과 검증: 400ms → 200ms 이하
  expect(processingTime).toBeLessThan(200); // ✅ PASS!
});

jacob314의 극찬: "Praised the performance optimization and test coverage"

** 결과:**

• 74% 성능 향상: 408ms → 107ms
• 구체적 증거: 테스트 코드로 성능 개선 입증
• 빠른 승인: 성능 데이터 덕분에 논의 없이 바로 머지

이번 PR은 이전 작업과의 연관성을 명시해서 승인이 매우 빠르게 났습니다.

여러분도 구글 프로젝트에 기여해보세요!

이번 경험을 통해 확실히 알게 된 것들:

• AI와 함께하면 코드베이스 분석이 훨씬 수월함
• 작은 PR부터 시작하면 리뷰어의 신뢰를 얻을 수 있음
• 성능 테스트까지 포함하면 더 좋은 평가를 받음
• 이전 작업과의 연관성을 명시하면 승인이 빨라짐

다음 액션 플랜

이 성공적인 기여 경험을 바탕으로, 더 큰 임팩트를 만들어갈 계획입니다.

단기 목표

• gemini-cli의 TODO 이슈들을 지속적으로 해결하며 핵심 컨트리뷰터 지위 확보
• 성능 최적화, 에러 핸들링, 사용자 경험 개선 등 고부가가치 기여 집중

시작

마이크를 잡는 순간 정말 내가 말해도 되는건가? 나 해도되는건가?

이 생각이 든 건 몇 달 전부터였다. 어느 모임에서 feconf 2024 라이트닝 연사자 분을 만나게 되었다. 재미있게 이야기 하던 도중 나에게 날아든 질문이 있었다.

"상욱님도 이거 잘 하실 수 있을 것 같아요! 너무 좋은 경험이었어서 꼭 해보셨으면 좋겠어요!"

신청

마침 스피커 모집이 있었고 크게 고민하지 않고 신청을 했다. 마침 오픈소스의 즐거움을 알아가던 참이었다. 이 메시지를 전달하면 된다는 생각을 가졌기 때문이다.

평소에 글쓰기도 자주 하고 있어 요약본으로 form을 제출했다. 상세 내역은 github 주소에 md 파일로 올려 신청을 했다.

선정

"됐네?!?!?" 심장이 떨렸다. 스크롤을 다시 올렸다 내렸다를 반복했다. 하지만 카운트 다운이 시작된 것처럼 바쁘게 움직였다.

준비

일정

5/27일에 선정 결과를 받았고 8/23일에 발표였다. 3번 정도의 사전 리허설이 있었다. 나의 목표는 첫 리허설까지 발표 슬라이드 완성이었다.

그렇게 해야 발표일 전까지 피드백을 받아 수정도 가능할 것 같았다.

초안 작성

관련링크

내용에 대한 고민은 많이 하지 않았다. 이미 전달하고 싶은 이야기는 정했기 때문이다. 가장 큰 걱정은 생각보다 양이 많다는 것이었다.

그래도 열심히 적었다. 정말 하고 싶은 이야기 다 적었다. 일단 적고 줄이는 전략으로 만들기 시작한 것이었다.

슬라이드 작성

이렇게 만든 초안을 슬라이드로 옮기는 것이 문제였다. 나는 정말 오랫동안 슬라이드를 만들어본 적이 없기 때문이다.
그래서 여러 플랫폼을 찾아 다녔다. md 파일을 바로 슬라이드로 만들어주는 플랫폼 여러곳이 있었지만 미리캠버스가 가장 원하는 형태로 잘 만들어 주었다. pdf가 필요하긴 했지만 md를 pdf로 바꾸는 건 쉽기 때문에 괜찮았다.

슬라이드로 만드니 대략 나오는 장수는 35장 많이 줄이는 것이 필요 했다. 정말 핵심적인 슬라이드 한장을 고르고 그걸 위주로 내용을 재편집 했다.
그 한 장이 '오픈 소스 코드 읽기로 얻는 것들'이었다.

나도 이력서에 한 줄 넣기 혹은 회사 일 하다가 넣은 것이지만 이것보다는 직접 소스코드를 분석하고 오픈소스를 어떻게 운영하는지에 대해 많이 배웠기 때문이다.

발표 연습

가깝게는 아는 지인들을 총동원 했다. (글쓰기 모임, 아는 오픈 톡방, 회사) 이중에 회사는 사내 발표로 까지 이어져 용돈까지 벌었다. 매우 뜻하지 않게 금전적 이득이 있어 기분이 들떴다.
이때 대략 15분 정도의 분량으로 준비를 해갔다. 남은 5분은 사전리허설의 피드백을 받아 줄여볼 생각이었기 때문이었다.

반응이 좋았다. 내용이 알차다고 피드백을 들었고 전부터 우려했던 목소리 톤이나 속도도 괜찮다는 피드백을 받았다.
하지만 피드백 중에 성향이 갈리는 듯 하였다. 누군가는 "그래서 오픈 소스 어떻게 기여할 수 있는건대?" 또 누군가는 "오픈 소스를 기여 해야하는 이유를 알 수 있어 좋았어요!" 라고 했기 때문이다.
둘다 공감 되는 내용이었고 어느정도 상충이 되는 내용이었다. 상충이 되는 이유는 이미 나에게 주어진 시간이 짧기 때문이었다.
하지만 난 나의 메시지를 전하는 것이 중요하기에 현재 구성 그대로 가기로 했다.

이제 발표 분량을 10분으로 줄일 때가 됐다.

상세하게 넣은 내용들을 다 지우기 시작 했고 큰 뼈대만 남기기 시작 했다.
그리고 내 소개도 지웠다. 내가 다니는 회사 연차 보다는 난 이렇게 오픈소스에 기여 하는걸 즐기는 사람 이라는 내용이 더 청자에게 신뢰감을 줄 수 있다는 판단이었다.
그래서 기여 했던 유명한 오픈소스들을 넣었고 횟수까지 넣었다. 멘트까지 준비 했다. 짧은 기간동안 30회 정도 기여한 사람이라고 이 내용이 현재 오픈 소스를 주제로 발표하는 나를 가장 잘 표현한 문장이라고 생각 했다.

이렇게 줄이기 시작하니 장표는 33장에서 11장으로 줄었다.

사전 리허설

각자의 시간을 투표 받아 사전 리허설을 했다. 정해진 순서에따라 발표를 해보는 건 아니었고 서로의 발표 자료를 보며 피드백을 하는 자리였다.
오거나이저인 재엽님과 동준님이 분위기를 풀어주었고 덕분에 즐겁고 하하 호호 웃으면서 서로의 발표를 들을 수 있었다.
나도 발표를 했고 구성이 너무 좋다, 오픈소스 기여하는 이유가 너무 좋다 등의 좋은 피드백을 들을 수 있었고
추가로 다른 곳에서도 발표 해달라는 제의(?)도 받았다. 기회가 된다면 다른 곳에 가서도 좀 더 내용을 채워서 해보고 싶다는 생각이 들었다.
how에 대한 내용을 조금 줄이고 그 내용은 글을 통해서 남기는 것이 어떻겠냐는 피드백을 들어 이 부분을 좀 수정하기로 했다.
피드백 받은 내용을 수정하기도 하고 발표 준비도 하면서 하루 하루를 보냈다.

발표

당일 도착 하기전

발표날 아침 동준님이 저 사진을 올리면서 라이트닝 스피커가 발표 하는 장소라고 알려주셨다.
순간 당황했다. 하지만 이왕 하는 거 멋진 곳에서 하게 되어서 오히려 흥분됐다. 아드레날린이 손끝까지 전해져 왔다.

컨퍼런스장 도착

단장을 하느라 조금 늦게 갔다.
가서 아는 사람들을 만났다. 오히려 더 많이 이야기를 나누었다. 글쓰기 모임 사람들과 이야기 하고 평소 아는 사람들과도 이야기를 많이 나누었다.
긴장을 풀기 위한 나의 방법 중 하나였다. 하지만 긴장은 쉽게 풀리지 않았다. 다른 세션도 들으러 가보았지만 마음이 둥둥 떠다니다 보니 전혀 들리지 않았다. 리더 토크를 들을 수도 있었는데 전혀 집중하지 못한 것이 아쉽다.

실전

내 앞에 멋지게 킵올빌런님께서 발표 해주셨다. 본인의 은퇴식이라고 멋지게 트위터 계정을 비활성화 하는 퍼포먼스까지 해주셨다. ㅠㅠ
마침내 내 차례가 됐다.
마이크를 잡는 순간 정말 내가 말해도 되는건가? 나 해도되는건가?
마이크는 생각보다 앞선 발표자로 인해 따뜻 했으며 앞에 놓인 노트북은 내가 만들어놓은 발표 자료가 놓여있었다. 관중은 화면을 집중하고 있었고 부모님도 앞아 앉아서 나와 내 발표자료를 바라 보았다.
이런 생각을 2초동안 하고 눈을 질끈 감고 발표를 시작 했다.
연습했던 내용들이 자연스럽게 흘러나왔고 생각보다 나의 발표 속도도 괜찮았다. 그러다 어느 순간 나의 숨쉬는 소리와 침 삼키는 소리가 내 귀에 들렸다.
듣는 순간 난 2초 동안 머리와 입이 멈추었다.(생각해보니 그냥 말하면 되는건대 긴장을 많이 한 탓이다.)
그래도 다행히 정신줄을 붙잡고 다시 발표를 이어나갔다. 그 순간 기묘한 깨달음이 왔다. '아, 나는 이미 충분히 준비됐어. 이제 내 이야기를 들려주기만 하면 되는거야.'

평소에 많이 연습을 한 탓인지 생각하면서 말을 하는 게 아니라 그냥 머슬메모리로 발표를 이어나갔다. 신기하게도 내 목소리가 점점 더 자연스러워지고 있었다.

발표가 끝났다. 마지막 슬라이드를 넘기는 순간, 본능적으로 숨을 깊게 들이마셨다. 박수 소리가 울리니까 비로소 속에서 그제서야 실감이 났다. '나, 해냈다!'

다리가 아직도 떨리고 있었지만, 이상하게 모든 게 선명해 보였다. 아들이 큰 곳에서 발표한다고 여기까지 와서 날 촬영해준 부모님의 웃음, 그동안 흐리게만 보였던 컨퍼런스장의 모습, 대기실에서 나를 지켜보던 다른 연사자들의 따뜻한 시선까지.

그제야 컨퍼런스장이 눈에 들어오기 시작했다. 네트워킹 장도 눈에 들어오기 시작했다.

컨퍼런스 즐기기

네트워크장은 매우 뜨거웠으며 다들 열띤 토론을 이어나갔다. 아쉽게도 내 발표가 뒷쪽이라 네트워크에 어울리지는 못 했지만 다들 비슷한 도메인 같은 직업 같은 고민을 하는 사람들이라 정말 쉼없이 토론을 하는 것을 보고 매우 흥미로웠다.
네트워킹을 나도 나중에 꼭 즐길 수 있었으면 좋겠다는 생각을 했다.
단 하나의 세션만 들었는대 그것은 flex 김종혁 님의 모노레포 절망편, 14개 레포로 부활하기까지 걸린 1년 이었다 나도 개인적으로 모노레포 떄문에 고통을 많이 받고 있어 이야기를 들으러 갔고 내가 얻은 인사이트는 결국 모노레포의 이야기 보다는
각 레이어의 역할이 충실하지 않아 발생하는 문제라고 생각을 했고 여기선 그 문제를 코드를 물리적으로 떼어놓는 것으로 해결 했다는 것이었다. 매우 흥미로웠고 현재 회사의 프로젝트에 패키지를 하나 만들 때마다 어떻게 적용 시킬 수 있을 지 고민을 하게 되었다.

뒷풀이

발표가 끝난 뒤에는 토스에서 주최하는 프라이빗 파티에 왔다.

음식은 굉장히 맛있었고 몇가지 주제로 각 테이블에서 열띈 토론을 하였는대 우리테이블은

1. 빠르게 vs 잘하게
2. 코드 리뷰 문화 개선

각 회사의 사정이 다르고 상황이 달라 의견이 조금씩 차이가 났다 그래도 공감 하는 부분은 각 각의 트레이드 오프를 생각해서 상황에 맞게 잘 적용 하는 것이라는 것이다.
사업의 생존이 걸릴 때는 빠르게 만들어서 반응을 보는 편이 좋고, 잘하게가 중요한 부분은 시스템을 설계하거나 기술 부채를 해결 할 때는 잘하게가 중요 했다.

코드리뷰 문화 개선은 소통 문제를 쿠션어나 영어만을 사용하여 말투를 바꾸어보는 사례가 있었고 병목이 되는 지점을 자동화나 프로세스 개선을 통해 해결 하는 모습이 있다로 정리 하였다.

마무리

한번도 컨퍼런스에 참여를 해보지 않았다. 선정에서 떨어지거나 표를 구하기도 어려웠고 시간을 내지 못 해 못 간 것도 있었다.
하지만 이렇게 오프라인 네트워크가 짜릿한 즐거움을 줄 수 있다는 걸 처음 느꼈다. 그리고 그걸 컨퍼런스에서 할 수 있다는 것도 처음 알았다.
그리고 feconf에서 발표를 하면서 내 안에 숨어있던 다른 모습을 발견했다. 예전 같으면 두려워서 피했을 일들에 도전하고 싶어하는 나. 완벽하지 않아도 일단 도전하고 나서 개선해 나가는 나. 그런 나를 처음 만났다.
네트워킹 및 세션에는 적극적으로 참여하지 못 한건 많이 아쉽지만 그건 다음 feconf 에선 꼭 열심히 참여하겠다고 생각을 했다.

아직 하고 싶은 이야기가 많으니 내년엔 feconf 메인세션으로 올라가 발표를 한번 더 해보고 싶다.

AI 페어 프로그래밍으로 오픈소스 진입 장벽 낮추기

“무조건 Node.js에 내 코드를 넣고 말겠다!”
오픈소스 기여가 점점 재미있어지고, 자신감도 차오르던 시기였다.
하지만 매일같이 이슈를 살펴봐도 여전히 모르는 부분이 많았다. C++ 코드가 보이기도 했고, fs 같은 코어 모듈이 대부분이었기 때문이다. (게다가 이슈를 완벽히 이해한 것도 아니었다.)
그러던 중 AI를 활용한 오픈소스 기여 모임을 알게 되었고, 거기서 본 한 링크가 나에게 혁신을 가져다주었다.

1. 이슈 찾기: AI로 시작하는 빠른 탐색

이슈 분석에 어려움을 느끼던 내게 구세주가 나타났다.
바로 이슈 수집기였다.
곧장 nodejs/node 저장소와 내 토큰을 입력하고 모든 이슈를 긁어왔다. (지금도 매일 한다.)

그중 눈에 들어온 이슈가 있었다.

Issue 23: util.inspect incorrectly formats negative fractional numbers

• 라벨: 없음
• 내용: numericSeparator: true 옵션 사용 시 음수 소수점 숫자 포맷팅 버그
• 원인: formatNumber 함수에서 -0 처리 시 부호 손실
• 해결 방향: 없음
• 적합도: 상 (재현 코드와 명확한 문제 설명)
• 기술 난이도: 중

C++도 없고, 복잡한 코어 모듈도 아닌, 숫자 유틸 함수 하나를 수정하는 일이었다.
게다가 이슈가 올라온 지 5시간밖에 되지 않아 바로 댓글을 달고 선점했다.

곧 메인테이너가 해결 방향과 최적화 아이디어를 제시해주었고, 나는 지체 없이 코드를 수정하러 들어갔다.

AI 활용 팁: 이슈 선택 시 체크리스트

• 난이도: 너무 어려운 영역(C++, 네이티브 모듈 등)은 피하고, 변경 범위가 명확한 이슈를 선택합니다.
• 재현 가능성: 이슈 설명에 재현 코드나 명확한 조건이 포함되어 있는지 확인합니다.
• 라벨 여부: 'good first issue', 'help wanted' 라벨은 초심자에게 좋은 출발점입니다.

2. 문제 분석: 버그 원인 파악하기

문제는 간단했다.
util.inspect에서 numericSeparator 옵션을 켜면, 0과 1 사이의 음수 값에서 부호가 사라지는 현상이 있었다.

import { inspect } from 'util';

const values = [0.1234, -0.12, -0.123, -0.1234, -1.234];
const text = inspect(values, { numericSeparator: true });
console.log(text);

// 기대 출력
[ 0.123_4, -0.12, -0.123, -0.123_4, -1.234 ]

// 실제 출력
[ 0.123_4, 0..12, 0..12_3, 0..12_34, -1.234 ]

문제의 원인은 lib/internal/util/inspect.js에서 숫자를 문자열로 변환할 때, -0이 "0"으로 변환되어 부호가 사라지는 것이었다.

3. 개발 환경 구축: 로컬에서 Node.js 빌드하기

Node.js 저장소를 포크 후 클론 받아 AI CLI 환경에서 코드베이스를 학습시켰다.

처음에는 C++이 없어서 빌드 에러가 발생했다. AI와 함께 원인을 찾아보니 Command Line Tools 설치가 필요했다. 설치 후 다시 빌드하니 약 30분 만에 성공.

처음 직접 빌드한 Node.js를 실행했을 때, 테스트 코드가 정상 동작하는 것을 보고 꽤 뿌듯했다.

AI 활용 팁: 빌드 에러 대처

• 환경 의존성: C++ 컴파일러, Python 버전 등 필수 의존성을 먼저 확인합니다.
• 빌드 로그 분석: 에러 메시지를 그대로 AI에게 전달하면 빠르게 해결책을 제시해줍니다.
• 부분 빌드: 전체 빌드가 오래 걸린다면, 변경된 부분만 빌드하는 방법을 찾아보세요.

4. 테스트 작성: 버그 재현부터 시작

다음 단계는 재현 테스트 작성이었다.
이슈(#59376) 내용을 기반으로 아직 통과하지 못하는 테스트를 만들고, 단일 파일 테스트를 실행했다.

./out/Release/node test/parallel/test-util-inspect.js

이슈 상황이 정상적으로 재현되는 것을 확인하고 수정 작업에 착수했다.

5. 버그 수정: 부호 보존 로직 추가

수정 전 formatNumber

// 수정 전 (버그가 있던 코드)
const integer = MathTrunc(number);
const string = String(integer);

// 소수점 처리
return fn(
  `${
    addNumericSeparator(string) // <- 여기서 음수 부호 손실
  }.${addNumericSeparatorEnd(
    StringPrototypeSlice(String(number), string.length + 1),
  )}`,
  'number',
);

수정 후 formatNumber

function formatNumber(fn, number, numericSeparator) {
  if (!numericSeparator) {
    if (ObjectIs(number, -0)) return fn('-0', 'number');
    return fn(`${number}`, 'number');
  }

  const numberString = String(number);
  const integer = MathTrunc(number);

  if (integer === number) {
    if (!NumberIsFinite(number) || StringPrototypeIncludes(numberString, 'e')) {
      return fn(numberString, 'number');
    }
    return fn(addNumericSeparator(numberString), 'number');
  }

  if (NumberIsNaN(number)) {
    return fn(numberString, 'number');
  }

  // 원본 문자열에서 직접 소수점 위치 찾기
  const decimalIndex = StringPrototypeIndexOf(numberString, '.');
  // 방어적 주석: IEEE-754에서 이 분기까지 오는 경우는 거의 없음
  if (decimalIndex === -1) return fn(numberString, 'number');

  // 원본 문자열에서 정수/소수 부분 분리
  const integerPart = StringPrototypeSlice(numberString, 0, decimalIndex);
  const fractionalPart = StringPrototypeSlice(numberString, decimalIndex + 1);

  return fn(
     return fn(`${
    addNumericSeparator(integerPart)  // <- 음수 부호 보존
  }.${
    addNumericSeparatorEnd(fractionalPart)
  }`, 'number');
}

이유

• 문제: -0.1234에서 Math.trunc(-0.1234) = -0, String(-0) = "0"이 되어 음수 기호가 사라짐
• 해결: 원본 문자열 -0.1234에서 직접 . 앞부분(-0)과 뒷부분(1234)을 분리

메인테이너가 제안한 방향(string 한번만 사용)을 반영하고, 이슈 제기자가 지적한 잠재적 케이스에 대해 방어적 주석을 남겼다.

6. Pull Request

AI에게 요약을 맡겨 PR 메시지를 작성하고, 로컬 테스트 통과 스크린샷과 함께 Push했다.
메인테이너는 빠르게 승인을 줬지만, 병합은 다른 PR과 함께 진행하는 듯했다.

이슈 제기자는 내 코드에 특정 케이스에서 버그가 날 수 있다고 했지만, 해당 케이스가 이미 테스트 코드에 포함되어 있었기에 문제없음을 설명했다.

7. 회고: AI와 함께한 오픈소스 첫걸음

이번 경험에서 느낀 점은 다음과 같다.

1. AI는 오픈소스 진입 장벽을 크게 낮춰준다.
   빌드·테스트 환경 설정, 코드 구조 파악 등에서 큰 도움을 받았다.
2. 작은 이슈도 충분히 가치 있다.
   코어 모듈이 아니더라도 유지보수와 품질 개선에 기여할 수 있다.
3. 테스트 코드 작성이 핵심이다.
   버그를 명확히 재현하고, 수정 후에도 안정성을 보장할 수 있었다.

앞으로도 AI를 적극적으로 활용해 더 많은 오픈소스 기여와 학습을 이어가고 싶다.

들어가며

"띠링" 새벽 2시, 내 핸드폰에 또 다른 GitHub 알림이 울렸다.

발신자: vercel/next.js
[제목] : Re:[vercel/next.js] Fix remote pattern (#80294) (PR #80428)

아, 이건 하면 안 되는 거였구나...

빨간색 "Closed" 라벨이 붙은 내 PR을 멍하니 바라보며, 가슴이 철렁 내려앉았다.

잠은 이미 다 깼고, 구글링으로 찾은 "How to contribute to Next.js" 글들은 아무런 도움이 되지 않았다. 마치 미로에 갇힌 기분이었다.

"생각보다 많이 어렵네..." 내적으로 혼잣말을 중얼거렸다.

이게 나의 두 번째 실패였다. 하지만 포기하고 싶지 않았다. 어딘가에서 '너도 할 수 있어'라는 목소리가 들리는 것 같았다.

한 달 후, 나는 Next.js Contributors 목록에 이름을 올렸다. 그 순간의 짜릿함과 벅참은 지금도 잊을 수 없다.

여러분도 오픈소스 기여에 도전하다가 좌절한 경험이 있으신가요? 실패가 두려워서 시도조차 못하고 계신가요?
그 과정에서 느꼈던 막막함과 불안감, 그리고 다시 일어서고 싶은 마음... 모두 이해합니다. 그 사이에 무슨 일이 있었는지, 지금부터 솔직하게 털어놓겠습니다.

첫 번째 실패: "이런 게 개발자의 현실인가?"

Fix segment prefetches fail with HTTP 400

3개월 전, Next.js 이슈 페이지를 뒤적이던 나는 마치 보물을 발견한 듯 가슴이 뛰었다.

"이거다! 예제 코드도 있고, 문제 코드 추정 부분까지 친절하게 써있어. 이 정도면 금방 할 수 있겠지?"

당시 내 마음은 설렘이 90%, 불안감이 10% 정도였다. 솔직히 말하면 "이거 성공하면 이력서에 써도 되겠는걸?" 이런 생각까지 들었다. 오픈소스 기여가 Next.js라니, 생각만 해도 가슴이 뛰었다.

실제로는 아무것도 모르는 상태로 무작정 도전했다. 지금 생각해보니 정말 용감했다. App Router의 prefetch라는 실험적인 기능에 덤벼들었는데, 이게 얼마나 복잡한 기능인지도 모르고 말이다.

로컬 환경 설정부터 막혀서 3일 동안 삽질했지만, 그래도 테스트 코드 구조만큼은 이해할 수 있었다. nextTestSetup()이라는 특별한 함수를 사용한다는 것도 이때 처음 알았다.

/**
 * 당시 내가 만든 테스트 코드
 * 시작점을 여기로 설정하면 같은 경로의 next.js 코드가 들어가게 된다(신기)
 */
import { nextTestSetup } from 'e2e-utils';
import { fetchViaHTTP } from 'next-test-utils';

describe('Segment prefetches with rewritten paths', () => {
  const { next } = nextTestSetup({
    files: __dirname,
  });

  // 필요한 부분만 이렇게 셋팅해서 테스트가 가능 하다.
  it('should fail with HTTP 400 when path is rewritten but hash is incorrect (reproducing issue #80014)', async () => {
    const res = await fetchViaHTTP(next.url, '/test', undefined, {
      headers: {
        RSC: '1',
        'Next-Router-Prefetch': '1',
        'Next-Router-Segment-Prefetch': '/_tree',
      },
    });

    expect(res.status).toBe(200);
  });
});

하지만 진짜 문제는 그 다음이었다. 테스트는 돌릴 수 있게 되었지만, 정작 실제 이슈를 어떻게 해결해야 할지 전혀 감이 오지 않았다. 코드베이스가 너무 복잡했고, 어디서부터 손을 대야 할지 막막했다.

결국 PR을 올리지도 못하고 포기했다. 그 순간의 감정: 허탈함과 함께 "내가 너무 어려운 걸 골랐구나"라는 뼈아픈 깨달음이었다.

💡 Next.js 테스트 환경 제대로 구축하기

일반적인 React 테스트와 달리 Next.js는 프레임워크 차원의 특수한 구조를 가지고 있다. 이를 모르면 며칠을 헤맬 수 있다.

왜 Next.js 테스트가 까다로운가?

• 서버사이드 렌더링, 라우팅, 빌드 과정이 모두 연결되어 있음
• 단순한 컴포넌트 테스트로는 실제 동작을 재현할 수 없음

Next.js만의 특별한 테스트 구조

• nextTestSetup(): Next.js 전용 테스트 유틸리티 활용
• E2E 테스트 환경에서 실제 서버 동작 재현
• fetchViaHTTP() 같은 Next.js 전용 헬퍼 함수들 이해하기

로컬에서 제대로 실행하기

• 의존성 설치 후 반드시 전체 빌드 먼저 실행
• 특정 테스트만 실행: npm test -- --testPathPattern="특정키워드"

그날 밤, 침대에 누워서 생각했다. "다음엔 좀 더 쉬운 걸로 해야겠어."

두 번째 실패: "자신감이 독이 될 줄이야"

Fix remote pattern

첫 번째 실패 후 한 달 뒤, 나는 다시 도전장을 내밀었다.

"이번엔 다르다. next/image는 내가 매일 쓰는 컴포넌트잖아. 이정도는 할 수 있어!"

이번엔 자신감이 70%, 조심스러움이 30% 정도였다. "이번엔 확실히 쉬운 걸로 골랐어"라고 생각했다. next/image는 내가 프로젝트에서 매일 사용하는 컴포넌트니까 말이다.

next/image 컴포넌트의 쿼리스트링 와일드카드 문제를 선택했다. 이슈를 보면서 "아, 이미지 src에 ?* 같은 와일드카드가 안 들어가는 거네?"라고 파악했다. 이번엔 테스트 코드도 자신 있게 작성했는데, dist가 있다는 걸 모르고 며칠을 고생했다.

/**
 * next/image remote pattern 확인하는 코드
 * 결국 여기도 읽어보면 별거 없다
 * 별거 없는 것 처럼 보이게 코드를 잘 나눈 것 같기도 하다.
 */
import type { RemotePattern } from './image-config';
import { makeRe } from 'next/dist/compiled/picomatch';

export function matchRemotePattern(
  pattern: RemotePattern | URL,
  url: URL,
): boolean {
  if (pattern.protocol !== undefined) {
    if (pattern.protocol.replace(/:$/, '') !== url.protocol.replace(/:$/, '')) {
      return false;
    }
  }
  if (pattern.port !== undefined) {
    if (pattern.port !== url.port) {
      return false;
    }
  }

  if (pattern.hostname === undefined) {
    throw new Error(
      `Pattern should define hostname but found\n${JSON.stringify(pattern)}`,
    );
  } else {
    if (!makeRe(pattern.hostname).test(url.hostname)) {
      return false;
    }
  }

  /**
   *  이 부분을 새로 썻다 기존 테스트 코드도 통과 시키면서 와일드 카드를 허용 시키는 코드였다.
   */
  const patternSearch = pattern.search ?? '';
  const patternPath = pattern.pathname ?? '**';
  const isSpecificWildcardPath =
    patternPath.includes('**') && patternPath !== '**' && patternPath !== '/**';

  if (patternSearch !== '') {
    if (patternSearch !== url.search) {
      return false;
    }
  } else if (url.search && !isSpecificWildcardPath) {
    return false;
  }

  // Should be the same as writeImagesManifest()
  if (!makeRe(pattern.pathname ?? '**', { dot: true }).test(url.pathname)) {
    return false;
  }

  return true;
}

// 그 당시 적었던 테스트 코드
it('should match URLs with wildcard patterns', () => {
  // 허용되는 패턴
  const p = 'https://example.com/act123/**';
  expect(m(new URL(p), new URL('https://example.com/act123/usr4?v=4'))).toBe(
    true,
  );
  expect(
    m(new URL(`${p}/*`), new URL('https://example.com/act123/u/74867549?v=4')),
  ).toBe(true);
});

2주 후, 또다시 내 PR이 닫혔다. 이번엔 더 상세한 설명과 함께.

메인테이너: "이 동작은 예상된 동작입니다. 이 코드가 머지되면 안 돼요."

그 순간 나는 뒤통수를 맞은 기분이었다.

"아... 이게 버그가 아니라 의도적인 거였구나. 나는 왜 이걸 미리 확인 안 했지?"

내가 버그라고 생각한 것이 사실은 보안상의 이유로 의도적으로 막아놓은 기능이었다. 그날은 정말 자존심이 상했다. 카페에서 앉아서 노트북을 덮고 한참을 멍때렸다. "내가 개발을 잘못 배운 건가?"

💡 이슈 분석과 문서 읽기

"이건 분명 버그야!"라고 성급하게 판단하기 전에, 의도된 동작일 가능성을 먼저 체크해야 한다.

1단계: 공식 문서 우선 탐색

• 해당 기능의 공식 문서에서 제약사항이나 보안 관련 언급 확인
• API 레퍼런스에서 예외 케이스나 주의사항 섹션 정독

2단계: 이슈 판별 기준 적용

• 기능이 완전히 작동 안 하는가? vs 특정 상황에서만 제한되는가?
• 보안, 성능상 이유로 의도적 제한일 가능성 검토
• GitHub Issues에서 similar한 토론이나 closed 이슈 검색

세 번째 도전: "AI와 함께라면 다를 거야"

Fix before interactive incorrectly render css

두 번의 실패 후 2개월이 지났다. 솔직히 말하면 조금 겁이 났다.

어느 날, AI와 코드 리뷰를 하다가 문득 생각이 들었다. "이번엔 혼자 하지 말고 AI와 함께 해볼까?"

이번엔 마음가짐부터 달랐다. 겸손함이 50%, 신중함이 40%, 기대감이 10% 정도였다. "이번엔 정말 확실하게 하자"는 다짐을 했다. 두 번의 실패를 겪으니 자연스럽게 조심스러워졌다.

AI와 함께한 과정:

나: "이 이슈 어떻게 생각해?"
AI: "script 컴포넌트의 다른 옵션들은 모두 파싱 함수를 거치는데, 이 부분만 빠져있네요."
나: "맞네! 다른 옵션들은 잘 동작하는데 이것만 안 되고 있어."

이때의 감정은 정말 특별했다. 마치 퍼즐의 마지막 조각을 맞춘 기분이었달까. AI의 객관적인 시각이 내가 놓친 부분들을 하나씩 짚어주었다.

/**
 * Before starting the Next.js runtime and requiring any module, we need to make
 * sure the following scripts are executed in the correct order:
 * - Polyfills
 * - next/script with `beforeInteractive` strategy
 */

import { setAttributesFromProps } from './set-attributes-from-props';

function loadScriptsInSequence(
  scripts: [src: string, props: { [prop: string]: any }][],
  hydrate: () => void,
) {
  if (!scripts || !scripts.length) {
    return hydrate();
  }

  return scripts
    .reduce((promise, [src, props]) => {
      return promise.then(() => {
        return new Promise<void>((resolve, reject) => {
          const el = document.createElement('script');

          if (props) {
            // 여기 하나 추가 해줬다. 하지만 엄청 짜릿했다.
            setAttributesFromProps(el, props);
          }

          if (src) {
            el.src = src;
            el.onload = () => resolve();
            el.onerror = reject;
          } else if (props) {
            el.innerHTML = props.children;
            setTimeout(resolve);
          }

          document.head.appendChild(el);
        });
      });
    }, Promise.resolve())
    .catch((err: Error) => {
      console.error(err);
      // Still try to hydrate even if there's an error.
    })
    .then(() => {
      hydrate();
    });
}

이번엔 정말 간단하고 명확한 이슈를 선정했다. script 컴포넌트에서 누락된 유틸 함수를 찾는 것이었다. AI가 수정이 필요한 부분을 제시해주었고, 나는 그걸 꼼꼼히 검토했다. 테스트 코드는 이슈의 예제 코드를 기준으로 회귀 테스트를 작성해달라고 요청했다.

// 그때 보다 훨씬 풍부해지고 깔끔한 테스트 코드를 작성할 수 있게 되었다.
import { nextTestSetup } from 'e2e-utils';

describe('Script component with beforeInteractive strategy CSS class rendering', () => {
  const { next } = nextTestSetup({
    files: __dirname,
  });

  it('should render script tag with correct class attribute instead of classname', async () => {
    const browser = await next.browser('/');

    // Wait for the page to fully load
    await browser.waitForElementByCss('#example-script');

    // Get the HTML content to check the actual rendered attributes
    const html = await browser.eval(() => document.documentElement.innerHTML);

    // Check that the script tag has 'class' attribute, not 'classname'
    expect(html).toContain('class="example-class"');
    expect(html).not.toContain('classname="example-class"');

    // Also verify the script element directly
    const scriptElement = await browser.elementByCss('#example-script');
    const className = await scriptElement.getAttribute('class');

    expect(className).toBe('example-class');
  });

  it('should execute beforeInteractive script correctly', async () => {
    const browser = await next.browser('/');

    // Check that the script executed by looking for its side effects
    const hasExecuted = await browser.eval(() => {
      return (window as any).beforeInteractiveExecuted === true;
    });

    expect(hasExecuted).toBe(true);
  });

  it('should render script in document head with beforeInteractive strategy', async () => {
    const browser = await next.browser('/');

    // Check that the script is in the head section
    const scriptInHead = await browser.eval(() => {
      return document.head.querySelector('#example-script') !== null;
    });

    expect(scriptInHead).toBe(true);
  });

  it('should render multiple beforeInteractive scripts with correct class attributes', async () => {
    const browser = await next.browser('/multiple');

    const html = await browser.eval(() => document.documentElement.innerHTML);

    // Check that both scripts have correct class attributes
    expect(html).toContain('class="first-script"');
    expect(html).toContain('class="second-script"');
    expect(html).not.toContain('classname="first-script"');
    expect(html).not.toContain('classname="second-script"');
  });
});

3주 후...

GitHub 알림: "✅ Merged into main branch"

그 순간을 지금도 생생히 기억한다. 손이 떨렸다. 정말로. 가슴이 벅차올랐고, 눈물까지 날 뻔했다. "드디어 해냈구나!"

💡 AI 활용 코드베이스 정복법

거대한 Next.js 코드베이스 앞에서 막막할 때, AI 도구를 제대로 활용하면 혼자 며칠 걸릴 일을 몇 시간 만에 해결할 수 있다.

1단계: 코드베이스 학습시키기

• Claude Code의 /init 명령어로 전체 프로젝트 학습
• SuperClaude의 커스텀 명령어로 추가 분석

2단계: 이슈 함께 파악하기

• 이슈를 AI에게 공유하고 "함께 파악해보자" 요청
• AI가 제시하는 수정 포인트를 꼼꼼히 검토

3단계: 테스트 코드 협업 작성

• 이슈의 예제 코드를 기준으로 회귀 테스트 작성 요청
• AI가 작성한 테스트를 검증하고 보완

이 경험이 내게 남긴 것들

감정적으로 많이 성장했다. 무엇보다 실패에 대한 두려움이 줄어들었다. 예전 같으면 한 번 실패하고 나서 주저했을 텐데, 이제는 실패도 성장의 과정이라고 받아들이게 되었다. 혼자서 모든 걸 해결하려는 고집 대신 협력의 힘을 배웠다.

기술적으로도 확실히 늘었다. 복잡한 코드베이스를 읽는 능력이 향상되었고, 테스트 코드 작성 스킬도 많이 늘었다. 무엇보다 이슈를 제대로 분석하는 방법을 익혔다. 단순히 코드만 보는 것이 아니라, 그 이슈가 왜 생겼는지, 어떤 맥락에서 발생한 건지를 파악하는 능력 말이다.

가장 중요한 깨달음: 실패에서 나오는 배움이 더 크다는 것.

첫 번째 실패에서 Next.js 테스트 환경의 복잡함을, 두 번째 실패에서 문서 정독의 중요성을 배웠다. 이런 교훈들이 없었다면 세 번째 도전에서 AI와 협력하는 전략도 떠올리지 못했을 것이다.

Next.js 기여를 꿈꾸는 여러분께:

실패해도 괜찮습니다. 그 실패가 더 큰 성공의 발판이 될 테니까요. 저의 경험이 조금이라도 도움이 되었으면 좋겠습니다.

결국 성공했다. 다음에 또 하라고 하면? 당연히 하고 싶다.
그리고 AI와 함께 하는 이런 협력 방식, 정말 추천하고 싶다.

평소처럼 Mantine의 Dropzone을 사용하고 있었는데, 문득 내부 구현이 궁금해졌습니다. 어떻게 이렇게 깔끔한 API를 제공할 수 있을까?

// Mantine Dropzone 사용 중...
<Dropzone onDrop={handleDrop}>
  <Dropzone.Idle>기본 상태</Dropzone.Idle>
  <Dropzone.Accept>허용 상태</Dropzone.Accept>
  <Dropzone.Reject>거부 상태</Dropzone.Reject>
</Dropzone>

마침 그때 디자인 팀에서 연락이 왔습니다.

[디자이너]: "파일 업로드 컴포넌트를 우리 디자인 시스템에 맞게 다시 만들어야 할 것 같아요. Mantine 스타일이 브랜드와 안 맞아서..."

[나]: "아, 그럼 Dropzone도 자체 구현해야 하는 건가요?"

[디자이너]: "네, 그리고 상태별로 다른 애니메이션이랑 아이콘도 써야 하고... 기본, 허용, 거부, 로딩 상태 모두 다르게 보여주세요!"

순간 두 가지 생각이 스쳐갔습니다. "어차피 다시 만들어야 한다면, Mantine의 내부 구현을 분석해서 더 나은 방식으로 만들어보자!"

그렇게 Mantine의 Dropzone 컴포넌트를 뜯어보다가 Context API + 컴파운드 컴포넌트 패턴의 놀라운 조합을 발견했습니다.

1부: Mantine 분석과 자체 구현의 필요성

Mantine Dropzone 분석하기

먼저 Mantine의 Dropzone이 어떻게 동작하는지 살펴봤습니다. 정말 간단한 API로 복잡한 상태 관리를 숨기고 있더군요.

// Mantine의 놀라운 API
<Dropzone onDrop={handleDrop}>
  <Dropzone.Idle>파일을 드래그하세요</Dropzone.Idle>
  <Dropzone.Accept>파일을 놓으세요</Dropzone.Accept>
  <Dropzone.Reject>지원하지 않는 파일입니다</Dropzone.Reject>
</Dropzone>

[나]: "어떻게 이렇게 간단한 API로 복잡한 상태 관리를 할 수 있지?"

자체 구현 시 고려사항

디자인 시스템에 맞게 자체 구현하면서도 Mantine의 좋은 패턴은 그대로 가져가고 싶었습니다. 하지만 처음엔 단순하게 접근했죠.

// 처음에 생각한 방식 (문제가 많음)
const DropZone = () => {
  const [dragState, setDragState] = useState<'idle' | 'accept' | 'reject'>(
    'idle',
  );
  const [loading, setLoading] = useState(false);

  const renderContent = () => {
    if (loading) {
      return <LoadingSpinner />;
    }

    if (dragState === 'accept') {
      return (
        <div>
          <CheckIcon />
          <span>파일을 놓으세요</span>
        </div>
      );
    }

    if (dragState === 'reject') {
      return (
        <div>
          <WarningIcon />
          <span>지원하지 않는 파일 형식입니다</span>
        </div>
      );
    }

    return (
      <div>
        <UploadIcon />
        <span>파일을 드래그하거나 클릭하세요</span>
      </div>
    );
  };

  return (
    <div onDragOver={handleDragOver} onDrop={handleDrop}>
      {renderContent()}
    </div>
  );
};

2부: Context API를 활용한 컴파운드 컴포넌트 설계

컴파운드 컴포넌트 패턴이란?

컴파운드 컴포넌트 패턴은 여러 컴포넌트가 협력해서 하나의 기능을 구현하는 패턴입니다. HTML의 <select>와 <option>의 관계와 비슷해요.

// 우리가 목표로 하는 API
<DropZone onDrop={handleDrop}>
  <DropZone.Idle
    icon="Upload"
    mainMessage="파일을 드래그하거나 클릭하세요"
    supportMessage="최대 10MB, JPG, PNG, PDF 지원"
  />
  <DropZone.Accept mainMessage="파일을 놓으세요" />
  <DropZone.Reject
    mainMessage="지원하지 않는 파일입니다"
    supportMessage="JPG, PNG, PDF만 업로드 가능합니다"
  />
</DropZone>

Context API를 통한 상태 공유

핵심 아이디어는 Context API로 DropZone의 모든 상태를 중앙 관리하고, 컴파운드 컴포넌트들이 이 상태를 구독하는 것입니다.

import {
  createContext,
  useContext,
  useCallback,
  useState,
  type ReactNode,
} from 'react';

type DropzoneStatus = 'idle' | 'accept' | 'reject' | 'loading';

type DropzoneContextValue = {
  // 상태
  status: DropzoneStatus;
  files: File[];
  error: string | null;

  // 액션
  setStatus: (status: DropzoneStatus) => void;
  setFiles: (files: File[]) => void;
  setError: (error: string | null) => void;
  resetState: () => void;

  // 드래그 이벤트 핸들러
  handleDragEnter: (e: DragEvent) => void;
  handleDragLeave: (e: DragEvent) => void;
  handleDragOver: (e: DragEvent) => void;
  handleDrop: (e: DragEvent) => void;
};

const DropzoneContext = createContext<DropzoneContextValue | null>(null);

export const useDropzoneContext = () => {
  const context = useContext(DropzoneContext);
  if (!context) {
    throw new Error('Dropzone 컴포넌트 내에서만 사용할 수 있습니다.');
  }
  return context;
};

type DropzoneProviderProps = {
  children: ReactNode;
  onDrop?: (files: File[]) => void;
  accept?: string[];
  maxSize?: number;
};

export const DropzoneProvider = ({
  children,
  onDrop,
  accept = [],
  maxSize = 10 * 1024 * 1024, // 10MB
}: DropzoneProviderProps) => {
  const [status, setStatus] = useState<DropzoneStatus>('idle');
  const [files, setFiles] = useState<File[]>([]);
  const [error, setError] = useState<string | null>(null);

  const validateFiles = useCallback(
    (fileList: File[]) => {
      const validFiles: File[] = [];
      let hasError = false;

      fileList.forEach(file => {
        // 파일 타입 검증
        if (accept.length > 0) {
          const isAccepted = accept.some(acceptType => {
            if (acceptType.endsWith('/*')) {
              return file.type.startsWith(acceptType.slice(0, -1));
            }
            return file.type === acceptType;
          });

          if (!isAccepted) {
            setError(`지원하지 않는 파일 형식입니다: ${file.name}`);
            hasError = true;
            return;
          }
        }

        // 파일 크기 검증
        if (file.size > maxSize) {
          setError(`파일 크기가 너무 큽니다: ${file.name}`);
          hasError = true;
          return;
        }

        validFiles.push(file);
      });

      return { validFiles, hasError };
    },
    [accept, maxSize],
  );

  const handleDragEnter = useCallback((e: DragEvent) => {
    e.preventDefault();
    e.stopPropagation();
    setStatus('accept');
    setError(null);
  }, []);

  const handleDragLeave = useCallback((e: DragEvent) => {
    e.preventDefault();
    e.stopPropagation();
    setStatus('idle');
  }, []);

  const handleDragOver = useCallback((e: DragEvent) => {
    e.preventDefault();
    e.stopPropagation();
  }, []);

  const handleDrop = useCallback(
    (e: DragEvent) => {
      e.preventDefault();
      e.stopPropagation();

      const droppedFiles = Array.from(e.dataTransfer?.files || []);
      const { validFiles, hasError } = validateFiles(droppedFiles);

      if (hasError) {
        setStatus('reject');
        return;
      }

      setFiles(validFiles);
      setStatus('loading');
      onDrop?.(validFiles);
    },
    [validateFiles, onDrop],
  );

  const resetState = useCallback(() => {
    setStatus('idle');
    setFiles([]);
    setError(null);
  }, []);

  const value: DropzoneContextValue = {
    status,
    files,
    error,
    setStatus,
    setFiles,
    setError,
    resetState,
    handleDragEnter,
    handleDragLeave,
    handleDragOver,
    handleDrop,
  };

  return (
    <DropzoneContext.Provider value={value}>
      {children}
    </DropzoneContext.Provider>
  );
};

메인 DropZone 컴포넌트 구현

import type { ReactNode, HTMLAttributes } from 'react';
import { DropzoneProvider, useDropzoneContext } from './context';
import { Accept, Idle, Reject, Loading } from './status';
import { dropzoneContainer } from './styles';

type DropzoneProps = {
  children: ReactNode;
  onDrop?: (files: File[]) => void;
  accept?: string[];
  maxSize?: number;
  className?: string;
} & Omit<HTMLAttributes<HTMLDivElement>, 'onDrop'>;

// 내부 컨테이너 컴포넌트 - Context를 사용
const DropzoneContainer = ({
  children,
  className,
  ...restProps
}: Omit<DropzoneProps, 'onDrop' | 'accept' | 'maxSize'>) => {
  const {
    handleDragEnter,
    handleDragLeave,
    handleDragOver,
    handleDrop,
    status,
    error,
  } = useDropzoneContext();

  const { container } = dropzoneContainer({
    status,
    error: !!error,
  });

  return (
    <div
      className={`${container} ${className || ''}`}
      onDragEnter={handleDragEnter}
      onDragLeave={handleDragLeave}
      onDragOver={handleDragOver}
      onDrop={handleDrop}
      {...restProps}
    >
      {children}
    </div>
  );
};

// 메인 Dropzone 컴포넌트
const Dropzone = ({
  children,
  onDrop,
  accept,
  maxSize,
  ...containerProps
}: DropzoneProps) => {
  return (
    <DropzoneProvider onDrop={onDrop} accept={accept} maxSize={maxSize}>
      <DropzoneContainer {...containerProps}>{children}</DropzoneContainer>
    </DropzoneProvider>
  );
};

// 컴파운드 컴포넌트 연결
Dropzone.Accept = Accept;
Dropzone.Idle = Idle;
Dropzone.Reject = Reject;
Dropzone.Loading = Loading;

export default Dropzone;

각 상태별 컴포넌트 구현

Idle 상태 컴포넌트

import type { ReactNode } from 'react';
import { useDropzoneContext } from '../context';
import { statusBaseClasses } from '../styles';
import Icon from '../../Icon';

type IdleProps = {
  icon?: string;
  mainMessage: ReactNode;
  supportMessage?: ReactNode;
  children?: ReactNode;
};

const Idle = ({
  mainMessage,
  supportMessage,
  icon = 'Upload',
  children,
}: IdleProps) => {
  const { status } = useDropzoneContext();

  // idle 상태일 때만 렌더링
  if (status !== 'idle') return null;

  const { container, mainText, supportText } = statusBaseClasses({
    status: 'idle',
  });
  const IconComponent = Icon[icon as keyof typeof Icon];

  return (
    <div className={container}>
      {children || (
        <>
          <IconComponent className="dropzone-icon" />
          <span className={mainText}>{mainMessage}</span>
          {supportMessage && (
            <span className={supportText}>{supportMessage}</span>
          )}
        </>
      )}
    </div>
  );
};

export default Idle;

Accept 상태 컴포넌트

import type { ReactNode } from 'react';
import { useDropzoneContext } from '../context';
import { statusBaseClasses } from '../styles';
import Icon from '../../Icon';

type AcceptProps = {
  mainMessage: ReactNode;
  children?: ReactNode;
};

const Accept = ({ mainMessage, children }: AcceptProps) => {
  const { status } = useDropzoneContext();

  // accept 상태일 때만 렌더링
  if (status !== 'accept') return null;

  const { container, mainText } = statusBaseClasses({ status: 'accept' });

  return (
    <div className={container}>
      {children || (
        <>
          <Icon.CircleCheckFill className="dropzone-icon" />
          <span className={mainText}>{mainMessage}</span>
        </>
      )}
    </div>
  );
};

export default Accept;

Reject 상태 컴포넌트

import type { ReactNode } from 'react';
import { useDropzoneContext } from '../context';
import { statusBaseClasses } from '../styles';
import Icon from '../../Icon';

type RejectProps = {
  mainMessage: ReactNode;
  supportMessage?: ReactNode;
  children?: ReactNode;
};

const Reject = ({ mainMessage, supportMessage, children }: RejectProps) => {
  const { status, error } = useDropzoneContext();

  // reject 상태일 때만 렌더링
  if (status !== 'reject') return null;

  const { container, mainText, supportText } = statusBaseClasses({
    status: 'reject',
  });

  return (
    <div className={container}>
      {children || (
        <>
          <Icon.CircleWarningFill className="dropzone-icon" />
          <span className={mainText}>{error || mainMessage}</span>
          {supportMessage && (
            <span className={supportText}>{supportMessage}</span>
          )}
        </>
      )}
    </div>
  );
};

export default Reject;

Loading 상태 컴포넌트

import type { ReactNode } from 'react';
import { useDropzoneContext } from '../context';
import { statusBaseClasses } from '../styles';
import Loader from '../../Loader';

type LoadingProps = {
  mainMessage: ReactNode;
  supportMessage?: ReactNode;
  children?: ReactNode;
};

const Loading = ({ mainMessage, supportMessage, children }: LoadingProps) => {
  const { status } = useDropzoneContext();

  // loading 상태일 때만 렌더링
  if (status !== 'loading') return null;

  const { container, mainText, supportText } = statusBaseClasses({
    status: 'loading',
  });

  return (
    <div className={container}>
      {children || (
        <>
          <Loader />
          <span className={mainText}>{mainMessage}</span>
          {supportMessage && (
            <span className={supportText}>{supportMessage}</span>
          )}
        </>
      )}
    </div>
  );
};

export default Loading;

Context API + 컴파운드 컴포넌트의 핵심 패턴

여기서 가장 중요한 패턴은 각 컴포넌트가 Context를 구독해서 자신이 렌더링될 조건을 스스로 판단한다는 것입니다.

// 🎯 핵심 패턴: 조건부 렌더링의 분산
const Idle = ({ mainMessage, supportMessage }: IdleProps) => {
  const { status } = useDropzoneContext(); // Context 구독

  if (status !== 'idle') return null; // 자체 조건 판단

  return <div>{/* Idle UI */}</div>;
};

const Accept = ({ mainMessage }: AcceptProps) => {
  const { status } = useDropzoneContext(); // Context 구독

  if (status !== 'accept') return null; // 자체 조건 판단

  return <div>{/* Accept UI */}</div>;
};

이 패턴의 혁신적인 점

1️⃣ 중앙 집중식 상태, 분산형 렌더링

// ❌ 기존 방식: 중앙에서 모든 조건 처리
const BadDropzone = () => {
  const [status, setStatus] = useState('idle');

  const renderContent = () => {
    if (status === 'idle') return <IdleUI />;
    if (status === 'accept') return <AcceptUI />;
    if (status === 'reject') return <RejectUI />;
    if (status === 'loading') return <LoadingUI />;
  };

  return <div>{renderContent()}</div>; // 모든 판단을 여기서!
};

// ✅ 새로운 방식: 각자가 자신의 조건 판단
const GoodDropzone = ({ children }) => {
  return (
    <DropzoneProvider>
      <div>{children}</div>
      {/* 조건 판단은 각 컴포넌트가! */}
    </DropzoneProvider>
  );
};

2️⃣ 선언적 API로 의도 명확화

// 사용하는 쪽에서 보면 각 상태가 무엇을 하는지 명확
<Dropzone onDrop={handleDrop}>
  <Dropzone.Idle mainMessage="파일을 드래그하세요" supportMessage="최대 10MB" />
  <Dropzone.Accept mainMessage="파일을 놓으세요" />
  <Dropzone.Reject mainMessage="잘못된 파일입니다" />
  <Dropzone.Loading mainMessage="업로드 중..." />
</Dropzone>

이런 방식의 핵심 장점:

1. 상태 추가 용이성: 새 상태 컴포넌트만 추가하면 됨
2. 독립적 테스트: 각 상태별 컴포넌트를 독립적으로 테스트
3. 코드 분할: 각 상태의 로직이 완전히 분리됨
4. 타입 안전성: 각 상태별로 다른 props 타입 적용 가능
5. 재사용성: 특정 상태만 필요한 곳에서 선택적 사용

3부: Panda CSS와 타입 안전성

Panda CSS를 활용한 스타일 시스템

import { sva } from '@styles/css';

export const dropzoneContainer = sva({
  slots: ['container'],
  base: {
    container: {
      position: 'relative',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      border: '2px dashed {colors.border.normal}',
      rounded: 'md',
      minHeight: 200,
      cursor: 'pointer',
      bg: 'bg.surface',
      transition: 'all 0.2s ease',

      '&:hover': {
        borderColor: 'border.hover',
        bg: 'bg.hover',
      },
    },
  },
  variants: {
    status: {
      idle: {
        container: {
          borderColor: 'border.normal',
          bg: 'bg.surface',
        },
      },
      accept: {
        container: {
          borderColor: 'status.success',
          bg: 'success.light',
          '--icon-color': '{colors.status.success}',
        },
      },
      reject: {
        container: {
          borderColor: 'status.error',
          bg: 'error.light',
          '--icon-color': '{colors.status.error}',
        },
      },
      loading: {
        container: {
          borderColor: 'primary.500',
          bg: 'primary.light',
          '--icon-color': '{colors.primary.500}',
        },
      },
    },
    error: {
      true: {
        container: {
          borderColor: 'status.error',
          bg: 'error.light',
        },
      },
    },
  },
  defaultVariants: {
    status: 'idle',
    error: false,
  },
});

export const statusBaseClasses = sva({
  slots: ['container', 'mainText', 'supportText'],
  base: {
    container: {
      display: 'flex',
      flexDirection: 'column',
      alignItems: 'center',
      justifyContent: 'center',
      textAlign: 'center',
      gap: 2,

      '& .dropzone-icon': {
        width: 12,
        height: 12,
        fill: 'var(--icon-color, {colors.text.secondary})',
        mb: 3,
      },
    },
    mainText: {
      fontSize: 'lg',
      fontWeight: 'semibold',
      color: 'text.primary',
    },
    supportText: {
      fontSize: 'sm',
      color: 'text.secondary',
      mt: 1,
    },
  },
  variants: {
    status: {
      idle: {
        container: { color: 'text.secondary' },
      },
      accept: {
        container: { color: 'status.success' },
        mainText: { color: 'status.success' },
      },
      reject: {
        container: { color: 'status.error' },
        mainText: { color: 'status.error' },
      },
      loading: {
        container: { color: 'primary.500' },
        mainText: { color: 'primary.500' },
      },
    },
  },
});

타입 안전성 보장

export type BaseProps = {
  mainMessage: ReactNode;
  supportMessage?: ReactNode;
};

// 각 상태별 컴포넌트는 필요한 props만 받도록 제한
type IdleProps = BaseProps & {
  icon: SvgNames; // 아이콘 타입도 제한
  children?: ReactNode;
  status?: 'idle' | 'reject';
};

type AcceptProps = Omit<BaseProps, 'supportMessage'>; // supportMessage 불필요

type RejectProps = BaseProps; // 모든 메시지 필요

실제 사용법

const FileUploadPage = () => {
  const [uploadedFiles, setUploadedFiles] = useState<File[]>([]);

  const handleDrop = async (files: File[]) => {
    console.log('업로드할 파일:', files);

    // 파일 업로드 로직
    try {
      await uploadFiles(files);
      setUploadedFiles(files);
    } catch (error) {
      console.error('업로드 실패:', error);
    }
  };

  return (
    <div className="upload-container">
      <Dropzone
        onDrop={handleDrop}
        accept={['image/*', 'application/pdf']}
        maxSize={10 * 1024 * 1024} // 10MB
        className="custom-dropzone"
      >
        <Dropzone.Idle
          icon="Upload"
          mainMessage="파일을 드래그하거나 클릭하세요"
          supportMessage="최대 10MB, JPG, PNG, PDF 지원"
        />
        <Dropzone.Accept mainMessage="파일을 놓으세요!" />
        <Dropzone.Reject
          mainMessage="지원하지 않는 파일입니다"
          supportMessage="JPG, PNG, PDF만 업로드 가능합니다"
        />
        <Dropzone.Loading
          mainMessage="파일 업로드 중..."
          supportMessage="잠시만 기다려주세요"
        />
      </Dropzone>

      {uploadedFiles.length > 0 && (
        <div className="uploaded-files">
          <h3>업로드된 파일</h3>
          {uploadedFiles.map(file => (
            <div key={file.name}>{file.name}</div>
          ))}
        </div>
      )}
    </div>
  );
};

Context 기반 고급 활용

const AdvancedFileUpload = () => {
  const handleDrop = async (files: File[]) => {
    // Context의 setStatus를 이용해서 수동 상태 제어도 가능
    try {
      await processFiles(files);
    } catch (error) {
      // 에러 발생 시 reject 상태로 수동 변경
    }
  };

  return (
    <Dropzone onDrop={handleDrop}>
      {/* 커스텀 UI도 Context 상태를 활용 가능 */}
      <CustomDropzoneStatus />

      <Dropzone.Idle mainMessage="기본 상태" />
      <Dropzone.Accept mainMessage="받을 준비 완료" />
      <Dropzone.Reject mainMessage="거부" />
      <Dropzone.Loading mainMessage="처리 중" />
    </Dropzone>
  );
};

// Context를 활용한 커스텀 컴포넌트
const CustomDropzoneStatus = () => {
  const { status, files, error } = useDropzoneContext();

  return (
    <div className="custom-status">
      현재 상태: {status}
      {files.length > 0 && <span>파일 개수: {files.length}</span>}
      {error && <span className="error">{error}</span>}
    </div>
  );
};

실무에서의 Context API 활용의 핵심

const FileUploadWithProgress = () => {
  return (
    <Dropzone onDrop={handleUpload}>
      {/* 여러 컴포넌트가 동일한 상태를 공유 */}
      <UploadProgressBar /> {/* Context에서 files 정보 구독 */}
      <FilePreviewList /> {/* Context에서 files 정보 구독 */}
      <DropzoneStatusDisplay /> {/* Context에서 status 정보 구독 */}
      {/* 기본 상태 컴포넌트들 */}
      <Dropzone.Idle mainMessage="파일 드래그" />
      <Dropzone.Accept mainMessage="놓으세요" />
      <Dropzone.Reject mainMessage="잘못된 파일" />
      <Dropzone.Loading mainMessage="업로드 중" />
    </Dropzone>
  );
};

// 모든 컴포넌트가 Context를 통해 동일한 상태에 접근
const UploadProgressBar = () => {
  const { files, status } = useDropzoneContext();

  if (status !== 'loading' || files.length === 0) return null;

  return (
    <div className="progress-bar">
      업로드 중: {files.map(f => f.name).join(', ')}
    </div>
  );
};

const FilePreviewList = () => {
  const { files } = useDropzoneContext();

  return (
    <div className="file-preview">
      {files.map(file => (
        <FilePreview key={file.name} file={file} />
      ))}
    </div>
  );
};

정리하며

Keep

• Context API 활용: 상태를 중앙 집중식으로 관리하면서 컴포넌트 간 공유
• 관심사 분리: 각 상태별 UI 로직이 독립적인 컴포넌트로 완벽 분리
• 조건부 렌더링 분산: 각 컴포넌트가 자신의 표시 조건을 스스로 판단
• 확장성: 새로운 상태 추가 시 새 컴포넌트만 만들면 됨
• 타입 안전성: TypeScript로 각 상태에 맞는 props와 Context 타입 강제
• 재사용성: Context 기반으로 어떤 조합이든 자유롭게 구성 가능

Problem

• 학습 곡선: Context API + 컴파운드 컴포넌트 패턴을 팀원들이 이해해야 함
• 초기 설계 비용: 단순한 DropZone에 비해 초기 구축 시간이 더 필요
• Context Provider 필수: 반드시 Provider로 감싸야 하는 구조적 제약
• 성능 고려사항: Context 값 변경 시 모든 구독 컴포넌트 리렌더링

Try

• Context 최적화: useMemo, useCallback을 활용한 불필요한 리렌더링 방지
• Progress Context 추가: 업로드 진행률을 별도 Context로 분리하여 성능 최적화
• 애니메이션 통합: 상태 전환 시 자연스러운 애니메이션 효과
• 테스트 전략: Context Provider를 활용한 독립적인 단위 테스트
• DevTools 연동: React DevTools에서 Context 상태 추적 개선

실무에서의 Context API + 컴파운드 컴포넌트 위력

[기획자]: "이제 드래그 상태에서 파일 개수도 보여주면 안 될까요? 그리고 업로드 진행률도..."

[나]: (예전 같으면 벙쪘을 상황) "네! Context에 files 정보가 있으니까 FileCountDisplay 컴포넌트만 추가하면 됩니다!"

[기획자]: "오, 그럼 기존 상태들은 영향 없나요?"

[나]: "전혀 없어요. Context를 구독하는 새 컴포넌트만 추가하면 끝이에요!"

// 기획 변경 대응: 단순히 컴포넌트 하나만 추가
<Dropzone onDrop={handleDrop}>
  <FileCountDisplay /> {/* 새로 추가! */}
  <UploadProgressBar /> {/* 새로 추가! */}
  <Dropzone.Idle mainMessage="드래그하세요" />
  <Dropzone.Accept mainMessage="놓으세요" />
  <Dropzone.Reject mainMessage="잘못된 파일" />
  <Dropzone.Loading mainMessage="업로드 중" />
</Dropzone>;

// 새 컴포넌트는 Context만 구독하면 끝
const FileCountDisplay = () => {
  const { files } = useDropzoneContext();
  return files.length > 0 ? <span>파일 {files.length}개</span> : null;
};

Context API + 컴파운드 컴포넌트 패턴의 진정한 가치

이건 단순히 코드 분리 문제가 아닙니다. 이 패턴의 핵심은:

1. 상태 공유의 투명성

• 모든 컴포넌트가 동일한 상태를 실시간으로 공유
• Props drilling 없이 깊은 계층의 컴포넌트도 상태 접근 가능
• 상태 변경 시 관련된 모든 UI가 자동으로 동기화

2. 조합형 개발 방식

• 레고 블록처럼 필요한 컴포넌트만 조합해서 사용
• 새로운 요구사항 = 새로운 컴포넌트 추가
• 기존 컴포넌트 수정 없이 기능 확장

이제 복잡한 상태 관리가 필요한 모든 컴포넌트에 이 패턴을 적용할 수 있습니다!

Context API의 상태 공유 능력과 컴파운드 컴포넌트의 조합형 개발 방식을 결합하면, 확장 가능하고 유지보수하기 쉬운 컴포넌트 시스템을 구축할 수 있거든요.

특히 파일 업로드처럼 복잡한 상태 변화와 다양한 UI 조합이 필요한 경우에는 이런 접근법이 정말 빛을 발합니다!