Comment ajouter des commentaires à package.json pour l'installation de npm?

J'ai un simple fichier package.json et je veux ajouter un commentaire. Existe-t-il un moyen de le faire, ou existe-t-il des hacks pour que cela fonctionne?

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

L'exemple de commentaire ci-dessus ne fonctionne pas lors des interruptions npm. J'ai également essayé des commentaires de style //.

Cela a récemment été discuté dans la liste de diffusion Node.js .

Selon Isaac Schlueter qui a créé npm:

... la clé "//" ne sera jamais utilisée par npm à quelque fin que ce soit et est réservée aux commentaires ... Si vous souhaitez utiliser un commentaire sur plusieurs lignes, vous pouvez utiliser soit un tableau, soit plusieurs "//" clés.

Lorsque vous utilisez vos outils habituels (npm, fil, etc.), plusieurs clés "//" seront supprimées. Cela survit:

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

Cela ne survivra pas:

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

Voici un autre hack pour ajouter des commentaires en JSON. Depuis:

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

Est équivalent à

{"a": 2}

Vous pouvez faire quelque chose comme:

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

Après avoir perdu une heure sur des solutions complexes et hacky, j'ai trouvé une solution à la fois simple et valide pour commenter ma section sur les dépendances encombrantes 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"
  }
}

Lorsqu'ils sont triés de la même manière, il est maintenant très facile pour moi de suivre ces paires de dépendances / commentaires dans les différences de validation git ou dans l'éditeur tout en travaillant avec package.json.

Et aucun outil supplémentaire n'est impliqué, juste un JSON simple et valide.

J'espère que cela aide n'importe qui.

Beaucoup d'idées intéressantes.

Ce que je fais, c'est ceci:

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

De cette façon, je peux à la fois lire les "pseudo-commentaires" dans le script lui-même, et également exécuter quelque chose comme ce qui suit, pour voir une sorte d'aide dans le terminal:

npm run about
npm run about:watch

Mes 2cents pour cette discussion :)

NPS (Node Package Scripts) a résolu ce problème pour moi. Vous permet de placer vos scripts NPM dans un fichier JS distinct, où vous pouvez ajouter de nombreux commentaires et toute autre logique JS dont vous avez besoin. https://www.npmjs.com/package/nps

Échantillon de l' package-scripts.jsun 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-devet de mettre cela dans mes package.jsonscripts.

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

Vous pouvez toujours abuser du fait que les clés dupliquées sont écrasées. Voici ce que je viens d'écrire:

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

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

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

Cependant, il n'est pas clair si JSON autorise les clés en double (voir La syntaxe JSON autorise-t - elle les clés en double dans un objet?. Cela semble fonctionner avec npm, donc je prends le risque.

Le hack recommandé est d'utiliser des "//"clés (de la liste de diffusion nodejs ). Quand je l'ai testé, cela ne fonctionnait pas avec les sections "dépendances". En outre, l'exemple de la publication utilise plusieurs "//"clés, ce qui implique que npm ne rejette pas les fichiers JSON avec des clés dupliquées. En d'autres termes, le hack ci-dessus devrait toujours être correct.

Mise à jour: Un inconvénient ennuyeux du hack de clé dupliqué est qu'il npm install --saveélimine silencieusement tous les doublons. Malheureusement, il est très facile de l'oublier et vos commentaires bien intentionnés ont disparu.

Le "//"hack est toujours le plus sûr qu'il n'y paraît. Cependant, les commentaires sur plusieurs lignes seront également supprimés par npm install --save.

J'ai une drôle d'idée de hack.

Créez le nom du package npm de manière appropriée comme diviseur de commentaires pour dependencieset devDependenciesbloquez dans package.json, par exemplex----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": "*"
    }
}

REMARQUE : Doit ajouter la dernière ligne de séparation des commentaires avec une version valide comme *dans le bloc.

Inspiré par ce fil, voici ce que nous utilisons :

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

Jusqu'à présent, la plupart des "hacks" suggèrent ici d'abuser de JSON. Mais au lieu de cela, pourquoi ne pas abuser du langage de script sous-jacent?

Modifier La réponse initiale consistait à mettre la description à droite en utilisant # add comments herepour la boucler; cependant, cela ne fonctionne pas sous Windows, car les indicateurs (par exemple, npm exécutent myframework - --myframework-flags) seraient ignorés. J'ai changé ma réponse pour la faire fonctionner sur toutes les plates-formes, et ajouté quelques retraits à des fins de lisibilité.

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

Cette volonté:

1. Ne pas casser la conformité JSON (ou du moins ce n'est pas un piratage, et votre IDE ne vous donnera pas d'avertissement pour faire des choses étranges et dangereuses)
2. Fonctionne sur plusieurs plates-formes (testé sur macOS et Windows, en supposant que cela fonctionnerait très bien sur Linux)
3. Ne gêne pas la course npm run myframework -- --help
4. Fournira des informations significatives lors de l'exécution npm run(qui est la commande réelle à exécuter pour obtenir des informations sur les scripts disponibles)
5. Présente une commande d'aide plus explicite (au cas où certains développeurs ne seraient pas conscients que npm run présente une telle sortie)
6. Affiche les commandes ET sa description lors de l'exécution de la commande elle-même
7. Est quelque peu lisible lors de l'ouverture package.json(en utilisant lessou votre IDE préféré)

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

