Bagaimana cara menambahkan komentar ke package.json untuk instal npm?

Saya punya file package.json yang sederhana dan saya ingin menambahkan komentar. Apakah ada cara untuk melakukan ini, atau apakah ada peretasan untuk membuat ini berfungsi?

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

Contoh komentar di atas tidak berfungsi sebagai npm break. Saya juga sudah mencoba // style comment.

Ini baru-baru ini dibahas di milis node.js .

Menurut Isaac Schlueter yang menciptakan npm:

... kunci "//" tidak akan pernah digunakan oleh npm untuk tujuan apa pun, dan dicadangkan untuk komentar ... Jika Anda ingin menggunakan beberapa komentar baris, Anda dapat menggunakan array, atau beberapa "//" kunci.

Saat menggunakan alat Anda yang biasa (npm, benang, dll) beberapa "//" kunci akan dihapus. Ini bertahan:

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

Ini tidak akan bertahan:

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

Berikut ini hack lain untuk menambahkan komentar di JSON. Sejak:

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

Setara dengan

{"a": 2}

Anda dapat melakukan sesuatu seperti:

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

Setelah menghabiskan satu jam pada solusi kompleks dan hacky, saya telah menemukan solusi sederhana dan valid untuk mengomentari bagian dependensi besar saya di package.json. Seperti ini:

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

Ketika disortir dengan cara yang sama, sekarang sangat mudah bagi saya untuk melacak pasangan dependensi / komentar ini baik di git commit diffs atau di editor saat bekerja dengan package.json.

Dan tidak ada alat tambahan yang terlibat, JSON sederhana dan valid.

Semoga ini bisa membantu siapa saja.

Banyak ide menarik.

Apa yang saya lakukan adalah ini:

{
  ...
  "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",
  }
  ...
}

Dengan cara ini saya bisa membaca "pseudo-comments" dalam skrip itu sendiri, DAN juga menjalankan sesuatu seperti berikut, untuk melihat beberapa jenis bantuan di terminal:

npm run about
npm run about:watch

2 sen saya untuk diskusi ini :)

NPS (Node Package Scripts) menyelesaikan masalah ini untuk saya. Memungkinkan Anda menempatkan skrip NPM ke file JS yang terpisah, tempat Anda dapat menambahkan banyak komentar dan logika JS lainnya yang Anda perlukan. https://www.npmjs.com/package/nps

Contoh package-scripts.jsdari salah satu proyek saya

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

Saya baru saja menginstal lokal npm install nps -save-devdan meletakkannya di package.jsonskrip saya .

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

Anda selalu dapat menyalahgunakan fakta bahwa kunci duplikat ditimpa. Inilah yang baru saja saya tulis:

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

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

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

Namun, tidak jelas apakah JSON mengizinkan kunci duplikat (lihat Apakah sintaks JSON memungkinkan kunci duplikat dalam suatu objek? Tampaknya berfungsi dengan npm, jadi saya mengambil risiko.

Peretasan yang disarankan adalah menggunakan "//"kunci (dari milis nodejs ). Ketika saya mengujinya, itu tidak bekerja dengan bagian "dependensi". Juga, contoh dalam posting menggunakan banyak"//" kunci, yang menyiratkan bahwa npm tidak menolak file JSON dengan kunci duplikat. Dengan kata lain, retasan di atas harus selalu baik-baik saja.

Pembaruan: Salah satu kelemahan menjengkelkan dari peretasan kunci duplikat adalah itunpm install --save diam diam menghilangkan semua duplikat. Sayangnya, sangat mudah untuk mengabaikannya dan komentar Anda yang bermaksud baik hilang.

The "//"hack masih paling aman seperti yang tampak. Namun, komentar multi-baris juga akan dihapus npm install --save.

Saya punya ide hack yang lucu.

Buat nama paket npm yang sesuai sebagai pembagi komentar dependenciesdan devDependenciesblokir di package.json, misalnyax----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": "*"
    }
}

