Comment puis-je ajouter des commentaires sur l'emballage.json pour npm install?

Cela a récemment été discuté dans le node.js liste de diffusion.

Selon Isaac Schlueter qui a créé mnp:

... le "//" clé ne sera jamais utilisé par npm pour n'importe quel but, et est réservé pour les commentaires ... Si vous voulez utiliser un multiple de la ligne de commentaire, vous pouvez utiliser soit un tableau, ou plusieurs "//" les clés.

Lors de l'utilisation de vos outils habituels (mnp, fil, etc), plusieurs "//" les clés seront supprimés. Cette survit:

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

Ce ne survivra pas:

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

Après perdre une heure sur complexe et hacky solutions que j'ai trouvé à la fois simple et solution valable pour les commentaires de mes encombrants à la section des dépendances dans package.json. Juste comme ça:

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

Quand triées de la même façon, il est maintenant très facile pour moi de suivre ces paires de dépendances/commentaires git commit diffs ou dans l'éditeur tout en travaillant avec package.json.

Et aucun outil supplémentaire impliqué, juste simple et JSON valide.

Espère que cela aide quelqu'un.

NPS (Node Package Scripts) a résolu ce problème pour moi. Vous permet de mettre votre MNP scripts dans un fichier JS, où vous pouvez ajouter des commentaires à gogo et tout autre JS logique vous en avez besoin.
https://www.npmjs.com/package/nps

Échantillon de la package-scripts.js de l'un de mes projets

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

Je viens de faire une installation locale npm install nps -save-dev et mettre ça dans ma package.json scripts.

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

De nombreuses idées intéressantes.

Ce que je fais est-ce:

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

Cette façon, je peux lire le "pseudo-commentaires" dans le script lui-même, mais aussi d'exécuter quelque chose comme ce qui suit, voir d'une certaine aide dans le terminal:

npm run about
npm run about:watch

Mes 2cents pour cette discussion 🙂

Voici mon point de vue sur les commentaires dans les package.json /bower.json:

J'ai package.json.js qui contient un script que les exportations réelles package.json. Exécute le script remplace le vieux package.json et me dit qu'changements qu'il a faits, parfaite pour vous aider à garder la trace des modifications automatiques npm fait. De cette façon, je peux même en programmant définir des paquets que je veux utiliser.

La dernière tâche grunt est ici:
https://gist.github.com/MarZab/72fa6b85bc9e71de5991

J'ai fini avec un scripts comme ça:

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

Mon intention ici n'est pas de préciser une ligne, juste pour avoir une sorte de délimiteurs entre mes scripts pour le backend, frontend, tous, etc.

Je ne suis pas un grand fan de 1a, 1b, 1c, 2a, ..., mais les touches sont différentes et je n'ai pas de problème du tout comme ça.

Un autre hack. J'ai créé un script pour lire package.json comme contexte pour un guidon de modèle.

Code ci-dessous dans le cas où quelqu'un trouve cette approche utile:

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

guidon fichier de modèle 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"

}}}

Comme cette réponse explique, // clé a été réservé, de sorte qu'il peut être utilisé classiquement pour les commentaires. Le problème avec // commentaire, c'est qu'il ne peut pas être utilisé dans dependencies et devDependencies régulière de dépendance avec une chaîne de caractères comme une version contrainte:

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

déclenche une erreur,

mnp ERR! code EINVALIDPACKAGENAME

mnp ERR! Invalide nom du package "//": le nom ne peut contenir que des URL-friendly
caractères

Si les touches avec les non-valeurs de chaîne sont considérés comme non valides dépendances et efficacement ignoré:

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

Une dépendance elle-même peut être commenté de la même manière:

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

Depuis les dépendances sont classés lors de l'emballage.json est modifiée par NPM, il est impossible de placer un commentaire au-dessus d'une dépendance, il se réfère:

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

Commentaire clé doit être nommée en conséquence, lorsqu'il se réfère à des de ligne, donc il n'est pas déplacé:

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

Un commentaire qui est applicable aux dépendance peut être ajouté comme partie de semver:

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

Avis que si la première partie avant de OR ne correspond pas, un commentaire peut être analysé, par exemple,1.x.

Ces solutions sont compatibles avec tous les MNP versions (6 et inférieur).