[Javascript] 시나브로 자바스크립트 5주차 이모저모 - npm 라이브러리 개발과 배포

2025년 3월 14일

#Javascript#Inflearn#Sinabro#Npm#Package#Package.json#Node#Nodejs#Yarn#Yarn.lock#

#NPM 라이브러리 개발과 배포

npm 라이브러리를 개발하고 배포하는 과정에 대한 이론적 내용을 정리해보았다. 라이브러리 개발에 필요한 핵심 개념과 고려사항을 알아보자.

#1. 모듈 시스템 고려하기

라이브러리를 배포할 때는 두 가지 주요 환경을 고려해야 한다:

  • CommonJS (CJS): Node.js의 전통적인 모듈 시스템으로, require()를 사용한다.
  • ES Modules (ESM): 모던 JavaScript의 표준 모듈 시스템으로, import/export 구문을 사용한다.

라이브러리의 모듈 시스템 지원 전략에는 몇 가지 접근법이 있다:

#1.1 듀얼 지원 접근법

{
  // ...
  "main": "./dist/library.umd.cjs", // CommonJS 환경용
  "module": "./dist/library.js", // ESM 환경용
  "exports": {
    ".": {
      "import": "./dist/library.js", // ESM 임포트용
      "require": "./dist/library.umd.cjs" // CJS 임포트용
    }
  }
  // ...
}

#1.2 ESM 우선 접근법

최근 트렌드는 ESM을 우선 지원하는 것이다. 트리쉐이킹과 같은 최적화는 ESM에서만 제대로 작동하기 때문이다. type: "module" 속성을 추가하면 해당 패키지가 기본적으로 ES Modules를 사용함을 명시한다.

#1.3 전략 선택

  • 범용 라이브러리: 두 환경 모두 지원하는 것이 좋다
  • UI 컴포넌트/번들 크기가 중요한 라이브러리: ESM 우선 또는 ESM 전용이 유리하다
  • Node.js 백엔드 도구: CommonJS 지원이 여전히 중요하다

#2. 타입 정의와 TypeScript

라이브러리 개발 시 타입 정의는 매우 중요하다. 두 가지 접근 방식이 있다:

  1. JavaScript로 개발 + 별도의 타입 정의:

    • .js 파일과 함께 .d.ts 파일을 수동으로 작성한다
    • 복잡한 타입의 경우 유지보수가 어려울 수 있다

  2. TypeScript로 개발 + 컴파일:

    • TypeScript로 개발하고 JavaScript + 타입 정의로 컴파일한다
    • 빌드 과정에서 자동으로 타입 정의 파일이 생성된다
    • 타입 안정성이 높고 유지보수가 용이하다

#3. 빌드 도구 선택

라이브러리 빌드를 위한 다양한 도구가 있다:

  • tsdx: TypeScript 라이브러리 개발을 위한 제로 설정 CLI이다
  • Vite: 모던 빌드 도구로, 빠른 개발 환경과 최적화된 빌드를 제공한다
  • Rollup: 라이브러리 번들링에 최적화된 도구이다
  • tsup: esbuild 기반의 TypeScript 라이브러리 번들러이다

각 도구는 장단점이 있으며, 프로젝트 요구사항에 맞게 선택하는 것이 중요하다.

#4. 모노레포 구조

모노레포는 여러 패키지를 하나의 저장소에서 관리하는 방식이다. 라이브러리 개발에 특히 유용한 이유는:

  • 라이브러리와 예제/데모 애플리케이션을 함께 관리할 수 있다
  • 로컬에서 라이브러리 변경사항을 즉시 테스트할 수 있다
  • npm에 배포하지 않고도 내부 패키지 간 의존성 관리가 가능하다

Yarn Workspaces나 npm Workspaces, 또는 Nx, Turborepo 같은 도구를 사용하여 구성할 수 있다.

#5. 테스트 환경 구축

라이브러리 품질 보장을 위한 테스트는 필수적이다:

  • 단위 테스트: 각 기능의 정상 작동을 확인한다
  • 통합 테스트: 여러 기능의 상호작용을 확인한다
  • JSDOM: 브라우저 환경을 시뮬레이션하여 DOM 관련 테스트가 가능하다

Jest, Vitest, Mocha 등의 테스트 프레임워크를 사용할 수 있다.

#6. 문서화

라이브러리 사용자를 위한 문서는 매우 중요하다:

  • README.md: 기본 사용법과 설치 방법을 안내한다
  • API 문서: 모든 공개 API에 대한 상세 설명을 제공한다
  • 예제: 일반적인 사용 사례에 대한 코드 예제를 제공한다

더 복잡한 문서화가 필요한 경우 전용 도구를 사용할 수 있다:

  • VitePress: Vue 기반의 정적 사이트 생성기이다
  • Docusaurus: React 기반의 문서 사이트 생성기이다
  • Nextra: Next.js 기반의 문서화 도구이다

모노레포 구조에서는 이러한 문서 사이트를 별도의 패키지로 관리할 수 있다.

#7. 구현 방식 선택: 클래스 vs 함수