CATATAN : Harus menambahkan baris pembagi komentar terakhir dengan versi yang valid seperti *di blokir.

Terinspirasi oleh utas ini, inilah yang kami gunakan :

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

Sejauh ini, sebagian besar "peretasan" di sini menyarankan untuk menyalahgunakan JSON. Namun, mengapa tidak menyalahgunakan bahasa skrip yang mendasarinya?

Sunting Respons awal menempatkan deskripsi di sebelah kanan gunakan # add comments hereuntuk membungkusnya; namun, ini tidak berfungsi pada Windows, karena flag (mis. npm menjalankan myframework - --myframework-flags) akan diabaikan. Saya mengubah respons saya untuk membuatnya berfungsi di semua platform, dan menambahkan beberapa indentasi untuk tujuan keterbacaan.

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

Ini akan:

1. Tidak melanggar kepatuhan JSON (atau setidaknya ini bukan peretasan, dan IDE Anda tidak akan memberi Anda peringatan karena melakukan hal-hal aneh dan berbahaya)
2. Bekerja lintas platform (diuji pada macOS dan windows, dengan asumsi itu akan berfungsi dengan baik di Linux)
3. Tidak menghalangi jalan npm run myframework -- --help
4. Akan menampilkan info yang bermakna saat berjalan npm run (yang merupakan perintah aktual untuk menjalankan untuk mendapatkan informasi tentang skrip yang tersedia)
5. Menyajikan perintah bantuan yang lebih eksplisit (kalau-kalau beberapa devs tidak menyadari bahwa npm run menyajikan output seperti itu)
6. Akan menampilkan kedua perintah DAN deskripsinya saat menjalankan perintah itu sendiri
7. Agak dapat dibaca ketika hanya membuka package.json(menggunakan lessatau IDE favorit Anda)

Inilah komentar saya di dalam package.json/bower.json :

Saya punya package.json.jsyang berisi skrip yang mengekspor yang sebenarnya package.json. Menjalankan skrip menimpa yang lama package.jsondan memberi tahu saya perubahan apa yang dibuatnya, sempurna untuk membantu Anda melacak perubahan otomatisnpm dibuat. Dengan begitu saya bahkan dapat secara program menentukan paket apa yang ingin saya gunakan.

Tugas kasar terbaru ada di sini: https://gist.github.com/MarZab/72fa6b85bc9e71de5991

Saya berakhir dengan scriptsseperti itu:

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

Maksud saya di sini bukan untuk memperjelas satu baris, hanya untuk memiliki semacam pembatas antara skrip saya untuk backend, frontend, semua, dll.

Saya bukan penggemar berat 1a, 1b, 1c, 2a, ... tapi kuncinya berbeda dan saya tidak punya masalah sama sekali seperti itu.

Saat jawaban ini menjelaskan, //kunci dicadangkan, sehingga dapat digunakan secara konvensional untuk komentar. Masalah dengan //komentar adalah bahwa itu tidak dapat digunakan dalam dependenciesdan devDependenciessebagai ketergantungan reguler dengan string sebagai batasan versi:

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

memicu kesalahan,

npm ERR! kode EINVALIDPACKAGENAME

npm ERR! Nama paket "//" tidak valid: nama hanya dapat berisi karakter yang ramah-URL

Meskipun kunci dengan nilai non-string dianggap dependensi tidak valid dan diabaikan secara efisien:

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

Ketergantungan itu sendiri dapat dikomentari dengan cara yang sama:

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

Karena dependensi diurutkan ketika package.json dimodifikasi oleh NPM, tidak praktis untuk menempatkan komentar di atas dependensi yang dimaksud:

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

Kunci komentar harus dinamai sesuai jika mengacu pada baris tertentu, sehingga tidak akan dipindahkan:

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

Sebuah komentar yang berlaku untuk ketergantungan khusus dapat ditambahkan sebagai bagian dari semver:

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

