web-dev-qa-db-fra.com

Comment ajouter des commentaires à package.json for npm install?

J'ai un simple fichier package.json et je veux ajouter un commentaire. Y a-t-il un moyen de faire cela, ou y at-il des bidouilles 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 comme des pauses npm. J'ai aussi essayé // commentaires de style.

commentsnpm
318
Will Shaver

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, elle est réservée aux commentaires ... Si vous souhaitez utiliser un commentaire sur plusieurs lignes, vous pouvez utiliser un tableau ou plusieurs "//". clés.

Lors de l'utilisation de 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" }
383
Igor Soarez

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

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

Après avoir perdu une heure sur des solutions complexes et complexes, je me suis trouvé une solution assez simple, élégante et valable pour commenter ma section de dépendances volumineuses 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"
  }
}

Une fois trié de la même manière, il m'est désormais très facile de suivre ces paires de dépendances/commentaires, soit dans les différences git commit, soit dans l'éditeur tout en utilisant package.json.

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

J'espère que cela aide quelqu'un.

58
gkond

Vous pouvez toujours abuser du fait que les clés dupliquées sont écrasées. C'est 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 dupliquées (voir La syntaxe JSON autorise-t-elle les clés dupliquées dans un objet? . Cela semble fonctionner avec npm, je prends donc le risque.

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

Mise à jour: L'un des inconvénients du piratage de clés dupliqué est que npm install --save élimine en silence tous les doublons. Malheureusement, il est très facile de l’ignorer et vos commentaires bien intentionnés ont disparu.

Le hack "//" est toujours le plus sûr qui semble être. Cependant, les commentaires sur plusieurs lignes seront également supprimés par npm install --save.

14
Philipp Claßen

J'ai une idée amusante.

Créez le nom du package npm de manière appropriée en tant que diviseur de commentaire pour les blocs dependencies et devDependencies dans package.json, par exemple 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: Doit ajouter la dernière ligne de division du commentaire avec une version valide telle que * en bloc.

8
Liao San Kai

Voici mon opinion sur les commentaires dans package.json/bower.json:

J'ai package.json.js qui contient un script qui exporte le package.json actuel. L'exécution du script remplace l'ancien package.json et m'indique les modifications qu'il a apportées, ce qui est parfait pour vous aider à suivre les modifications automatiques effectuées par npm. De cette façon, je peux même définir par programme quels paquets je veux utiliser. 

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

5
MarZab

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

Edit La réponse initiale mettait la description à droite en utilisant # add comments here pour l’envelopper; toutefois, cela ne fonctionne pas sous Windows, car les indicateurs (par exemple, npm exécutant myframework - --myframework-flags) seraient ignorés. J'ai modifié ma réponse pour la faire fonctionner sur toutes les plates-formes et ajouté quelques alinéas pour des raisons 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 viole pas la conformité JSON (ou du moins ce n'est pas un hack, et votre IDE ne vous avertira pas de faire des choses étranges et dangereuses)
  2. Fonctionne sur plusieurs plates-formes (testé sur macOS et Windows, en supposant que cela fonctionnerait parfaitement sous Linux)
  3. Ne gêne pas l'exécution de npm run myframework -- --help 
  4. Produira des informations significatives lors de l'exécution de npm run (qui est la commande à 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 sachent pas 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 en ouvrant simplement package.json (en utilisant less ou votre IDE préféré)
5
Marc Trudel

Beaucoup d'idées intéressantes.

Voici ce que j'ai fait:

{
  ...
  "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 proprement dit, et exécuter aussi quelque chose comme ceci, pour voir une sorte d'aide dans le terminal:

npm run about
npm run about:watch

Mes 2cents pour cette discussion :)

4
Felipe N Moura

Comme les clés de commentaires en double sont supprimées avec les outils package.json (npm, yarn, etc.), j’en suis venu à utiliser une version hachée qui permet une meilleure lecture sous forme de lignes et de clés multiples

"//": {
  "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 dans dependencies, il se plaint de l'attente d'une valeur de chaîne.

0
Clemens Tolboom

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

Un autre hack. J'ai créé un script pour lire package.json en tant que 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
forforf

Je me suis retrouvé avec une scripts comme celle-ci:

  "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, mais simplement d'avoir une sorte de 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 clés sont différentes et je n'ai aucun problème du tout comme ça.

0
maxime1992

Comme cette réponse explique, la clé // a été réservée, elle peut donc être utilisée de manière classique pour les commentaires. Le problème avec le commentaire // est qu'il ne peut pas être utilisé dans dependencies et devDependencies comme dépendance normale 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 adaptés aux 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"],
}

Puisque les dépendances sont triées lorsque package.json est modifié par NPM, il est peu pratique 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 avant OR ne correspond pas, un commentaire peut être analysé, par exemple. 1.x.

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

0
Estus Flask