web-dev-qa-db-ja.com

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が壊れたときには機能しません。 //スタイルのコメントも試しました。

commentsnpm
341
Will Shaver

これは最近 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" }
403
Igor Soarez

JSONにコメントを追加するためのもう1つのハックです。以来：

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

と同等です

{"a": 2}

次のようなことができます。

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

複雑でハッキーな解決策を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"
  }
}

同じ方法でソートすると、package.jsonを使って作業している間に、git commit diffまたはエディタで、これらの依存関係/コメントのペアを追跡することが非常に簡単になりました。

追加のツールは必要ありません。単純で有効なJSONだけです。

これが誰にでも役立つことを願っています。

73
gkond

重複したキーが上書きされるという事実をいつでも悪用することができます。これは私がちょうど書いたものです：

"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によって削除されます。

15
Philipp Claßen

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

私のプロジェクトの1つからの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"
}
13
Jim Doyle

面白いハックのアイデアがあります。

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

NOTE：最後のコメント区切り行に*のような有効なバージョンをブロックで追加する必要があります。

9
Liao San Kai

たくさんの面白いアイデアがあります。

私がやっているのはこれです：

{
  ...
  "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セント：）

8
Felipe N Moura

これまでのところ、ここでのほとんどの「ハック」は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. クロスプラットフォームで動作します（Linuxでは問題なく動作すると想定して、macOSとWindowsでテスト済み）。
  3. npm run myframework -- --helpの実行の邪魔にならない
  4. npm runを実行するときに意味のある情報を出力します（利用可能なスクリプトに関する情報を取得するために実行する実際のコマンドです）。
  5. より明確なhelpコマンドを提示します（npm runがそのような出力を提示することを一部の開発者が認識していない場合）。
  6. コマンド自体を実行すると、コマンドとその説明の両方が表示されます。
  7. package.jsonを開いたときにやや読みやすくなります（lessまたはあなたの好きなIDEを使って）
6
Marc Trudel

これがpackage.json/bower.json内のコメントです。

実際のpackage.json.jsをエクスポートするスクリプトを含むpackage.jsonがあります。スクリプトを実行すると古いpackage.jsonが上書きされ、それが行った変更が表示されます。npmが自動変更したことを追跡するのに役立ちます。こうすれば、どのパッケージを使いたいかをプログラム的に定義することさえできます。

最新の不気味な仕事はここにあります： https://Gist.github.com/MarZab/72fa6b85bc9e71de5991

5
MarZab

このスレッドに触発された、これが私たちが使っているものです：

{
  "//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"
  }
}
2
thisismydesign

私はそのような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といった大ファンではありませんが、キーは異なり、まったく問題ありません。

1
maxime1992

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内では文字列値が必要です。

0
Clemens Tolboom

もう一つのハック。ハンドルバーテンプレートのコンテキストとして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"

}}}
0
forforf

この回答 で説明しているように、//キーは予約されていたため、従来どおりコメントに使用できます。 //コメントの問題は、バージョン制約として文字列を使用する通常の依存関係として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以前）と互換性があります。

0
Estus Flask