라이브러리 설계 시 구현 방식 선택은 중요하다:

  • 클래스 기반:

    • 상태와 메서드를 캡슐화하기 좋다
    • 객체지향 패러다임에 익숙한 개발자에게 친숙하다
    • 상속과 다형성 활용이 가능하다

  • 함수 기반:

    • 더 가볍고 간결한 API를 제공한다
    • 함수형 프로그래밍 패러다임과 잘 어울린다
    • 트리쉐이킹에 더 유리할 수 있다

#8. 트리쉐이킹 고려

트리쉐이킹은 사용하지 않는 코드를 제거하여 번들 크기를 줄이는 기술이다:

  • ESM 사용: 트리쉐이킹은 ES Modules에서만 제대로 작동한다
  • 개별 함수 내보내기: 큰 객체 대신 개별 함수를 내보내는 방식을 사용한다

#8.1 sideEffects 설정의 중요성

package.json에 "sideEffects": false 설정은 웹팩(Webpack)이나 다른 번들러의 트리쉐이킹 기능을 최적화하는 중요한 옵션이다:

{
  "name": "my-library",
  "version": "1.0.0",
  "sideEffects": false
}

이 설정이 의미하는 바는:

  1. 사이드 이펙트 없음 선언: 이 패키지의 모든 파일이 사이드 이펙트가 없다고 선언한다. 여기서 '사이드 이펙트'란 모듈이 로드될 때 전역 상태를 변경하거나, 외부에 영향을 주는 코드를 의미한다.

  2. 트리쉐이킹 최적화: 번들러에게 "이 패키지의 어떤 파일도 단순히 임포트하는 것만으로는 애플리케이션에 영향을 주지 않으니, 실제로 사용되는 코드만 번들에 포함시켜도 된다"고 알린다.

  3. 예시로 이해하기:

    // 만약 이 패키지에서
import { button } from "ui-library";

// button만 사용한다면, "sideEffects": false 설정이 있을 때
// modal, dropdown 등 다른 컴포넌트 코드는 최종 번들에 포함되지 않는다

주의해야 할 점:

  • 패키지가 실제로 사이드 이펙트가 있는데 "sideEffects": false로 설정하면 문제가 발생할 수 있다. 특히 다음과 같은 경우 조심해야 한다:

    • 전역 CSS 파일을 임포트하는 경우
    • 전역 객체를 수정하는 경우 (예: window.X = Y)
    • 폴리필을 적용하는 경우

  • 특정 파일만 사이드 이펙트가 있다면 다음과 같이 설정할 수 있다:

    "sideEffects": [
  "*.css",
  "./src/polyfills.js"
]

#8.2 트리쉐이킹에 유리한 코드 구조

단순 함수를 리턴하는 모듈은 모든 메서드가 한꺼번에 불러와지므로, 메서드가 많을 경우 트리쉐이킹이 제대로 동작하지 않을 수 있다. 따라서 다음과 같은 방식을 고려할 수 있다:

// 트리쉐이킹에 불리한 방식
export const utils = {
  method1,
  method2,
  method3,
};

// 트리쉐이킹에 유리한 방식
export const method1 = () => {
  /* 구현 */
};
export const method2 = () => {
  /* 구현 */
};
export const method3 = () => {
  /* 구현 */
};

#9. 패키지 배포 준비

npm에 패키지를 배포하기 전에 확인해야 할 사항들:

  • package.json 설정: 이름, 버전, 설명, 키워드, 라이센스 등을 정의한다
  • 파일 선택: files 필드를 통해 배포할 파일을 지정한다
  • gitignore/npmignore: 불필요한 파일을 제외한다
  • README/LICENSE: 기본 문서화와 라이센스 정보를 제공한다
  • 버전 관리: Semantic Versioning(SemVer)을 준수한다

#10. 최근 트렌드

npm 라이브러리 개발의 최근 트렌드는:

  • ESM 우선: CommonJS만 지원하던 패키지들이 ESM을 우선 지원하는 추세이다
  • TypeScript 채택 증가: 타입 안정성과 개발자 경험 향상을 위해 사용한다
  • 번들 크기 최적화: 트리쉐이킹과 코드 분할을 통한 최적화를 중요시한다
  • 모노레포 활용: 복잡한 라이브러리 생태계 관리를 위해 도입한다

일부 패키지는 트리쉐이킹의 이점을 극대화하기 위해 ESM만 제공하는 경우도 있다. 이는 번들 크기 최적화가 호환성보다 중요한 프론트엔드 라이브러리에서 특히 두드러진다.

#결론

npm 라이브러리 개발은 단순히 코드 작성 이상의 것을 요구한다. 모듈 시스템, 타입 정의, 빌드 도구, 테스트, 문서화, 패키지 설정 등 다양한 측면을 고려해야 한다.

특히 모듈 시스템과 트리쉐이킹 간의 균형을 찾는 것이 중요하다. 라이브러리의 용도와 타겟 사용자에 따라 듀얼 지원 전략이나 ESM 우선 전략 중 적절한 것을 선택해야 한다. 어떤 선택이든 그 결정과 이유를 문서에 명확히 기술하는 것이 사용자에게 도움이 된다.

이러한 이론적 기반을 잘 이해하면 더 품질 높은 라이브러리를 개발하고 배포할 수 있다.