package.json 가독화 도구 사용법
npm 프로젝트의 핵심 메타데이터 파일인 package.json은 의존성이 늘어날수록 한 화면에 들어오지 않게 되고, "이 라이브러리가 dependencies인가 devDependencies인가?" "이 ^4.2.0은 정확히 어디까지 업데이트되는 범위지?" 같은 질문이 반복됩니다. 이 도구에 package.json 내용을 붙여넣으면 자동으로 JSON을 검증하고, 키를 표준 순서(name → version → description → main → scripts → dependencies …)로 재배치하며, 모든 의존성을 dependencies / devDependencies / peerDependencies / optionalDependencies 그룹으로 분리해 표 형태로 보여줍니다.
각 패키지 옆에는 버전 범위 의미가 색상 배지로 표시됩니다. ^1.2.3은 minor 업데이트까지 허용(파란색), ~1.2.3은 patch 업데이트만 허용(초록색), 1.2.3처럼 캐럿/틸드 없는 표기는 exact(노란색), * 또는 latest는 any(빨간색)로 나타납니다. SemVer 규칙을 모르거나 팀원에게 설명할 때 그대로 화면을 보여 주면 됩니다.
scripts 의존 관계 분석
scripts 섹션에서는 각 스크립트가 다른 스크립트를 호출하는지를 npm run / yarn / pnpm 키워드로 추적해 표시합니다. 예를 들어 "build": "npm run lint && tsc"라면 이 build 스크립트가 lint 스크립트에 의존한다는 사실을 알려 줍니다. CI/CD 파이프라인을 설계할 때 어떤 스크립트가 무엇을 호출하는지 한 번에 파악할 수 있습니다.
가독성 점수와 경고
경고 섹션은 흔한 실수를 자동으로 잡아 줍니다. dependencies와 devDependencies에 같은 패키지가 동시에 들어있는지, name이 npm 규칙(소문자·하이픈)을 어기는지, version이 SemVer 형식이 아닌지, scripts에 "test": "echo \\"Error...\\" && exit 1" 같은 기본값이 그대로 남아있는지 등을 검사합니다.
자주 묻는 질문 (FAQ)
Q. 캐럿(^)과 틸드(~)는 정확히 어떻게 다른가요?
A. ^1.2.3은 1.x.x 안에서 가장 큰 버전(주 버전 고정), ~1.2.3은 1.2.x 안에서 가장 큰 버전(부 버전 고정)을 허용합니다. 0.x.x 대 버전에서는 ^의 동작이 약간 달라 ^0.2.3은 0.2.x만 허용합니다.
Q. dependencies와 devDependencies는 어떻게 구분하나요?
A. 런타임에서 import 해 쓰는 것은 dependencies, 빌드·테스트·린트·타입 정의처럼 개발 단계에서만 필요한 것은 devDependencies로 둡니다. 라이브러리를 만들 때 잘못 분류하면 npm install 시 사용자의 node_modules가 불필요하게 커집니다.
Q. peerDependencies는 언제 사용하나요?
A. 플러그인이나 컴포넌트 라이브러리가 호스트 프로젝트의 react·vue 같은 패키지에 "함께 설치되어 있어야 한다"는 조건을 명시할 때 씁니다. npm v7+ 이후로는 기본적으로 자동 설치되므로 동일 버전 충돌이 더 자주 보일 수 있습니다.