npm 설치를 위해 package.json에 주석을 어떻게 추가합니까?

간단한 package.json 파일이 있고 주석을 추가하고 싶습니다. 이 작업을 수행 할 수있는 방법이 있습니까, 아니면이 작업을 수행하기위한 해킹이 있습니까?

{
  "name": "My Project",
  "version": "0.0.1",
  "private": true,
  "dependencies": {
    "express": "3.x",
    "mongoose": "3.x"
  },
  "devDependencies" :  {
    "should": "*"
    /* "mocha": "*" not needed as should be globally installed */
  }
}

위의 예제 주석은 npm 나누기로 작동하지 않습니다. // 스타일 주석을 시도했습니다.

이것은 최근 node.js 메일 링리스트 에서 논의되었습니다 .

npm을 만든 Isaac Schlueter에 따르면 :

... "//"키는 npm에서 어떤 목적으로도 사용되지 않으며 주석 용으로 예약되어 있습니다 ... 여러 줄 주석을 사용하려면 배열 또는 여러 "//"를 사용할 수 있습니다 열쇠.

일반적인 도구 (npm, yarn 등)를 사용하면 여러 개의 "//"키가 제거됩니다. 이것은 살아남는다 :

{ "//": [ 
  "first line", 
  "second line" ] } 

이것은 살아남지 못할 것입니다 :

{ "//": "this is the first line of a comment", 
  "//": "this is the second line of the comment" } 

JSON에 주석을 추가하는 또 다른 해킹이 있습니다. 이후:

{"a": 1, "a": 2}

에 해당

{"a": 2}

당신은 다음과 같은 것을 할 수 있습니다 :

{
  "devDependencies": "'mocha' not needed as should be globally installed",
  "devDependencies" :  {
    "should": "*"
  }
}

복잡하고 해킹 된 솔루션에 대해 한 시간을 낭비한 후에서 부피가 큰 종속성 섹션에 주석을 달기위한 간단하고 유효한 솔루션을 모두 발견했습니다 package.json. 이처럼 :

{
  "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"
  },
  "dependencies": {
    "ajv": "^5.2.2"
  },
  "dependenciesComments": {
    "ajv": "JSON-Schema Validator for validation of API data"
  }
}

같은 방식으로 정렬하면 git commit diffs 또는으로 작업하는 동안 편집기에서 이러한 종속성 / 주석 쌍을 추적하는 것이 매우 쉽습니다 package.json.

추가 도구가 필요하지 않으며 평범하고 유효한 JSON입니다.

이것이 누군가를 돕기를 바랍니다.

많은 흥미로운 아이디어.

내가하고있는 일은 이것입니다 :

{
  ...
  "scripts": {
    "about": "echo 'Say something about this project'",
    "about:clean": "echo 'Say something about the clean script'",
    "clean": "do something",
    "about:build": "echo 'Say something about building it'",
    "build": "do something",
    "about:watch": "echo 'Say something about how watch works'",
    "watch": "do something",
  }
  ...
}

이 방법으로 스크립트 자체에서 "의사-의견"을 읽고 터미널에서 어떤 종류의 도움을보기 위해 다음과 같은 것을 실행할 수 있습니다.

npm run about
npm run about:watch

이 토론을위한 나의 2cents :)

NPS (노드 패키지 스크립트)가이 문제를 해결했습니다. NPM 스크립트를 별도의 JS 파일에 저장하면 주석을 추가하고 필요한 다른 JS 로직을 추가 할 수 있습니다. https://www.npmjs.com/package/nps

package-scripts.js내 프로젝트 중 하나에서 샘플

module.exports = {
  scripts: {
    // makes sure e2e webdrivers are up to date
    postinstall: 'nps webdriver-update',

    // run the webpack dev server and open it in browser on port 7000
    server: 'webpack-dev-server --inline --progress --port 7000 --open',

    // start webpack dev server with full reload on each change
    default: 'nps server',

    // start webpack dev server with hot module replacement
    hmr: 'nps server -- --hot',

    // generates icon font via a gulp task
    iconFont: 'gulp default --gulpfile src/deps/build-scripts/gulp-icon-font.js',

    // No longer used
    // copyFonts: 'copyfiles -f src/app/glb/font/webfonts/**/* dist/1-0-0/font'
  }
}

