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


380

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.



17
@YehudaKatz - Saya rasa ini bukan duplikat karena pertanyaan ini khusus untuk package.jsonfile dan ada package.jsonjawaban spesifik pada milis NodeJS.
Mark Evans

2
Salah satu pengembang npm inti telah menolak untuk mempertimbangkan dukungan komentar di package.json. Silakan mengomentari masalah itu - mungkin kita dapat menunjukkan seberapa bermanfaat komentar tersebut.
Dan Dascalescu

5
Satu tag tunggal <sarkasme />. JSON5 mendukung komentar json5.org
Cristian E.

Jawaban:


450

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

58
Adakah cara untuk mendokumentasikan setiap entri di bagian 'dependensi'? trik "//" tidak berfungsi ketika itu merupakan 'ketergantungan'.
rynop

8
Perhatikan bahwa menggunakan banyak komentar seperti dalam contoh pertama { "//": "first", "//": "second"}mencegah Anda menggunakan npm versiondan utilitas baris perintah lainnya yang biasanya mem-reparse seluruh JSON dan membuang kunci duplikat dalam proses.
jakub.g

60
Salah satu harus menyadari bahwa "//" hanya dapat digunakan pada akar dari package.jsonobjek. Misalnya { "dependencies": { "//": "comment?" }}tidak valid tetapi { "//": "comment!", "dependencies":{}}valid.
david_p

52
Bahkan Douglas Crockford tidak memiliki masalah dengan menempatkan komentar dalam file konfigurasi JSON. Situasi dengan NPM konyol untuk sedikitnya.
Muhammad Rehan Saeed

5
dalam pengalaman saya "//"kunci dan nilainya akhirnya bisa dihapus. apakah ada cara untuk memiliki komentar permanen?
Pruett

116

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

12
Ini juga berfungsi pada tingkat paket tertentu. Sebagai contoh. "express": "makes routing better so I don't want to gouge my eyes out", "express": "3.x". Jadi, ya, "huek" seperti kata ColinE, dan juga "terima kasih" seperti kata ColinE.
juanpaco

22
Perhatikan bahwa peretasan ini mencegah Anda dari pernah mengubah package.jsondalam cara yang terprogram, katakan dengan npm version 1.2.3menabrak versi - entri yang berlebihan akan dihapus dari JSON yang dihasilkan.
jakub.g

16
Ini saran yang buruk, karena urutan objek diartikan tidak dijamin. Misalnya, dalam beberapa situasi, contoh Anda mungkin berakhir dengan makhluk 1 bukannya 2.
Jo Sprague

6
@mpen Resikonya adalah tidak ada jaminan bahwa kode yang menguraikan JSON akan melakukannya secara berurutan.
Jo Sprague

7
Sebagai catatan, RFC secara eksplisit mengatakan: "Ketika nama-nama dalam suatu objek tidak unik, perilaku perangkat lunak yang menerima objek seperti itu tidak dapat diprediksi. Banyak implementasi melaporkan hanya nama / pasangan nilai saja. Implementasi lainnya melaporkan kesalahan atau kegagalan untuk mem-parsing objek, dan beberapa implementasi melaporkan semua pasangan nama / nilai, termasuk duplikat. "
Alan Tam

106

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.


1
Dengan cara ini lebih masuk akal dan menjaga kebersihan.
Hitesh Sahu

4
Terima kasih atas solusi non-hacky yang secara teknis valid dan semantik bermanfaat.
Roy Tinker

5
Untuk komentar tentang skrip, mengapa tidak memberikan skrip "bantuan", misalnya "scripts": { "postinstall": "echo postinstall stuff goes here", "help-postinstall": "echo helpful stuff goes here" }
puncak

1
@ bicara terima kasih! Satu-satunya downside yang saya lihat adalah bahwa skrip aktual akan dicampur dengan komentar.
gkond

1
@gkond terima kasih untuk ini. Masuk akal bagiku.
Robin Winslow

20

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 :)


pintar, saya suka
KorreyD

14

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

13

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.


1
The "//"hack tidak bekerja di dalam devDependencies. NPM mencoba menyelesaikan jalur UNC.
Dmitry S.

Terima kasih telah memperbarui kalimat tetapi sekali lagi itu tidak dapat mengomentari mochaatribut. Hanya dapat menambahkan lebih dari satu dan akan digunakan oleh npm pada akhirnya.
vusan

Aku benci mengakuinya - tapi aku suka ini lebih baik daripada "//"
roocell

9

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.


6
yay, sebenarnya tersedia: npmjs.com/package/x----x----x
revelt

9
npm installSenang tentang jawaban ini tetapi setelah saya berlari (menggunakan npm 5) kunci duplikat saya secara otomatis dihapus :(
Eric Majerus

@EricMajerus oops ~, npm5 menghancurkan hatiku juga :(
Liao San Kai

8

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

7

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)

Argh, sebenarnya pada Windows itu hanya akan mengabaikan bendera, jadi 3. tidak benar: /
Marc Trudel

Jadikan windows cmd kompatibel dengan: &&alih-alih ;demikian perintah pertama menjadi:"help": "echo 'Display help information (this screen)' && npm run",
phil_lgr

1
Ya, itulah yang akhirnya saya lakukan. Tangkapan yang bagus!
Marc Trudel

3
Ini hanya berfungsi di scriptsbagian ini. package.jsonAda banyak hal lain.
Rolf

Benar. Kemudian lagi, apa lagi yang Anda rasakan perlu didokumentasikan di sana?
Marc Trudel

6

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 pikir ini adalah jawaban yang "benar" dalam banyak hal (tugas untuk menghapus komentar dengan penambalan yang berbeda untuk memperhitungkan perubahan pasca-strip) - namun, saya mendapatkan pengertian bahwa bobot tambahan dari tugas kasar bukanlah apa yang dilakukan sebagian orang. setelah, Untuk proyek-proyek kecil, mungkin yang terbaik untuk menyimpan file eksternal untuk komentar dan menggunakan NPM scrpts (menghindari tugas membangun sama sekali). Untuk proyek-proyek besar, Anda mungkin menggunakan beberapa bentuk pelari tugas, jadi pendekatan ini tampaknya solid. Di antara keduanya, saya pikir mungkin mengadaptasi saran "//" secukupnya (menghindari titik rasa sakit seseorang) adalah yang terbaik yang bisa dilakukan.
Enull

1
Saya suka ide ini, tetapi sebagai seseorang bertanya pada intinya, apa tentang kasus di mana Anda memodifikasi package.json asli melalui npm install --saveatau --save-dev?
Isochronous

ya saya terus melewatkan komentar itu; tidak ada solusi yang baik, saya biasa melihat git diffs dan memperbarui file .js saya setelah memperbarui
MarZab

1

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.


1

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).


1

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.


1

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.


0

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.


ya b / c Anda tidak bisa benar-benar tetapi //kuncinya di mana-mana, itu bukan pengganti yang baik untuk komentar, terutama ketika komentar dapat memiliki sintaksis yang bagus dengan editor dll.
Alexander Mills

0

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"

}}}

0

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.


tidakkah ini mencoba menginstal paket yang bernama del-commentdan envify-comment?
Beni Cherniavsky-Paskin

-1

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

menggunakan start_commentakan lebih baik, karena dengan begitu ia akan memesan sesuai abjad
Alexander Mills
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.