it-swarm-id.com

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

Saya punya file package.json yang sederhana dan saya ingin menambahkan komentar. Apakah ada cara untuk melakukan ini, atau adakah hack 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.

318
Will Shaver

Ini baru-baru ini telah 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" } 
383
Igor Soarez

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

Setelah menghabiskan satu jam pada solusi kompleks dan peretasan, saya menemukan diri saya solusi yang cukup sederhana, elegan 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 diurutkan 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.

58
gkond

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 ini menggunakan beberapa kunci "//", yang menyiratkan bahwa npm tidak menolak file JSON dengan kunci duplikat. Dengan kata lain, retasan di atas harus selalu baik-baik saja.

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

Retas "//" masih tampak paling aman. Namun, komentar multi-baris juga akan dihapus oleh npm install --save.

14
Philipp Claßen

NPS (Node Package Scripts) menyelesaikan masalah ini untuk saya. Memungkinkan Anda menempatkan skrip NPM Anda ke dalam 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.js dari 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 npm install nps -save-dev lokal dan meletakkannya di skrip package.json saya.

"scripts": {
    "start": "nps",
    "test": "nps test"
}
11
Jim Doyle

Saya punya ide hack yang lucu.

Buat nama paket npm sesuai sebagai pembagi komentar untuk dependencies dan devDependencies di package.json, misalnya 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: Harus menambahkan baris pembagi komentar terakhir dengan versi yang valid seperti * di blokir.

8
Liao San Kai

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

Saya memiliki package.json.js yang berisi skrip yang mengekspor package.json yang sebenarnya. Menjalankan skrip menimpa package.json lama dan memberi tahu saya perubahan apa yang dibuatnya, sempurna untuk membantu Anda melacak perubahan otomatis npm yang 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

5
MarZab

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

Edit Respons awal menempatkan deskripsi di sebelah kanan menggunakan # add comments here untuk membungkusnya; namun, ini tidak berfungsi di 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 menjalankan npm run myframework -- --help 
  4. Akan menampilkan info yang bermakna saat menjalankan 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 sadar 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 less atau IDE favorit Anda)
5
Marc Trudel

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

4
Felipe N Moura

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

Ketika 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 dalam dependencies ia mengeluh mengharapkan nilai string.

0
Clemens Tolboom

Peretasan lagi. Saya membuat skrip untuk membaca package.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
forforf

Saya berakhir dengan scripts seperti 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.

0
maxime1992