Node.js 모듈 시스템과 NPM 패키지 관리 핵심 개념

모듈화의 기본 원리

모듈화란 무엇인가?

복잡한 소프트웨어를 설계할 때 시스템을 하위 단위로 나누는 과정을 모듈화라고 합니다. 프로그래밍 관점에서는 거대한 단일 파일을 독립적이면서도 서로 의존성을 가지는 작은 단위의 파일로 분리하는 작업을 의미하며, 이를 통해 코드의 재사용성과 유지보수성을 크게 향상시킬 수 있습니다.

주요 모듈화 규격

모듈을 불러오고 외부로 내보낼 때 사용하는 문법적 약속을 모듈화 규격이라고 합니다.

CommonJS 규격

Node.js 환경에서 기본적으로 채택한 방식입니다.

  • 각 파일은 독립적인 모듈로 취급되며, 내부에서 module 객체를 통해 현재 모듈의 정보를 참조합니다.
  • 외부 모듈을 불러올 때는 require() 함수를 사용합니다.
  • 모듈의 멤버를 외부에 공개할 때는 module.exports 객체를 활용합니다.

ES Modules (ESM) 규격

브라우저와 서버 환경 모두에서 사용할 수 있는 표준 규격입니다. AMD나 CommonJS 등 다양한 규격을 따로 학습할 필요 없이 통일된 문법을 제공합니다.

  • 모든 JavaScript 파일은 독립적인 모듈로 동작합니다.
  • 다른 모듈의 기능을 가져올 때는 import 키워드를 사용합니다.
  • 현재 모듈의 기능을 내보낼 때는 export 키워드를 사용합니다.

Node.js에서 ESM을 활성화하려면 다음 조건을 만족해야 합니다:

  1. Node.js v14.15.1 이상의 버전이 설치되어 있어야 합니다.
  2. 프로젝트 루트의 package.json 파일에 "type": "module" 속성을 추가해야 합니다.

Node.js 환경에서의 모듈 활용

모듈의 종류

  • 내장 모듈 (Core Modules): Node.js 설치 시 기본적으로 제공되는 fs, path, http 등의 모듈입니다.
  • 로컬 모듈 (Local Modules): 개발자가 직접 생성한 .js 파일로 구성된 사용자 정의 모듈입니다.
  • 외부 모듈 (Third-party Modules): 다른 개발자나 조직이 만들어 배포한 모듈로, 패키지 관리자를 통해 다운로드하여 사용합니다.

모듈 로드 방식

CommonJS 환경을 기준으로 모듈을 불러오는 예시는 다음과 같습니다.

// 내장 모듈 로드
const fileSystem = require('fs');
const pathUtils = require('path');

// 로컬 모듈 로드 (확장자 생략 가능)
const mathHelpers = require('./utils/mathHelpers');

// 외부 모듈 로드
const _ = require('lodash');

참고: require()를 통해 모듈을 불러오는 시점에 해당 모듈 내부의 코드가 즉시 실행됩니다.

모듈 스코프와 캡슐화

각 모듈은 자신만의 독립된 스코프를 가집니다. 따라서 모듈 내부에서 선언된 변수나 함수는 명시적으로 내보내지 않는 한 외부에서 접근할 수 없으며, 이는 전역 스코프 오염을 방지하는 데 핵심적인 역할을 합니다.

// config.js
const apiKey = 'SECRET_KEY_12345';

function getApiKey() {
    return apiKey;
}

// main.js
const config = require('./config');
console.log(config); // 출력: {} (빈 객체)

멤버 내보내기 (Exporting)

module 객체와 module.exports

모든 로컬 모듈은 자신의 메타데이터를 담고 있는 module 객체를 가집니다. 이 중 module.exports는 외부로 공유할 대상을 지정하는 통로입니다. require()를 호출한 결과물은 결국 이 module.exports가 가리키는 객체가 됩니다.

// userProfile.js
module.exports.getName = function() {
    return 'Alice';
};

module.exports.getRole = function() {
    return 'Administrator';
};

exports 단축 객체의 함정

