개인 블로그를 직접 만들기로 하고 MDX 처리 도구를 찾았습니다. 검색하면 나오는 답은 거의 하나였습니다. 당시 Next.js로 블로그를 만드는 글의 대부분이 그 라이브러리를 쓰고 있었고, 별 고민 없이 그걸로 정할 뻔했습니다.
그런데 설치하기 전에 저장소를 열어 봤다가 이상한 걸 발견했습니다. 마지막 커밋이 오래전이었고, 이슈에 답이 달리지 않고 있었습니다. 최신 Next.js와의 호환 문제를 묻는 이슈가 여러 개 열려 있었는데 전부 조용했습니다.
지금 동작한다는 것과 1년 뒤에도 동작한다는 것
지금 설치하면 문제없이 돌아갈 것입니다. 그건 확실했습니다. 문제는 그다음이었습니다. Next.js는 자주 올라갑니다. 그때마다 이 라이브러리가 따라오지 못하면 나는 두 가지 중 하나를 골라야 합니다. 프레임워크 버전을 올리지 않거나, 콘텐츠 파이프라인을 통째로 갈아엎거나.
개인 블로그라서 다행이지 실무 프로젝트였다면 더 심각했을 것입니다. 그래서 대안을 찾기로 했고, Velite라는 도구를 발견했습니다. 당시에는 자료가 거의 없었습니다. 한국어 글은 물론이고 영어 자료도 공식 문서 정도였습니다.
그래도 이쪽을 택했습니다. 문서를 읽어 보니 필요한 것은 다 있었고, 무엇보다 저장소가 살아 있었습니다. 결과적으로 이후 Next.js 버전을 여러 번 올리는 동안 콘텐츠 파이프라인 때문에 막힌 적이 한 번도 없었습니다.
많이 쓰인다는 것은 과거의 지표이고, 지금도 관리되고 있다는 것은 미래의 지표입니다.
지금 쓰는 체크리스트
이 경험 이후로 라이브러리를 도입할 때 보는 순서가 생겼습니다. 위에서부터 봅니다.
1. 살아 있는가
- 최근 커밋이 언제인가. 몇 달 단위로 조용하면 신호입니다.
- 이슈에 메인테이너가 답하고 있는가. 이슈 수 자체보다 응답 여부가 중요합니다.
- 메인테이너가 한 명뿐인가. 그 한 사람이 바빠지면 프로젝트가 멈춥니다.
- 의존하는 프레임워크의 최신 메이저를 지원하는가. 지원 이슈가 몇 달째 열려 있으면 위험합니다.
2. 걷어낼 수 있는가
더 중요한 질문일 수도 있습니다. 이 라이브러리가 문제가 됐을 때, 얼마나 빨리 다른 것으로 바꿀 수 있는가?
| 침투 정도 | 예 | 교체 비용 |
|---|---|---|
| 경계에만 있음 | 날짜 포맷, HTTP 클라이언트 | 낮음 — 래퍼 하나만 고치면 된다 |
| 일부 화면에 있음 | 차트, 캘린더, 에디터 | 중간 — 해당 화면만 다시 만든다 |
| 전체 구조를 정함 | 상태 관리, 라우터, 빌드 파이프라인 | 높음 — 사실상 재작성 |
아래로 갈수록 신중하게 고릅니다. 날짜 라이브러리는 마음에 안 들면 갈면 그만이지만, 콘텐츠 파이프라인이나 상태 관리는 프로젝트 구조를 결정합니다. 위험도가 다르면 검토의 깊이도 달라야 합니다.
3. 이것 없이 얼마나 걸리는가
직접 만들면 하루가 걸리는 것을 위해 의존성을 추가할 필요는 없습니다. 반대로 직접 만들면 두 달이 걸리고 그마저도 엣지 케이스에서 틀릴 것이 뻔한 영역 — 날짜 계산, 국제화, 접근성 처리된 컴포넌트 — 은 검증된 것을 쓰는 게 맞습니다.
판단이 애매할 때 나는 이렇게 묻습니다. 이 문제의 엣지 케이스를 내가 다 알고 있는가? 안다면 직접 만들어도 됩니다. 모른다면 이미 그 엣지 케이스들을 만나 본 사람들의 코드를 쓰는 게 낫습니다.
4. 번들에 얼마나 들어오는가
클라이언트로 내려가는 라이브러리라면 크기를 확인합니다. 트리 셰이킹이 되는지, 서브 경로 임포트를 지원하는지도 같이 봅니다. 서버에서만 도는 것이라면 이 항목은 거의 무시해도 됩니다.
인기가 함정이 되는 경우
'많이 쓰니까 안전하다'는 판단은 대체로 맞지만 항상 맞지는 않습니다. 인기는 관성이 있어서, 유지보수가 멈춘 뒤에도 한동안 계속 추천됩니다. 블로그 글과 튜토리얼은 업데이트되지 않고 그대로 남아 있기 때문입니다.
내가 그 라이브러리를 후보에 올린 이유도 검색 결과였습니다. 검색은 '작년에 사람들이 무엇을 썼는지'를 알려 주지, '지금 무엇을 써야 하는지'를 알려 주지 않습니다. 그래서 설치 전에 저장소를 직접 열어 보는 습관이 생겼습니다. 5분이면 됩니다.
자료가 적은 것을 고를 때
Velite를 택할 때 가장 걸렸던 건 자료가 없다는 점이었습니다. 막히면 물어볼 곳이 없다는 뜻이니까. 실제로 몇 번 막혔고, 그때마다 공식 문서와 소스 코드를 직접 읽어야 했습니다.
그런데 지나고 보니 그게 나쁘지 않았습니다. 블로그 글을 따라 하는 것보다 소스를 읽으며 이해한 것이 더 오래 남았습니다. 자료가 적다는 것은 진입 비용이지 결격 사유가 아닙니다. 대신 그 비용을 감당할 수 있는 규모의 프로젝트인지는 따져야 합니다. 마감이 촉박한 실무 프로젝트에서 자료 없는 도구를 처음 쓰는 것은 다른 이야기입니다.
정리
- 설치 전에 저장소를 5분 열어 봅니다. 최근 커밋과 이슈 응답만 봐도 많은 걸 알 수 있습니다.
- '많이 쓴다'는 과거 지표입니다. '지금 관리되고 있다'가 미래 지표입니다.
- 교체 비용이 큰 영역일수록 깊이 검토합니다. 위험도에 따라 검토의 깊이를 다르게 둡니다.
- 여러 곳에서 쓰이고 교체 가능성이 있는 것은 얇게 감싸 둡니다.
- 엣지 케이스를 내가 다 아는 문제만 직접 만듭니다.
- 자료가 적은 것은 진입 비용의 문제이지 결격 사유가 아닙니다. 다만 프로젝트 상황을 봐야 합니다.