NPM: package.json 스크립트를 문서화하는 방법

프로젝트가 커짐에 따라 package.json에 더 많은 스크립트를 추가합니다.
새로운 멤버가 프로젝트에 합류했을 때(혹은 휴식 후 복귀했을 때) 대본 자체로는 이해하기 힘들고,
그것이 무엇을 하고 있으며 왜 생성되었는지, 특히 스크립트가 많은 매개변수와 && 가 있는 80자 길이일 때.

이에 대해 우리가 무엇을 하는지 봅시다:

README.md

README.md 파일의 섹션에 스크립트에 대한 문서를 추가할 수 있습니다.

## NPM scripts

- **start**: Description for `npm start` script
- **test**: Description for `npm test` script
...

👍이 접근 방식은 마크다운 서식 있는 텍스트 기능을 사용할 수 있기 때문에 좋습니다. 또한 README 파일은 팀의 새로운 구성원이 여는 첫 번째 파일입니다.

🙁 이 접근 방식의 단점은 package.json에서 스크립트를 볼 때 README를 연 다음 package.json 또는 터미널로 돌아가서 명령을 실행해야 한다는 것입니다.

패키지.json

Npm은 예를 들어 tsconfig.json에서 JSON 주석을 허용할 수 있는 package.json에 대해 지원하지 않습니다JSON5.

주제에 대한 StackOverflow에 대한 인기 있는 질문이 있습니다.

How do I add comments to package.json for npm install?

StackOverflow에서 제안된 모든 변형(및 토론)을 읽을 수 있습니다. 괜찮을 수 있는 한 가지 옵션은 다음과 같습니다.

{
  "name": "package name",
  "version": "1.0",
  "description": "package description",
  "scripts": {
    "start": "npm install && node server.js"
  },
  "scriptsComments": {
    "start": "Runs development build on a local server configured by server.js"
  },
  ...
}

👍이 접근 방식은 스크립트 문서가 스크립트 자체에 더 가깝게 유지되기 때문에 좋습니다.

🙁 단점: package.json이 더 많은 스크립트, 종속성, 기타 도구 구성과 함께 커짐에 따라 길을 잃기 매우 쉽습니다.

npx 왜

npx why는 package.json 스크립트 문서화 문제를 해결하기 위해 만든 도구입니다.

터미널에서 스크립트를 실행해야 한다면 터미널에 스크립트에 대한 문서가 없는 이유는 무엇입니까?


npx why --init는 package.json의 모든 스크립트와 기본 설명을 사용하여 프로젝트의 루트에 package-why.json을 생성합니다.

그런 다음 npx why를 호출하면 모든 스크립트와 설명이 인쇄됩니다.
npx why <some script name>는 npm run <some script name>에 대한 설명만 인쇄합니다.
npx why <some script name> "<script description>" 에 설명을 전달하여 문서를 업데이트할 수 있습니다. 또는 package-why.json 파일을 직접 변경합니다.

더 나은 경험을 위해 패키지를 개발 종속성으로 설치하는 것이 좋습니다.

npm install why --save-dev

🎉스크립트를 문서화하기 위한 이 솔루션은 터미널(스크립트를 사용해야 하는 곳)에서 문서에 액세스하기 때문에 좋습니다.
또한 새로운 업데이트와 기능을 통해 why 사용 경험이 점점 더 좋아질 것이라고 확신합니다.

🙁 단점: package-why.json 파일과 package.json 파일 사이를 이동해야 하기 때문에 스크립트를 문서화하는 과정이 그리 편하지 않습니다.

체크아웃 npx why package .