J'ai package.json.jsqui contient un script qui exporte le réel package.json. L'exécution du script écrase l'ancien package.jsonet me dit quelles modifications il a apportées, parfait pour vous aider à garder une trace des modifications automatiques apportées npm. De cette façon, je peux même définir par programme les packages que je veux utiliser.

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

Je me suis retrouvé avec un scriptscomme ç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 clarifier une ligne, juste d'avoir des délimiteurs entre mes scripts pour le backend, le frontend, tout, etc.

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

Comme l' explique cette réponse , la //clé était réservée, elle peut donc être utilisée de manière conventionnelle pour les commentaires. Le problème avec le //commentaire est qu'il ne peut pas être utilisé dans dependencieset en devDependenciestant que dépendance régulière avec une chaîne comme contrainte de version:

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

déclenche une erreur,

npm ERR! code EINVALIDPACKAGENAME

npm ERR! Nom de package non valide "//": le nom ne peut contenir que des caractères compatibles avec les URL

Bien que les clés avec des valeurs non-chaîne soient considérées comme des dépendances non valides et efficacement ignorées:

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

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

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

Étant donné que les dépendances sont triées lorsque package.json est modifié par NPM, il est impossible de placer un commentaire au-dessus d'une dépendance à laquelle il fait référence:

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

La clé de commentaire doit être nommée en conséquence si elle fait référence à une ligne spécifique, elle ne sera donc pas déplacée:

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

Un commentaire applicable à une dépendance spécifique peut être ajouté dans le cadre de semver:

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

Notez que si la première partie précédente ORne correspond pas, un commentaire peut être analysé, par exemple 1.x.

Ces solutions de contournement sont compatibles avec toutes les versions actuelles de NPM (6 et inférieures).

Comme la plupart des développeurs connaissent la documentation basée sur les balises / annotations, la convention que j'ai commencé à utiliser est similaire. Voici un avant-goût:

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

Note: Pour les dependencies, devDependencies, etc sections, les annotations de commentaires ne peut pas être ajouté directement au- dessus des dépendances de package individuels à l' intérieur de l'objet de configuration depuis npms'attend à la clé d'être le nom d'un paquet NPM. D'où la raison de la @comment dependencies.

Remarque: Dans certains contextes, comme dans l'objet scripts, certains éditeurs / IDE peuvent se plaindre du tableau. Dans le contexte des scripts, VS Code attend une chaîne pour la valeur - pas un tableau.

J'aime la manière d'annotation / style de balise d'ajouter des commentaires à JSON parce que le @symbole se démarque des déclarations normales.

Pour résumer toutes ces réponses:

1. Ajoutez un seul champ de niveau supérieur appelé //qui contient une chaîne de commentaire. Cela fonctionne mais ça craint parce que vous ne pouvez pas mettre des commentaires près de la chose qu'ils commentent.

2. Ajoutez plusieurs champs de niveau supérieur commençant par // , par exemple, //dependenciesqui contiennent une chaîne de commentaire. C'est mieux, mais cela ne vous permet toujours de faire des commentaires de haut niveau. Vous ne pouvez pas commenter les dépendances individuelles.

3. Ajoutez des echocommandes à votre scripts. Cela fonctionne mais ça craint parce que vous ne pouvez l'utiliser que dans scripts.

Ces solutions sont également toutes peu lisibles. Ils ajoutent une tonne de bruit visuel et les IDE ne les mettent pas en surbrillance en tant que commentaires.

Je pense que la seule solution raisonnable est de générer le à package.jsonpartir d'un autre fichier. Le moyen le plus simple est d'écrire votre JSON en Javascript et d'utiliser Node pour l'écrire package.json. Enregistrez ce fichier sous package.json.mjs, chmod +xil, puis vous pouvez simplement l'exécuter pour générer votre 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));

Il utilise la //clé pour avertir les gens de ne pas le modifier. \x40generatedest délibéré. Il se transforme en @generatedin package.jsonet signifie que certains systèmes de révision de code réduisent ce fichier par défaut.

C'est une étape supplémentaire dans votre système de construction, mais elle bat tous les autres hacks ici.

Comme les clés de commentaires en double sont supprimées en exécutant les outils package.json (npm, fil, etc.), j'en suis venu à utiliser une version hachée qui permet une meilleure lecture sous forme de plusieurs lignes et clés comme

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

qui est «valide» selon mon IDE en tant que clé racine, mais en dependenciesson sein se plaint d'attendre une valeur de chaîne.

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

Code ci-dessous au cas où quelqu'un trouverait 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;
  });
});

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

}}}

Pour npm package.json ont trouvé 2 façons (après avoir lu cette conversation):

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

Mais avec la mise à jour ou la réinstallation du paquet avec "--save" ou "--save-dev, commentez comme" ^ 4.1.0! commentaire "à l'endroit correspondant sera supprimé. Et tout cela cassera l'audit npm.

Mon point de vue sur la frustration de l'absence de commentaires dans JSON. Je crée de nouveaux nœuds, nommés d'après les nœuds auxquels ils se réfèrent, mais préfixés par des traits de soulignement. C'est imparfait, mais fonctionnel.

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