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

voici un autre hack pour ajouter des commentaires dans 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 les solutions complexes et hacky, je me suis trouvé une solution assez simple, élégante et valide pour commenter ma section volumineuse de dépendances dans package.json . Comme ceci:

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

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

et pas d'outils supplémentaires impliqués, juste simple et valide JSON.

J'espère que ça aidera n'importe qui.

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? . Il semble fonctionner avec npm, donc je prends le risque.

le piratage recommandé est d'utiliser les clés "//" (de la liste de diffusion nodejs ). Quand je l'ai testé, cela n'a pas fonctionné avec les sections "dépendances", cependant. En outre, l'exemple dans le post 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 piratage ci-dessus devrait toujours être bien.

mise à jour: un inconvénient gênant du piratage des clés dupliquées est que npm install --save élimine silencieusement tous les doublons. Malheureusement, il est très facile de l'ignorer et vos commentaires bien intentionnés s'en sont allés.

le piratage du "//" est toujours aussi sûr qu'il y paraît. Cependant , les commentaires multilignes seront également supprimés par npm install --save .

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

Échantillon de l 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 je l'ai mis dans mes scripts package.json .

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

j'ai une drôle d'idée de piratage.

créer le nom du paquet npm de manière appropriée comme diviseur de commentaire pour les blocs dependencies et devDependencies dans le paquet.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 commentaire diviseur avec une version valide comme * dans le bloc.

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

j'ai package.json.js qui contient un script que les exportations de la package.json . Exécuter le script écrira l'ancien package.json et me dira quels changements il a fait, parfait pour vous aider à garder la trace des changements automatiques npm fait. De cette façon, je peux même définir programmatiquement les paquets que je veux utiliser.

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

jusqu'ici, la plupart des "hacks" suggèrent d'abuser de JSON. Mais pourquoi ne pas abuser du langage de script sous-jacent?

Edit la réponse initiale était de mettre la description sur la droite en utilisant # add comments here pour l'envelopper; cependant, cela ne fonctionne pas sur Windows, parce que les drapeaux (par exemple npm run myfram Framework -- --myfram Framework-flags) seraient ignorés. J'ai modifié ma réponse pour qu'elle fonctionne sur toutes les plateformes, et j'ai ajouté des tirets pour la lisibilité. but.

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

Ce sera:

1. Pas de rupture de JSON de la conformité (ou au moins, pas un hack, et votre IDE ne sera pas vous donner des avertissements pour faire d'étrange, quelque chose de dangereux)
2. fonctionne plate-forme croisée (testé sur macOS et windows, en supposant qu'il fonctionnerait très bien sur Linux)
3. ne s'oppose pas à l'exécution de npm run myframework -- --help
4. produira des informations significatives lorsque lancer 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 (dans le cas où certains devs ne sont pas conscients que npm run présente une telle sortie)
6. affichera à la fois les commandes et leur description lors de l'exécution de la commande elle-même
7. est quelque peu lisible en ouvrant package.json (en utilisant less ou votre IDE préféré)

beaucoup d'idées intéressantes.

ce que j'ai fait 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 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:)

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 clarifier une ligne, juste d'avoir une sorte de délimiteurs entre mes scripts pour backend, frontend, all, 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 de ce genre.

de Mon point de vue sur la frustration de pas de commentaires en JSON. Je crée de nouveaux noeuds, nommés d'après les noeuds auxquels ils font référence, mais préfixés avec des underscores. C'est imparfait, mais fonctionnelle.

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

comme dupliquer les touches de commentaire sont supprimés en lançant paquet.outils json (npm, fil, etc) je suis venu à l'aide d'une version hachée qui permet une meilleure lecture que les lignes multiples et des 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 comme clé racine, mais dans dependencies il se plaint d'attendre une valeur de chaîne.