[JSTS-006][기초] npm·모듈·패키지 한 번에 이해하기 > IT 기술 공유

• 목록

[이번 수업]

JavaScript를 모듈로 나누어 npm 스크립트로 실행하고 의존성·잠금 파일·재현 설치를 구분합니다.

[선수지식]

JSTS-001·002의 실행 환경과 함수를 알고 Node.js·npm을 설치해야 합니다.

[학습목표]

1. 모듈·패키지·npm의 역할을 구분한다.
2. ES 모듈을 import·export하고 npm 스크립트로 실행한다.
3. dependencies·devDependencies·package-lock.json을 설명한다.

[핵심개념]

모듈(module)은 기능을 파일로 나누고 필요한 값만 내보내거나 가져오는 단위입니다. ES 모듈은 `export`·`import`를 씁니다. package.json의 `"type": "module"`은 `.js`를 ES 모듈로 해석하게 하며 상대 import에는 `.js` 확장자까지 적습니다.

패키지(package)는 package.json으로 설명되는 폴더 트리입니다. 이 파일에는 이름, 버전, 모듈 방식, 스크립트, 의존성을 적고 `"private": true`로 실수로 공개 배포되는 일을 막습니다.

npm은 패키지 설치와 명령 실행을 돕습니다. `npm install 패키지명`은 보통 실행 의존성에, `npm install -D 패키지명`은 테스트·빌드용 `devDependencies`에 기록합니다. 설치 코드는 `node_modules`에 놓이며 직접 수정하지 않습니다.

버전 범위는 허용할 업데이트를 나타냅니다. package-lock.json은 실제로 선택된 하위 의존성 트리를 기록하므로 package.json과 함께 버전 관리하고 npm 명령으로 갱신합니다.

`npm install`은 필요하면 잠금 파일도 갱신합니다. `npm ci`는 package.json과 잠금 파일이 맞아야 하며 잠금 파일을 바꾸지 않아 자동 검사 환경의 재현 설치에 알맞습니다.

`scripts`는 `npm run 이름`으로 실행할 명령의 별칭이며 `start`, `test`, `build` 같은 공통 진입점을 제공합니다. 설치 과정과 scripts도 실제 코드처럼 실행됩니다.

[따라하기]

빈 `jsts006-demo` 폴더를 만들고 아래 세 파일을 저장합니다. 외부 패키지를 설치하지 않아 인터넷 연결이 필요 없습니다.

package.json

```json
{
  "name": "module-practice",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node index.js"
  }
}
```

math.js

```javascript
export function add(a, b) {
  return a + b;
}
```

index.js

```javascript
import { add } from "./math.js";

console.log("2 + 3 =", add(2, 3));
```

터미널에서 해당 폴더로 이동해 실행합니다. 명령은 Windows PowerShell, macOS, Linux에서 같습니다.

```shell
npm run start
```

버전 줄은 달라도 마지막 출력은 같습니다.

```text
> module-practice@1.0.0 start
> node index.js

2 + 3 = 5
```

package.json의 start 값이 `node index.js`로 연결되고, index.js가 math.js의 `add`만 가져와 사용했습니다.

[흔한 실수]

- 패키지와 모듈을 같게 봅니다. 패키지는 여러 모듈을 포함할 수 있습니다.
- `"type": "module"` 없이 import를 써서 오류가 납니다.
- 상대 import의 `.js` 확장자를 생략합니다.
- node_modules를 직접 고치거나 커밋합니다.
- 잠금 파일을 무시해 환경마다 다른 트리가 설치됩니다.

[보안 주의]

이름이 비슷한 패키지를 잘못 설치하지 않도록 정확한 이름, 공식 저장소, 유지 상태를 확인하세요. 설치 스크립트와 npm scripts는 명령을 실행할 수 있으므로 출처를 모르는 프로젝트에서 바로 실행하지 말고 격리 환경에서 package.json과 잠금 파일 변경을 먼저 검토합니다. 토큰을 package.json, 소스, 명령줄에 넣지 말고 공식 자격증명 저장 방식을 사용합니다. `npm audit` 결과는 중요한 신호지만 안전을 완전히 보증하지 않으므로 불필요한 의존성을 줄이고 보안 권고와 업데이트 내용을 함께 확인하세요.

[직접 해볼 과제]

1. math.js에 `multiply(a, b)`를 export하고 index.js에서 가져와 `3 * 4 = 12`를 출력하세요.
2. package.json에 `"check": "node --check index.js"` 스크립트를 추가하고 `npm run check`를 실행하세요.

[확인문제]

1. 모듈과 패키지의 차이는 무엇인가요?
2. package-lock.json을 함께 버전 관리하는 이유는 무엇인가요?
3. dependencies와 devDependencies는 어떤 기준으로 나누나요?

[다음 학습]

JSTS-007에서는 JavaScript 코드에 TypeScript 타입 시스템을 적용합니다.

[공식 참고 자료]

- Node.js 패키지·모듈 공식 문서: https://nodejs.org/api/packages.html
- package.json 공식 문서: https://docs.npmjs.com/cli/v11/configuring-npm/package-json/
- package-lock.json 공식 문서: https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json/
- npm ci 공식 문서: https://docs.npmjs.com/cli/v11/commands/npm-ci/
- npm audit 공식 문서: https://docs.npmjs.com/cli/v11/commands/npm-audit/