NPM 공식문서 따라 읽기

sham·2025년 1월 11일

npm

개요

프론트를 개발하며 숨쉬듯 사용했던 npm install, npm run dev, npm run build.

그러나 내가 사용하고 있는 npm이 정확히 무엇인지, 제대로 알고 있지 않았다.

NPM은 Node.js의 패키지를 관리할 수 있는 도구이다.

Python의 pip나 Ruby의 gem처럼, 웹 사이트에서 패키지를 다운로드하여 컴퓨터에 설치할 수 있다.

공식 문서를 따라가며 NPM이 무엇인지 제대로 알아보자.

본문

About npm

About npm | npm Docs

npm은 세상에서 가장 큰 소프트웨어 저장소이다.

개인부터 조직까지 npm을 통해 오픈 소스 개발부터 사내 개발을 관리하고 있다.

npm을 구성하는 것은 다음 세 가지 요소이다.

웹사이트 - 남들이 만든 패키지를 조회하고, 직접 만들어서 관리할 수 있다.
CLI - 터미널 상에서 npm와 상호작용한다.
레지스트리 - npm 상의 모든 모듈들이 저장되는 곳. npm 서버에서 우리는 모듈들을 설치받는다.

사용처

남들이 만들어 Node.js 기반 패키지를 다운받아 사용할 수 있다. npx 없이!
내가 만든 JS 모듈을 다른 사용과 공유할 수 있다. 특정 개발자에게만 제한할 수도 있다.
조직을 만들어 패키지를 관리할 수도 있다.
모듈의 여러 버전을 만들고, 의존성을 관리할 수 있다.

Packages and modules

About packages and modules | npm Docs

packages와 modules은 다음과 같이 구분된다.

packages
- package.json에 의해 정의되는 파일이나 디렉토리
- package.json을 포함하며 npm registry 상에 배포되어 있어야 한다.
- packages를 만들면 자동으로 사용자나 조직 이름을 딴 스코프가 부여된다. (사용자 이름이 gulsam00이면 @gulsam00/[패키지 이름])
modules
- Node.js의 require() 함수로 불러올 수 있는 node_modules 디렉토리의 파일이나 디렉토리이다.
  - package.json에 “main” 필드가 포함된 폴더나, JS 파일이 이에 해당한다.

모든 모듈이 패키지는 아니며, package.json 파일을 가진 모듈을 패키지로 간주한다.

Configuring/package.json

package.json | npm Docs

굉장히 길다. 몇몇 부분만 발췌해보았다.

package.json은 문서이다. 개발자가 배포한 패키지에 대해 설치, 관리를 할 때 도움이 될 문서이다.

패키지가 무엇을 의존하며, 어떤 버전이고 어떻게 배포하는지에 대한 명세가 담겨있다.

{
  "name": "ultra-exact-ncst",
  "version": "1.1.6",
  "description": "nowcast with coordinate",
  "main": "dist/index.js",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "test": "npx ts-node src/index.ts"
  },
  "author": "GulSam00",
  "license": "ISC",
  "Keywords": [
    "nowcast",
    "coordinate"
  ],
  "dependencies": {
    "axios": "^1.7.7",
    "date-fns": "^4.1.0"
  },
  "devDependencies": {
    "dotenv": "^16.4.5",
    "typescript": "^5.6.3"
  },
  "files": [
    "dist/**/*"
  ]
}

위는 내가 직접 만든 패키지의 package.json이다. 배포하는 패키지에는 어떤 요소가 들어가는지 확인해보자.

main
- 모듈을 사용할 때, 해당 모듈의 진입점이 될 경로를 설정한다.
  - require("ultra-exact-ncst") 를 호출했을 때, main에 지정한 모듈을 export 가 반환되는 것이다.
- 이 경로는 패키지 폴더의 루트를 기준으로 상대 경로여야 한다.
- main이 설정되지 않으면 기본값으로 패키지의 루트 폴더에 있는 index.js 파일이 사용된다.
- 배포하기 위한 패키지의 필수적이면서도 핵심적인 설정이다.
- 내 패키지는 ts 파일을 js로 컴파일 및 번들링하여 dist/index.js라는 이름으로 저장되었기에, 해당 경로를 설정해주었다.
type
- 기본값은 commonjs로, 해당 디렉토리의 모든 js 파일을 CommonJS로 간주한다.
- "module" 로 설정하면 모든 js 파일을 ESM(ES modules)로 간주한다.
  - 즉, import, export 문법이 포함된 ESM을 사용하고 싶다면 "module"로 설정해주자…!
scripts
- 주로 사용하게 될 명령어를 커맨드로 지정해서 사용할 수 있다.
- npm run [커맨드] 형태로 CLI 상에서 사용한다.
dependencies
- 이 패키지가 의존하고 있는 패키지들의 이름과 버전을 기술해놓은 명세이다.
- 압축 파일이나 Git URL을 통해서 지정할 수도 있다.
- npm install 시 dependencies에 있는 패키지들을 node_modules라는 디렉토리 경로에 설치하게 된다.
devDependencies
- 기본적인 것은 dependencies와 동일하지만, 배포할 때는 포함되지 않을 패키지들이 이곳에 들어간다.
- 애플리케이션 동작과 직접적인 연관은 없지만, 개발할 때 필요한 라이브러리가 이곳에 들어가는데, prettier 같은 formatter나, jest같은 테스트 도구나, 배포 시에는 js로 컴파일되는 typescript 등이 이에 해당한다.
- npm install 시 설치되는 것은 동일하나, 배포된 해당 패키지를 설치할 때는 devDependencies의 패키지들이 설치되지 않는다.
- 테스트 할 때 사용된 dotenv와 타입 지정을 위한 typescript가 devDependencies에 해당된다.
files
- files 필드는 패키지가 종속성으로 설치될 때 포함될 항목을 설명하는 파일 패턴 배열이다.
- .gitignore와 정반대의 역할을 한다고 보면 편하다. 무조건 설치되어야 하는 파일들을 배열 형태로 넣어준다.

Using/workspaces

workspaces | npm Docs

Workspaces(워크스페이스)는 npm CLI에서 제공하는 기능 집합을 지칭하는 일반적인 용어로, 단일 최상위 루트 패키지 내에서 로컬 파일 시스템의 여러 패키지를 관리할 수 있도록 지원하는 기능이다.

간단하게 말하면 한 package.json에서 packages라는 이름으로 구분된 작업 영역을 만들 수 있는 기능이다. 별개의 폴더를 만든다고 생각해도 좋다.

{
    "name": "workspace-example",
    "version": "1.0.0",
    "workspaces": [
        "packages/a",
        "packages/b",
        "packages/c"
    ]
}