방금 로컬 설치를 npm install nps -save-dev하고 package.json스크립트에 넣었습니다 .

"scripts": {
    "start": "nps",
    "test": "nps test"
}

중복 된 키를 덮어 쓴다는 사실을 항상 남용 할 수 있습니다. 이것은 내가 방금 쓴 것입니다.

"dependencies": {
  "grunt": "...",
  "grunt-cli": "...",

  "api-easy": "# Here is the pull request: https://github.com/...",
  "api-easy": "git://..."

  "grunt-vows": "...",
  "vows": "..."
}

그러나 JSON이 중복 키를 허용하는지 여부는 확실하지 않습니다 (JSON 구문이 객체에서 중복 키를 허용합니까? 참조). . npm과 함께 작동하는 것 같습니다.

권장되는 핵은 nodejs 메일 링리스트"//" 에서 키 를 사용 하는 것 입니다. 테스트했을 때 "종속성"섹션에서는 작동하지 않았습니다. 또한 게시물의 예제는 여러 "//"키를 사용하므로 npm은 키가 중복 된 JSON 파일을 거부하지 않습니다. 즉, 위의 핵은 항상 괜찮습니다.

업데이트 : 중복 키 핵의 단점 중 하나는npm install --save 모든 중복 자동으로 제거 입니다. 불행히도, 그것을 간과하기가 매우 쉽고 의도적 인 의견이 사라졌습니다.

"//"이 보인다 해킹은 여전히 가장 안전합니다. 그러나 여러 줄 주석도에 의해 제거됩니다 npm install --save.

재미있는 해킹 아이디어가 있습니다.

예를 들어 package.json에서 주석 분배기로 npm 패키지 이름을 작성 dependencies하고 devDependencies차단하십시오.x----x----x

{
    "name": "app-name",
    "dependencies": {
        "x----x----x": "this is the first line of a comment",
        "babel-cli": "6.x.x",
        "babel-core": "6.x.x",
        "x----x----x": "this is the second line of a comment",
        "knex": "^0.11.1",
        "mocha": "1.20.1",
        "x----x----x": "*"
    }
}

참고 : *블록에서 와 같이 유효한 버전으로 마지막 주석 구분선을 추가해야합니다 .

이 스레드에서 영감을 받아 다음 과 같이 사용합니다 .

{
  "//dependencies": {
    "crypto-exchange": "Unified exchange API"
  },
  "dependencies": {
    "crypto-exchange": "^2.3.3"
  },
  "//devDependencies": {
    "chai": "Assertions",
    "mocha": "Unit testing framwork",
    "sinon": "Spies, Stubs, Mocks",
    "supertest": "Test requests"
  },
  "devDependencies": {
    "chai": "^4.1.2",
    "mocha": "^4.0.1",
    "sinon": "^4.1.3",
    "supertest": "^3.0.0"
  }
}

지금까지 대부분의 "해킹"은 JSON을 남용하는 것을 제안합니다. 대신 기본 스크립팅 언어를 남용하지 않는 이유는 무엇입니까?

편집 초기 응답은 설명을 올바른 모양 # add comments here으로 감싸는 데 사용 되었습니다. 그러나 플래그 (예 : npm run myframework---myframework-flags)는 무시되므로 Windows에서는 작동하지 않습니다. 모든 플랫폼에서 작동하도록 응답을 변경하고 가독성을 위해 들여 쓰기를 추가했습니다.