Perhatikan bahwa jika bagian pertama sebelumnya ORtidak cocok, komentar dapat diuraikan, misalnya1.x .

Penanganan masalah ini kompatibel dengan semua versi NPM saat ini (6 dan lebih rendah).

Karena sebagian besar pengembang akrab dengan dokumentasi berbasis tag / anotasi, konvensi yang sudah mulai saya gunakan adalah serupa. Berikut ini rasanya:

{
  "@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": "..."
  }
}

Catatan: Untuk bagian dependencies,, devDependenciesdll., Anotasi komentar tidak dapat ditambahkan langsung di atas dependensi paket individual di dalam objek konfigurasi karenanpm mengharapkan kunci untuk menjadi nama paket npm. Karenanya alasan untuk @comment dependencies.

Catatan: Dalam konteks tertentu, seperti dalam objek skrip, beberapa editor / IDE mungkin mengeluh tentang array. Dalam konteks skrip, VS Code mengharapkan string untuk nilai - bukan array.

Saya suka cara penjelasan / gaya tag menambahkan komentar ke JSON karena @simbol menonjol dari deklarasi normal.

Untuk merangkum semua jawaban ini:

1. Tambahkan bidang tingkat atas tunggal yang disebut //yang berisi string komentar. Ini berfungsi tetapi menyebalkan karena Anda tidak dapat memberikan komentar di dekat hal yang mereka komentari.

2. Tambahkan beberapa bidang tingkat atas yang dimulai dengan // , misalnya //dependenciesyang berisi string komentar. Ini lebih baik tetapi masih hanya memungkinkan Anda untuk membuat komentar tingkat atas. Anda tidak dapat berkomentar ketergantungan individu.

3. Tambahkan echoperintah ke scripts. Ini berfungsi tetapi menyebalkan karena Anda hanya dapat menggunakannya dalam scripts.

Semua solusi ini juga tidak terlalu mudah dibaca. Mereka menambahkan satu ton kebisingan visual dan IDE tidak akan menyorotnya sebagai komentar.

Saya pikir satu-satunya solusi yang masuk akal adalah menghasilkan package.jsondari file lain. Cara paling sederhana adalah menulis JSON sebagai Javascript dan menggunakan Node untuk menulisnya package.json. Simpan file ini sebagai package.json.mjs, chmod +xitu, dan kemudian Anda bisa menjalankannya untuk menghasilkan 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));

Itu menggunakan //kunci untuk memperingatkan orang dari mengeditnya. \x40generateddisengaja. Itu berubah menjadi @generateddipackage.json dan berarti beberapa sistem kode review akan runtuh file yang secara default.

Ini adalah langkah ekstra dalam sistem build Anda, tetapi ini mengalahkan semua peretasan lainnya di sini.

Karena kunci komentar duplikat dihapus menjalankan alat package.json (npm, benang, dll) saya menggunakan versi hash yang memungkinkan untuk membaca lebih baik karena banyak baris dan kunci seperti

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

yang 'valid' menurut IDE saya sebagai kunci root, tetapi di dependenciesdalamnya mengeluh mengharapkan nilai string.

Peretasan lagi. Saya membuat skrip untuk dibacapackage.json sebagai konteks untuk template setang.

Kode di bawah ini dalam kasus seseorang menemukan pendekatan ini berguna:

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;
  });
});

file template setang 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"

}}}

Untuk npm package.json telah menemukan 2 cara (setelah membaca percakapan ini):

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

Tetapi dengan pembaruan atau instal ulang paket dengan "--save" atau "--save-dev, komentar seperti" ^ 4.1.0! komentar "di tempat yang sesuai akan dihapus. Dan semua ini akan merusak audit npm.

Saya mengambil frustrasi tidak ada komentar di JSON. Saya membuat node baru, dinamai untuk node yang mereka rujuk, tetapi diawali dengan garis bawah. Ini tidak sempurna, tetapi fungsional.

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