Node.js는 개발자의 편의를 위해 exports라는 단축 객체를 제공합니다. 초기 상태에서 exports와 module.exports는 동일한 빈 객체를 참조합니다. 하지만 이 둘을 혼용할 때 주의해야 할 함정이 있습니다.

// scenario A
exports.version = '1.0.0';
module.exports = {
    status: 'active',
    retries: 3
};
// require() 결과: { status: 'active', retries: 3 }
// exports에 할당한 version은 무시됨
// scenario B
module.exports.version = '1.0.0';
exports = {
    status: 'active',
    retries: 3
};
// require() 결과: { version: '1.0.0' }
// exports 참조만 변경되었을 뿐, module.exports는 그대로 유지됨

결론적으로 require()의 반환값은 항상 module.exports를 기준으로 결정됩니다. 코드 가독성과 예기치 않은 오류를 방지하기 위해 한 모듈 내에서는 module.exports와 exports 중 하나만 일관되게 사용하는 것이 좋습니다.

NPM과 패키지 생태계

패키지의 개념

Node.js 생태계에서 외부 모듈은 '패키지'라고 불립니다. 이는 오픈소스 커뮤니티에 의해 공유되며, 내장 모듈을 기반으로 하거나 독립적으로 구현된 고급 API를 제공하여 개발 생산성을 높여줍니다.

패키지 설치 및 관리

NPM(Node Package Manager)을 사용하여 패키지를 검색하고 프로젝트에 통합할 수 있습니다.

# 특정 패키지 설치
npm install axios

# 전역(Global) 설치
npm install -g typescript

# 특정 버전 설치
npm install express@4.18.2

# 패키지 제거
npm uninstall axios

설치된 패키지는 프로젝트 루트의 node_modules 디렉토리에 저장되며, package-lock.json 파일에는 종속성 트리와 정확한 버전 정보가 기록됩니다.

패키지 버전은 '주.부.수(Major.Minor.Patch)' 형식의 시맨틱 버저닝(Semantic Versioning)을 따릅니다. 주 버전은 호환성이 깨지는 변경, 부 버전은 하위 호환되는 기능 추가, 수 버전은 버그 수정을 의미합니다.

package.json 구성

프로젝트의 루트 디렉토리에는 반드시 package.json 파일이 존재해야 합니다. 다음 명령어로 빠르게 생성할 수 있습니다.

npm init -y

종속성(Dependencies) 구분

  • dependencies: 런타임 환경에서 반드시 필요한 핵심 패키지입니다. npm install 명령어만 실행하면 이 목록에 있는 모든 패키지가 자동으로 다운로드됩니다.
  • devDependencies: 테스트, 린팅, 빌드 등 개발 단계에서만 사용되는 패키지입니다. 설치 시 -D 또는 --save-dev 플래그를 사용합니다.
npm install jest -D

네트워크 속도와 레지스트리 미러링

기본 NPM 레지스트리의 응답 속도가 느릴 경우, 타사 미러 서버를 사용하도록 설정을 변경할 수 있습니다.

# 현재 레지스트리 확인
npm config get registry

# 레지스트리 변경 (예시)
npm config set registry https://registry.npmmirror.com

또는 nrm 도구를 활용하면 여러 레지스트리를 편리하게 전환할 수 있습니다.

npm install -g nrm
nrm ls       # 사용 가능한 레지스트리 목록 출력
nrm use taobao   # 타오바오 미러로 전환

표준 패키지 디렉토리 구조

올바르게 구성된 NPM 패키지는 다음 조건을 충족해야 합니다:

  1. 패키지는 독립된 최상위 디렉토리를 가져야 합니다.
  2. 최상위 디렉토리에는 필수 메타데이터를 담은 package.json 파일이 위치해야 합니다.
  3. package.json 내에는 패키지의 식별자인 name, 현재 상태를 나타내는 version, 그리고 모듈 로드 시 기준이 되는 진입점 파일인 main 속성이 반드시 정의되어 있어야 합니다.

태그: Node.js CommonJS ESModules npm package.json

10월 13일 18:56에 게시됨