《npm Deep Dive》를 읽고 정리한 라이브러리 설계의 기준

라이브러리는 동작하는 코드가 아니라, 다른 개발자가 믿고 설치할 수 있는 약속에 가깝습니다.

들어가며

라이브러리를 만들어보고 싶다는 생각은 오래전부터 가지고 있었습니다. React 컴포넌트를 작성하는 일에 익숙해지면서, 자연스럽게 이를 패키지로 배포해볼 수 있겠다는 생각도 들었습니다.

실제로 몇 차례는 npm에 배포까지 해보았습니다. 다만 그 패키지들은 실제 프로젝트에 계속 적용하기 어려웠습니다. 기능은 동작했지만, 스스로 보아도 구조가 안정적이라는 확신이 없었기 때문입니다.

당시에는 이 실패를 구현력 부족이라고만 생각했습니다. 그런데 지금 돌아보면 문제는 다른 데 있었습니다. 무엇을 만들고 싶은지는 있었지만, 어떤 기준으로 라이브러리를 설계해야 하는지는 알지 못한 상태였습니다.

이 글은 책 내용을 요약하려는 글은 아닙니다. 《npm Deep Dive》를 읽고 나서, 왜 이전 시도가 불안정했는지와 앞으로 무엇을 먼저 판단해야 하는지를 정리한 회고에 가깝습니다.

문제는 구현이 아니라 기준의 부재였습니다

이전의 시도를 떠올려보면 항상 비슷한 지점에서 멈췄습니다. 코드는 일단 동작했지만, 구조가 조금만 복잡해져도 손대기 어려워졌고 실제 사용 환경을 상정한 판단도 부족했습니다.

특히 다음 세 가지가 반복적으로 비어 있었습니다.

• 어떤 환경에서 이 패키지가 사용될 것인지 구체적으로 가정하지 않았습니다.
• 어디까지를 공개 API로 두고, 어디부터를 내부 구현으로 숨길지 정리하지 못했습니다.
• 지금의 편의보다 이후의 유지보수를 우선하는 판단을 하지 못했습니다.

결국 문제는 실패 그 자체가 아니었습니다. 왜 실패했는지를 설명할 수 없었다는 점이 더 큰 문제였습니다.

돌이켜보면, 동작하는 코드와 배포 가능한 라이브러리는 고민의 결이 다릅니다. 당시의 저는 이 차이를 분명하게 인식하지 못했습니다.

《npm Deep Dive》를 읽고 바뀐 질문

이 책을 읽으며 가장 크게 달라진 점은, 라이브러리를 만들기 전에 먼저 던져야 할 질문이 생겼다는 점입니다. 책은 특정 도구의 사용법만 나열하지 않고, 왜 지금의 npm 생태계가 이런 구조를 갖게 되었는지를 설명합니다. 그 과정에서 라이브러리를 바라보는 기준도 함께 정리되었습니다.

어떤 환경을 먼저 상정할 것인가

브라우저에서만 쓸 것인지, Node.js 환경도 지원할 것인지, 번들러와 런타임 제약은 무엇인지부터 먼저 가정해야 한다는 점이 분명해졌습니다. 예전에는 구현을 시작한 뒤에 이런 조건을 뒤늦게 맞추려 했고, 그 과정에서 구조가 흔들렸습니다.

어디까지를 책임질 것인가

이제는 기능을 더 넣는 일보다 경계를 정하는 일이 더 중요하다고 생각하게 되었습니다. 사용자가 믿고 써야 하는 표면은 단순해야 하고, 내부 구현은 바뀌더라도 외부 약속은 쉽게 흔들리지 않아야 합니다.

이 구조를 내가 계속 운영할 수 있는가

배포는 시작일 뿐입니다. 이후에는 버전 관리, 문서, 예제, 변경에 대한 책임이 따라옵니다. 이 구조를 내가 계속 관리할 수 있는지까지 포함해서 설계해야 한다는 점을 이전보다 더 분명하게 보게 되었습니다.

그래서 이전 실패가 다르게 보이기 시작했습니다

이 책을 읽고 나니 과거의 실패가 단순한 시행착오로 보이지 않았습니다. 왜 구조가 불안정했는지, 왜 사용을 전제로 한 설계가 되지 않았는지, 왜 스스로도 코드에 확신을 갖지 못했는지가 하나의 맥락으로 이어졌습니다.

결국 라이브러리는 코드 묶음이 아니라 사용자와의 약속 위에 놓인 결과물에 가깝습니다. 이 관점을 얻고 나서야, 예전에는 구현만 있었지 설계는 없었다는 사실을 분명하게 설명할 수 있게 되었습니다.

아직 남아 있는 과제

물론 이 책 한 권으로 라이브러리 개발에 대한 모든 답을 얻은 것은 아닙니다. 실제로는 테스트 전략, 배포 흐름, 버전 정책, 문서화처럼 더 많은 실무적인 판단이 필요합니다. npm 생태계는 여전히 복잡하고, 프로덕션에서 오래 살아남는 패키지는 훨씬 더 많은 검증을 거칩니다.

다만 지금은 적어도 다음 시도에서 무엇을 먼저 점검해야 하는지는 알고 있습니다.

• 사용 환경과 지원 범위를 먼저 고정할 것
• 공개 API와 내부 구현의 경계를 분명하게 나눌 것
• 유지보수 가능한 구조인지 배포 전에 스스로 설명할 수 있을 것

마치며

이전에는 라이브러리를 만들고 싶다는 마음이 먼저였습니다. 지금은 그보다 앞서, 어떤 기준으로 만들 것인지부터 정리해야 한다고 생각합니다.

이번 독서는 저를 완성된 상태로 옮겨놓지는 않았습니다. 다만 적어도 이제는 실패의 이유를 설명할 수 있고, 다음 시도에서 무엇을 먼저 판단해야 하는지도 알고 있습니다. 그 차이는 생각보다 큽니다.