{
 "scripts": {
    "help": "       echo 'Display help information (this screen)';          npm run",
    "myframework": "echo 'Run myframework binary';                          myframework",
    "develop": "    echo 'Run in development mode (with terminal output)';  npm run myframework"
    "start": "      echo 'Start myFramework as a daemon';                   myframework start",
    "stop":  "      echo 'Stop the myFramework daemon';                     myframework stop"
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

이것은 :

1. JSON 준수를 위반하지 마십시오 (또는 적어도 해킹이 아니며 IDE는 이상하고 위험한 일을하는 것에 대한 경고를주지 않습니다)
2. 크로스 플랫폼에서 작동 (macOS 및 Windows에서 테스트되었으며 Linux에서 제대로 작동한다고 가정)
3. 달리는 데 방해가되지 않습니다 npm run myframework -- --help
4. 실행할 때 의미있는 정보를 출력합니다 npm run (사용 가능한 스크립트에 대한 정보를 얻기 위해 실행하는 실제 명령 임)
5. 보다 명확한 도움말 명령을 제공합니다 (일부 개발자가 npm run이 이러한 출력을 제공한다는 것을 인식하지 못하는 경우)
6. 명령 자체를 실행할 때 명령과 설명을 모두 표시합니다
7. 그냥 열 때 package.json(사용 less하거나 좋아하는 IDE) 다소 읽을 수 있습니다.

여기에 내 의견에 필자의 package.json/은 bower.json:

내가 가진 package.json.js그 실제를 수출하는 스크립트가 들어 있습니다 package.json. 스크립트를 실행하면 이전 스크립트를 덮어 쓰고 package.json변경된 내용을 알려주며 자동 변경 내용을 추적 할 수 있습니다 npm. 그렇게하면 프로그래밍 방식으로 사용하려는 패키지를 정의 할 수도 있습니다.

최신 grunt 작업은 다음과 같습니다 : https://gist.github.com/MarZab/72fa6b85bc9e71de5991

나는 다음과 scripts같이 끝났다 .

  "scripts": {
    "//-1a": "---------------------------------------------------------------",
    "//-1b": "---------------------- from node_modules ----------------------",
    "//-1c": "---------------------------------------------------------------",
    "ng": "ng",
    "prettier": "prettier",
    "tslint": "tslint",
    "//-2a": "---------------------------------------------------------------",
    "//-2b": "--------------------------- backend ---------------------------",
    "//-2c": "---------------------------------------------------------------",
    "back:start": "node backend/index.js",
    "back:start:watch": "nodemon",
    "back:build:prod": "tsc -p backend/tsconfig.json",
    "back:serve:prod": "NODE_ENV=production node backend/dist/main.js",
    "back:lint:check": "tslint -c ./backend/tslint.json './backend/src/**/*.ts'",
    "back:lint:fix": "yarn run back:lint:check --fix",
    "back:check": "yarn run back:lint:check && yarn run back:prettier:check",
    "back:check:fix": "yarn run back:lint:fix; yarn run back:prettier:fix",
    "back:prettier:base-files": "yarn run prettier './backend/**/*.ts'",
    "back:prettier:fix": "yarn run back:prettier:base-files --write",
    "back:prettier:check": "yarn run back:prettier:base-files -l",
    "back:test": "ts-node --project backend/tsconfig.json node_modules/jasmine/bin/jasmine ./backend/**/*spec.ts",
    "back:test:watch": "watch 'yarn run back:test' backend",
    "back:test:coverage": "echo TODO",
    "//-3a": "---------------------------------------------------------------",
    "//-3b": "-------------------------- frontend ---------------------------",
    "//-3c": "---------------------------------------------------------------",
    "front:start": "yarn run ng serve",
    "front:test": "yarn run ng test",
    "front:test:ci": "yarn run front:test --single-run --progress=false",
    "front:e2e": "yarn run ng e2e",
    "front:e2e:ci": "yarn run ng e2e --prod --progress=false",
    "front:build:prod": "yarn run ng build --prod --e=prod --no-sourcemap --build-optimizer",
    "front:lint:check": "yarn run ng lint --type-check",
    "front:lint:fix": "yarn run front:lint:check --fix",
    "front:check": "yarn run front:lint:check && yarn run front:prettier:check",
    "front:check:fix": "yarn run front:lint:fix; yarn run front:prettier:fix",
    "front:prettier:base-files": "yarn run prettier \"./frontend/{e2e,src}/**/*.{scss,ts}\"",
    "front:prettier:fix": "yarn run front:prettier:base-files --write",
    "front:prettier:check": "yarn run front:prettier:base-files -l",
    "front:postbuild": "gulp compress",
    "//-4a": "---------------------------------------------------------------",
    "//-4b": "--------------------------- cypress ---------------------------",
    "//-4c": "---------------------------------------------------------------",
    "cy:open": "cypress open",
    "cy:headless": "cypress run",
    "cy:prettier:base-files": "yarn run prettier \"./cypress/**/*.{js,ts}\"",
    "cy:prettier:fix": "yarn run front:prettier:base-files --write",
    "cy:prettier:check": "yarn run front:prettier:base-files -l",
    "//-5a": "---------------------------------------------------------------",
    "//-5b": "--------------------------- common ----------------------------",
    "//-5c": "---------------------------------------------------------------",
    "all:check": "yarn run back:check && yarn run front:check && yarn run cy:prettier:check",
    "all:check:fix": "yarn run back:check:fix && yarn run front:check:fix && yarn run cy:prettier:fix",
    "//-6a": "---------------------------------------------------------------",
    "//-6b": "--------------------------- hooks -----------------------------",
    "//-6c": "---------------------------------------------------------------",
    "precommit": "lint-staged",
    "prepush": "yarn run back:lint:check && yarn run front:lint:check"
  },

백엔드, 프론트 엔드, 모두 등의 스크립트 사이에 일종의 구분 기호를두기 위해 한 줄을 명확히하는 것이 아닙니다.

나는 1a, 1b, 1c, 2a의 열렬한 팬이 아니지만 ... 열쇠가 다르므로 전혀 문제가 없습니다.

으로 이 대답은 설명, //키가 예약 된, 그래서 의견을 통상적으로 사용 할 수 있습니다. 의 문제 //의견은 사용할 수 없습니다 수 있다는 것입니다 dependencies및 devDependencies버전 제약과 같은 문자열을 일반 종속성으로 :

"dependencies": {
  "//": "comment"
}

오류를 유발하고

npm ERR! 코드 EINVALIDPACKAGENAME

npm ERR! 잘못된 패키지 이름 "//": name은 URL 친화적 인 문자 만 포함 할 수 있습니다

문자열이 아닌 값을 가진 키는 유효하지 않은 종속성으로 간주되고 효율적으로 무시됩니다.

"dependencies": {
  "//": ["comment"]
}

의존성 자체도 같은 방식으로 주석 처리 할 수 ​​있습니다.

"dependencies": {
  "foo": ["*", "is not needed now"],
}

package.json이 NPM에 의해 수정 될 때 종속성이 정렬되므로 다음과 같은 종속성 위에 주석을 추가하는 것은 비현실적입니다.

"dependencies": {
  "bar": "*",
  "//": ["should be removed in 1.x release"]
  "foo": "*",
}

주석 키는 특정 행을 참조하는 경우 적절하게 이름이 지정되어야하므로 이동되지 않습니다.

"dependencies": {
  "bar": "*",
  "foo": "*",
  "foo //": ["should be removed in 1.x release"]
}

특정 종속성에 적용 가능한 주석은 semver의 일부로 추가 될 수 있습니다.

"dependencies": {
  "bar": "*",
  "foo": "* || should be removed in 1.x release"
}

이전의 첫 번째 부분 OR이 일치하지 않으면 주석을 구문 분석 할 수 있습니다 (예 :1.x .

이 해결 방법은 모든 현재 NPM 버전 (6 이하)과 호환됩니다.

대부분의 개발자는 태그 / 주석 기반 문서에 익숙하므로 사용하기 시작한 규칙은 비슷합니다. 여기 맛이 있습니다 :

{
  "@comment dependencies": [
    "These are the comments for the `dependencies` section.",
    "The name of the section being commented is included in the key after the `@comment` 'annotation'/'tag' to ensure the keys are unique.",
    "That is, using just \"@comment\" would not be sufficient to keep keys unique if you need to add another comment at the same level.",
    "Because JSON doesn't allow a multi-line string or understand a line continuation operator/character, just use an array for each line of the comment.",
    "Since this is embedded in JSON, the keys should be unique.",
    "Otherwise JSON validators, such as ones built into IDE's, will complain.",
    "Or some tools, such as running `npm install something --save`, will rewrite the `package.json` file but with duplicate keys removed.",
    "",
    "@package react - Using an `@package` 'annotation` could be how you add comments specific to particular packages."
  ],
  "dependencies": {
    ...
  },
  "scripts": {
    "@comment build": "This comment is about the build script.",
    "build": "...",

    "@comment start": [
      "This comment is about the `start` script.",
      "It is wrapped in an array to allow line formatting.",
      "When using npm, as opposed to yarn, to run the script, be sure to add ` -- ` before adding the options.",
      "",
      "@option {number} --port - The port the server should listen on."
    ],
    "start": "...",

    "@comment test": "This comment is about the test script.",
    "test": "..."
  }
}

참고 다음의 경우 dependencies, devDependencies이후 등 섹션, 주석 주석을 직접 구성 개체 내부의 개별 패키지 종속성 이상 추가 할 수 없습니다 npmNPM 패키지의 이름이 될 수있는 키를 기대하고있다. 따라서 이유@comment dependencies .

참고 : scripts 객체와 같은 특정 상황에서는 일부 편집기 / IDE가 어레이에 대해 불평 할 수 있습니다. 스크립트 컨텍스트에서 VS Code는 배열이 아닌 값에 대한 문자열을 예상합니다.

@기호가 일반 선언에서 눈 에 띄기 때문에 JSON에 주석을 추가하는 주석 / 태그 스타일 방식이 마음에 듭니다 .

이 모든 답변을 요약하면 다음과 같습니다.

1. 주석 문자열이 포함 된 단일 최상위 필드를 추가하십시오 //. 이것은 효과가 있지만 주석을 달고있는 물건 근처에 주석을 넣을 수 없기 때문에 짜증납니다.

2. 여러 추가 최상위 필드 로 시작 // , 예를 들어 //dependencies설명 문자열을 포함하는합니다. 이 방법이 더 좋지만 여전히 최상위 댓글 만 작성할 수 있습니다. 개별 종속성에 대해서는 언급 할 수 없습니다.

3. 에 echo명령을 추가 하십시오 scripts. 이것은 작동하지만에서 사용할 수 있기 때문에 짜증납니다 scripts.

이러한 솔루션은 모두 읽기 쉽지 않습니다. 그것들은 많은 시각적 노이즈를 추가하고 IDE는 그것들을 주석으로 강조 표시하지 않습니다.

합리적인 해결책은 package.json다른 파일에서 파일 을 생성하는 것입니다. 가장 간단한 방법은 JSON을 Javascript로 작성하고 Node를 사용하여 작성하는 것 package.json입니다. 이 파일 저장 package.json.mjs, chmod +x그것을, 그리고 당신은 당신을 생성하기 위해 실행할 수 있습니다 package.json.

#!/usr/bin/env node

import { writeFileSync } from "fs";

const config = {
  // TODO: Think of better name.
  name: "foo",
  dependencies: {
    // Bar 2.0 does not work due to bug 12345.
    bar: "^1.2.0",
  },
  // Look at these beautify comments. Perfectly syntax highlighted, you
  // can put them anywhere and there no risk of some tool removing them.
};

writeFileSync("package.json", JSON.stringify({
    "//": "This file is \x40generated from package.json.mjs; do not edit.",
    ...config
  }, null, 2));

이 //키를 사용하여 사람들에게 편집을 경고합니다. \x40generated고의입니다. 그것은으로 변 @generated에서 package.json일부 코드 리뷰 시스템은 기본적으로 해당 파일을 축소 의미합니다.

빌드 시스템의 추가 단계이지만 다른 모든 해킹을 능가합니다.

package.json 도구 (npm, yarn 등)를 실행하여 중복 주석 키가 제거되면 해시 버전을 사용하여 여러 줄과 키로 더 잘 읽을 수 있습니다.

"//": {
  "alpaca": "we use the bootstrap version",
  "eonasdan-bootstrap-datetimepicker": "instead of bootstrap-datetimepicker",
  "moment-with-locales": "is part of moment"
},

내 IDE에 따라 루트 키로 '유효'하지만 dependencies문자열 값을 기대한다고 불평합니다.

또 다른 해킹. package.json핸들 바 템플릿의 컨텍스트 로 읽을 스크립트를 만들었습니다 .

누군가이 방법이 유용하다고 생각되는 경우 아래 코드를 작성하십시오.

const templateData = require('../package.json');
const Handlebars = require('handlebars');
const fs = require('fs-extra');
const outputPath = __dirname + '/../package-json-comments.md';
const srcTemplatePath = __dirname + '/package-json-comments/package-json-comments.hbs';

Handlebars.registerHelper('objlist', function() {
  // first arg is object, list is a set of keys for that obj
  const obj = arguments[0];
  const list = Array.prototype.slice.call(arguments, 1).slice(0,-1);

  const mdList = list.map(function(k) {
    return '* ' + k + ': ' + obj[k];
  });

  return new Handlebars.SafeString(mdList.join("\n"));
});

fs.readFile(srcTemplatePath, 'utf8', function(err, srcTemplate){
  if (err) throw err;
  const template = Handlebars.compile(srcTemplate);
  const content = template(templateData);

  fs.writeFile(outputPath, content, function(err) {
    if (err) throw err;
  });
});

핸들 템플릿 파일 package-json-comments.hbs

### Dependency Comments
For package: {{ name }}: {{version}}

#### Current Core Packages
should be safe to update
{{{objlist dependencies
           "@material-ui/core"
           "@material-ui/icons"
           "@material-ui/styles"
}}}

#### Lagging Core Packages
breaks current code if updated
{{{objlist dependencies
           "amazon-cognito-identity-js"
}}}

#### Major version change
Not tested yet
{{{objlist dependencies
           "react-dev-utils"
           "react-redux"
           "react-router"
           "redux-localstorage-simple"

}}}

npm package.json의 경우 두 가지 방법을 찾았습니다 (이 대화를 읽은 후).

  "devDependencies": {
    "del-comment": [
      "some-text"
    ],
    "del": "^5.1.0 ! inner comment",
    "envify-comment": [
      "some-text"
    ],
    "envify": "4.1.0 ! inner comment"
  }

그러나 "--save"또는 "--save-dev로 패키지를 업데이트하거나 다시 설치하면"^ 4.1.0! 해당 위치의 주석 "이 삭제됩니다.이 모든 것이 npm 감사를 중단합니다.

JSON에 의견이 없다는 좌절감을 느낍니다. 나는 그들이 참조하는 노드의 이름을 가지지 만 밑줄로 시작하는 새로운 노드를 만듭니다. 이것은 불완전하지만 기능적입니다.

{
  "name": "myapp",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "react": "^16.3.2",
    "react-dom": "^16.3.2",
    "react-scripts": "1.1.4"
  },
  "scripts": {
    "__start": [
        "a note about how the start script works"
    ],
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test --env=jsdom",
    "eject": "react-scripts eject"
  },
  "__proxy": [
    "A note about how proxy works",
    "multilines are easy enough to add"
  ],
  "proxy": "http://server.whatever.com:8000"
}