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.
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" }
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": "*"
}
}
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.
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
.
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.
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
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é:
npm run myframework -- --help
npm run
(qui est la commande à exécuter pour obtenir des informations sur les scripts disponibles)package.json
(en utilisant less
ou votre IDE préféré)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 :)
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.
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"
}
}
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"
}}}
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.
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).