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": "*"
  }
}

複雑でハッキーなソリューションに1時間費やした後、私はのかさばる依存関係セクションにコメントするためのシンプルで有効なソリューションを見つけました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 diffまたはエディターでこれらの依存関係/コメントのペアを追跡するのが非常に簡単になりました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

この議論のための私の2セント:)

NPS（Node Package Scripts）は私のためにこの問題を解決しました。NPMスクリプトを別のJSファイルに入れて、コメントやその他の必要なJSロジックを追加できます。 https://www.npmjs.com/package/nps

package-scripts.js私のプロジェクトの1 つからのサンプル

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構文でオブジェクトの重複キーを許可していますか？を参照してください） 。

推奨されるハックは、"//"（nodejsメーリングリストの）キーを使用することです。テストしたところ、「依存関係」セクションでは機能しませんでした。また、投稿の例では複数の"//"キーを使用しています。これは、npmが重複したキーを持つJSONファイルを拒否しないことを意味します。言い換えれば、上記のハックは常に問題ないはずです。

更新：重複したキーハックの厄介な欠点の1つは、npm install --saveすべての重複静かに排除することです。残念ながら、見落とすのは非常に簡単で、意図的なコメントは消えてしまいます。

"//"それはそうとハックはまだ最も安全です。ただし、複数行のコメントはnpm install --saveます。

私は面白いハックのアイデアを持っています。

たとえば、package.jsonのコメント区切りdependenciesおよびdevDependenciesブロックとしてnpmパッケージ名を適切に作成します。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それをラップするために使用して右側に説明を入れていました。ただし、これはWindowsでは機能しません。フラグ（たとえば、npm run myframework---myframework-flags）が無視されるためです。すべてのプラットフォームで機能するように応答を変更し、読みやすくするためにインデントをいくつか追加しました。

{
 "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行ったれます。行われた。そうすれば、使用したいパッケージをプログラムで定義することもできます。

最新のうなり声タスクはこちらです：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"
  },

ここでの目的は、1行を明確にすることではなく、バックエンド、フロントエンド、すべてなどのスクリプト間に区切り文字を配置することです。

私は1a、1b、1c、2aなどの大ファンではありませんが、キーは異なり、まったく問題ありません。

この答えは説明して、//キーが予約されていたので、コメントに従来から使用することができます。問題//のコメントは、それが中で使用することができないということですdependenciesとdevDependencies、バージョン制約として文字列との定期的な依存関係として：

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

エラーをトリガーし、

npm ERR！コードEINVALIDPACKAGENAME

npm ERR！無効なパッケージ名 "//"：名前には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以来、などのセクション、コメントのアノテーションは、直接設定オブジェクト内の個々のパッケージの依存関係の上に追加することができないnpmキーがNPMパッケージの名前であることを期待しています。したがって、の理由@comment dependencies。

注：スクリプトオブジェクトなどの特定のコンテキストでは、一部のエディター/ 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は2つの方法を見つけました（この会話を読んだ後）：

  "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"
}