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


380

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



17
@YehudaKatz - Je ne pense pas que ce soit un doublon dans la mesure où cette question est spécifique aux package.jsonfichiers et qu'il existe une package.jsonréponse spécifique sur la liste de diffusion NodeJS.
Mark Evans

2
L'un des principaux développeurs de npm a refusé d'envisager la prise en charge des commentaires dans package.json. Veuillez commenter cette question - nous pourrons peut-être montrer à quel point les commentaires peuvent être utiles.
Dan Dascalescu

5
Une seule balise <sarcasm />. JSON5 prend en charge les commentaires json5.org
Cristian E.

Réponses:


450

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

58
existe-t-il un moyen de documenter ce que chaque entrée dans la section «dépendances» est? l'astuce "//" ne fonctionne pas quand c'est un attr de 'dépendances'.
rynop

8
Notez que l'utilisation de plusieurs commentaires comme dans le premier exemple { "//": "first", "//": "second"}vous empêche d'utiliser npm versionet d'autres utilitaires de ligne de commande qui analysent généralement le JSON entier et suppriment les clés en double en cours.
jakub.g

60
Il faut savoir que "//" ne peut être utilisé qu'à la racine de l' package.jsonobjet. Par exemple, { "dependencies": { "//": "comment?" }}n'est pas valide mais { "//": "comment!", "dependencies":{}}est valide.
david_p

52
Même Douglas Crockford n'a aucun problème à mettre des commentaires dans des fichiers de configuration JSON. La situation avec NPM est pour le moins idiote.
Muhammad Rehan Saeed

5
d'après mon expérience, la "//"clé et sa valeur finissent par s'effacer. existe-t-il un moyen d'avoir des commentaires permanents?
pruett

116

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

12
Cela fonctionne également au niveau du package spécifique. Par exemple. "express": "makes routing better so I don't want to gouge my eyes out", "express": "3.x". Donc, oui, "beurk" comme le dit ColinE, et aussi "merci" comme le dit ColinE.
juanpaco

22
Notez cependant que ce hack vous empêche de modifier le package.jsonde manière programmatique, par exemple en npm version 1.2.3augmentant la version - les entrées redondantes seront supprimées du JSON résultant.
jakub.g

16
C'est un mauvais conseil, car l'ordre d'interprétation d'un objet n'est pas garanti. Par exemple, dans certaines situations, votre exemple pourrait se retrouver avec un être 1 au lieu de 2.
Jo Sprague

6
@mpen Le risque est qu'il n'y ait aucune garantie que le code analysant le JSON le fera séquentiellement.
Jo Sprague

7
Pour mémoire, la RFC dit explicitement: "Lorsque les noms dans un objet ne sont pas uniques, le comportement du logiciel qui reçoit un tel objet est imprévisible. De nombreuses implémentations signalent uniquement le dernier nom / valeur. D'autres implémentations signalent une erreur ou échouent pour analyser l'objet, et certaines implémentations signalent toutes les paires nom / valeur, y compris les doublons. "
Alan Tam

106

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.


1
De cette façon, il est plus logique de garder les choses propres.
Hitesh Sahu

4
Merci pour une solution non hacky techniquement valide et sémantiquement utile.
Roy Tinker

5
Pour des commentaires sur les scripts, pourquoi ne pas fournir des scripts "d'aide", par exemple "scripts": { "postinstall": "echo postinstall stuff goes here", "help-postinstall": "echo helpful stuff goes here" }
pic

1
@peak merci! Le seul inconvénient que je vois est que les scripts réels seront mélangés avec des commentaires.
gkond

1
@gkond merci pour cela. Cela a le plus de sens pour moi.
Robin Winslow

20

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


intelligent, j'aime ça
KorreyD

14

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

13

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.


1
Le "//"hack ne fonctionne pas dans devDependencies. NPM essaie de résoudre un chemin UNC.
Dmitry S.

Merci pour la phrase de mise à jour mais encore une fois, il ne peut pas commenter l' mochaattribut Il peut simplement en ajouter plusieurs et sera utilisé par npm à la fin.
vusan

je déteste l'admettre - mais j'aime mieux cela que le "//"
roocell

9

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.


6
yay, il est actuellement disponible: npmjs.com/package/x----x----x
revelt

9
J'ai été ravi de cette réponse, mais après avoir exécuté npm install(en utilisant npm 5) mes clés en double ont été automatiquement supprimées :(
Eric Majerus

@EricMajerus oups ~, npm5 me brise aussi le cœur :(
Liao San Kai

8

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

7

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

Argh, en fait sous Windows, il ignorerait juste les drapeaux, donc 3. n'est pas vrai: /
Marc Trudel

Rendez-le compatible avec cmd avec: &&au lieu de, ;donc la première commande devient:"help": "echo 'Display help information (this screen)' && npm run",
phil_lgr

1
Oui, c'est ce que j'ai fini par faire. Bonne prise!
Marc Trudel

3
Cela ne fonctionne que dans la scriptssection. package.jsonc'est beaucoup d'autres choses.
Rolf

Correct. Là encore, que ressentiriez-vous le besoin de documenter là-dedans?
Marc Trudel

6

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 pense que c'est la réponse "correcte" à bien des égards (tâche de supprimer les commentaires avec des correctifs diff pour tenir compte des changements post-bande) - cependant, j'ai l'impression que le poids supplémentaire d'une tâche de grognement n'est pas ce que certaines personnes sont après, pour les petits projets, il est probablement préférable de conserver un fichier externe pour les commentaires et d'utiliser les scripts NPM (évite complètement les tâches de construction). Pour les grands projets, vous utilisez probablement une certaine forme de gestionnaire de tâches, donc cette approche semble solide. Entre les deux, je pense que peut-être adapter la suggestion "//" au goût (éviter ses points de douleur particuliers) est le meilleur qui puisse être fait.
Enull

1
J'aime cette idée, mais comme quelqu'un l'a demandé sur l'essentiel, qu'en est-il du cas où vous modifiez le package.json d'origine via npm install --saveou --save-dev?
isochrone

ouais je continue de manquer ces commentaires; Il n'y a pas de bonne solution, j'avais l'habitude de regarder les différences git et de mettre à jour mon fichier .js après la mise à jour
MarZab

1

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.


1

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


1

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.


1

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.


0

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.


oui b / c vous ne pouvez pas vraiment mais la //clé partout, ce n'est pas vraiment un bon substitut pour les commentaires, surtout quand les commentaires peuvent avoir une belle coloration syntaxique avec un éditeur etc.
Alexander Mills

0

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"

}}}

0

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.


cela n'essaierait-il pas d'installer les packages nommés del-commentet envify-comment?
Beni Cherniavsky-Paskin

-1

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

utiliser start_commentserait mieux, car alors il ordonnera par ordre alphabétique
Alexander Mills
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.