Làm cách nào để thêm nhận xét vào gói.json để cài đặt npm?

Tôi đã có một tệp pack.json đơn giản và tôi muốn thêm một nhận xét. Có cách nào để làm điều này, hoặc có bất kỳ hack để làm cho công việc này?

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

Nhận xét ví dụ ở trên không hoạt động khi nghỉ npm. Tôi cũng đã thử // bình luận kiểu.

Này gần đây đã được thảo luận trong các mailing list Node.js .

Theo Isaac Schlueter, người đã tạo ra npm:

... Khóa "//" sẽ không bao giờ được sử dụng bởi npm cho bất kỳ mục đích nào và được dành riêng cho các nhận xét ... Nếu bạn muốn sử dụng một nhận xét nhiều dòng, bạn có thể sử dụng một mảng hoặc nhiều "//" chìa khóa.

Khi sử dụng các công cụ thông thường của bạn (npm, sợi, v.v.), nhiều phím "//" sẽ bị xóa. Điều này tồn tại:

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

Điều này sẽ không tồn tại:

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

Đây là một hack khác để thêm ý kiến ​​trong JSON. Từ:

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

Tương đương với

{"a": 2}

Bạn có thể làm một cái gì đó như:

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

Sau khi lãng phí một giờ cho các giải pháp phức tạp và hacky, tôi đã tìm thấy cả giải pháp đơn giản và hợp lệ để bình luận phần phụ thuộc cồng kềnh của mình package.json. Chỉ như thế này:

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

Khi được sắp xếp theo cùng một cách, giờ đây tôi rất dễ dàng theo dõi các cặp phụ thuộc / nhận xét này trong git commit diffs hoặc trong trình chỉnh sửa trong khi làm việc với package.json.

Và không có công cụ bổ sung nào liên quan, chỉ là JSON đơn giản và hợp lệ.

Hy vọng điều này sẽ giúp bất cứ ai.

Nhiều ý tưởng thú vị.

Những gì tôi đã làm là thế này:

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

Bằng cách này, tôi có thể vừa đọc "bình luận giả" trong chính kịch bản, VÀ cũng chạy một cái gì đó như sau, để xem một số loại trợ giúp trong thiết bị đầu cuối:

npm run about
npm run about:watch

2cents của tôi cho cuộc thảo luận này :)

NPS (Node Gói Script) đã giải quyết vấn đề này cho tôi. Cho phép bạn đặt các tập lệnh NPM của mình vào một tệp JS riêng biệt, nơi bạn có thể thêm các bình luận galore và bất kỳ logic JS nào khác mà bạn cần. https://www.npmjs.com/package/nps

Mẫu của package-scripts.jsmột trong những dự án của tôi

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

Tôi vừa thực hiện một cài đặt cục bộ npm install nps -save-devvà đặt nó trong package.jsonkịch bản của tôi .

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

Bạn luôn có thể lạm dụng thực tế là các khóa trùng lặp được ghi đè. Đây là những gì tôi vừa viết:

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

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

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

Tuy nhiên, không rõ liệu JSON có cho phép các khóa trùng lặp hay không (xem Cú pháp JSON có cho phép các khóa trùng lặp trong một đối tượng không? . Nó dường như hoạt động với npm, vì vậy tôi chấp nhận rủi ro.

Việc hack được khuyến nghị là sử dụng "//"các khóa (từ danh sách gửi thư của nodejs ). Tuy nhiên, khi tôi kiểm tra nó, nó không hoạt động với các phần "phụ thuộc". Ngoài ra, ví dụ trong bài đăng sử dụng nhiều "//"khóa, hàm ý rằng npm không từ chối các tệp JSON có các khóa trùng lặp. Nói cách khác, hack ở trên phải luôn ổn.

Cập nhật: Một nhược điểm khó chịu của hack key trùng lặp là npm install --saveâm thầm loại bỏ tất cả các bản sao. Thật không may, nó rất dễ dàng để bỏ qua nó và ý kiến ​​có thiện chí của bạn đã biến mất.

Việc "//"hack vẫn an toàn nhất có vẻ như. Tuy nhiên, bình luận nhiều dòng cũng sẽ bị xóa npm install --save.

Tôi có một ý tưởng hack vui nhộn.

Tạo tên gói npm phù hợp làm bộ chia nhận xét cho dependenciesvà devDependencieschặn trong gói.json, ví dụ: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": "*"
    }
}

LƯU Ý : Phải thêm dòng chia bình luận cuối cùng với phiên bản hợp lệ như *trong khối.

Lấy cảm hứng từ chủ đề này, đây là những gì chúng tôi đang sử dụng :

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

Cho đến nay, hầu hết các "hack" ở đây đề nghị lạm dụng JSON. Nhưng thay vào đó, tại sao không lạm dụng ngôn ngữ kịch bản cơ bản?

Chỉnh sửa Phản hồi ban đầu là đặt mô tả ở bên phải bằng cách sử dụng # add comments heređể bọc nó; tuy nhiên, điều này không hoạt động trên Windows, vì các cờ (ví dụ: npm chạy myframework - --myframework-flags) sẽ bị bỏ qua. Tôi đã thay đổi phản hồi của mình để làm cho nó hoạt động trên tất cả các nền tảng và thêm một số thụt lề cho mục đích dễ đọc.

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

Điều này sẽ:

1. Không phá vỡ sự tuân thủ JSON (hoặc ít nhất nó không phải là hack và IDE của bạn sẽ không đưa ra cảnh báo cho bạn khi làm những việc lạ, nguy hiểm)
2. Hoạt động đa nền tảng (được thử nghiệm trên macOS và windows, giả sử nó sẽ hoạt động tốt trên Linux)
3. Không cản trở hoạt động npm run myframework -- --help
4. Sẽ xuất thông tin có ý nghĩa khi chạy npm run (đó là lệnh thực tế để chạy để lấy thông tin về các tập lệnh có sẵn)
5. Trình bày một lệnh trợ giúp rõ ràng hơn (trong trường hợp một số nhà phát triển không biết rằng npm run trình bày đầu ra như vậy)
6. Sẽ hiển thị cả hai lệnh VÀ mô tả của nó khi chạy chính lệnh đó
7. Có thể đọc được một chút khi chỉ cần mở package.json(sử dụng lesshoặc IDE yêu thích của bạn)

Đây là nhận xét của tôi trong package.json/ bower.json:

Tôi có package.json.jschứa một kịch bản xuất khẩu thực tế package.json. Chạy kịch bản ghi đè lên bản cũ package.jsonvà cho tôi biết những thay đổi đã thực hiện, hoàn hảo để giúp bạn theo dõi các thay đổi tự độngnpm được thực hiện. Bằng cách đó, tôi thậm chí có thể xác định theo chương trình những gói tôi muốn sử dụng.

Nhiệm vụ grunt mới nhất có tại đây: https://gist.github.com/MarZab/72fa6b85bc9e71de5991

Tôi đã kết thúc với một scriptsnhư thế:

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

Mục đích của tôi ở đây không phải là làm rõ một dòng, chỉ để có một số loại phân cách giữa các tập lệnh của tôi cho phụ trợ, frontend, tất cả, v.v.

Tôi không phải là một fan hâm mộ lớn của 1a, 1b, 1c, 2a, ... nhưng các phím khác nhau và tôi không có bất kỳ vấn đề nào như vậy cả.

Như câu trả lời này giải thích, //khóa đã được bảo lưu, vì vậy nó có thể được sử dụng thông thường cho các bình luận. Vấn đề với //nhận xét là nó không thể được sử dụng dependenciesvà devDependenciesphụ thuộc thường xuyên với một chuỗi như ràng buộc phiên bản:

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

gây ra lỗi,

npm ERR! mã EINVALIDPACKAGENAME

npm ERR! Tên gói không hợp lệ "//": tên chỉ có thể chứa các ký tự thân thiện với URL

Mặc dù các khóa có giá trị không phải là chuỗi được coi là phụ thuộc không hợp lệ và bị bỏ qua một cách hiệu quả:

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

Một phụ thuộc chính nó có thể được nhận xét theo cùng một cách:

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

Vì các phụ thuộc được sắp xếp khi pack.json được sửa đổi bởi NPM, nên việc đặt một nhận xét bên trên một phụ thuộc mà nó đề cập là không thực tế:

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

Khóa bình luận nên được đặt tên phù hợp nếu nó đề cập đến dòng cụ thể, vì vậy nó sẽ không được di chuyển:

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

Một nhận xét có thể áp dụng cho sự phụ thuộc cụ thể có thể được thêm vào như một phần của ngữ nghĩa:

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

Lưu ý rằng nếu phần đầu tiên trước khi ORkhông khớp, một nhận xét có thể được phân tích cú pháp, ví dụ 1.x.

Các cách giải quyết này tương thích với tất cả các phiên bản NPM hiện tại (6 trở xuống).

Vì hầu hết các nhà phát triển đều quen thuộc với tài liệu dựa trên thẻ / chú thích, nên quy ước tôi đã bắt đầu sử dụng là tương tự. Đây là một hương vị:

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

Lưu ý: Đối với các phần dependencies, devDependenciesv.v., các chú thích nhận xét không thể được thêm trực tiếp bên trên các phụ thuộc gói riêng lẻ bên trong đối tượng cấu hình vì npmhy vọng khóa sẽ là tên của gói npm. Do đó lý do cho @comment dependencies.

Lưu ý: Trong một số bối cảnh nhất định, chẳng hạn như trong đối tượng script, một số trình soạn thảo / IDE có thể phàn nàn về mảng. Trong ngữ cảnh tập lệnh, Mã VS mong đợi một chuỗi cho giá trị - không phải là một mảng.

Tôi thích cách thêm chú thích / kiểu thẻ chú thích vào JSON vì @biểu tượng nổi bật so với các khai báo thông thường.

Để tóm tắt tất cả các câu trả lời sau:

1. Thêm một trường cấp cao nhất được gọi //có chứa chuỗi nhận xét. Điều này hoạt động nhưng nó rất tệ bởi vì bạn không thể đặt bình luận gần với điều họ đang bình luận.

2. Thêm nhiều trường cấp cao nhất bắt đầu bằng // , ví dụ: //dependenciescó chứa chuỗi nhận xét. Điều này tốt hơn nhưng nó vẫn chỉ cho phép bạn đưa ra nhận xét cấp cao nhất. Bạn không thể bình luận phụ thuộc cá nhân.

3. Thêm echolệnh vào của bạn scripts. Điều này hoạt động nhưng nó hút bởi vì bạn chỉ có thể sử dụng nó trong scripts.

Những giải pháp này cũng không dễ đọc lắm. Họ thêm rất nhiều tiếng ồn thị giác và IDE sẽ không làm nổi bật chúng dưới dạng các bình luận.

Tôi nghĩ rằng giải pháp hợp lý duy nhất là tạo ra package.jsontừ một tập tin khác. Cách đơn giản nhất là viết JSON của bạn dưới dạng Javascript và sử dụng Node để viết nó package.json. Lưu tệp này dưới dạng package.json.mjs, chmod +xvà sau đó bạn có thể chạy tệp này để tạo tệp của mình 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));

Nó sử dụng //chìa khóa để cảnh báo mọi người chỉnh sửa nó. \x40generatedlà cố ý. Nó biến thành @generatedtrong package.jsonvà có nghĩa là một số hệ thống xem lại mã sẽ thu gọn tệp đó theo mặc định.

Đây là một bước bổ sung trong hệ thống xây dựng của bạn nhưng nó đánh bại tất cả các bản hack khác ở đây.

Vì các khóa nhận xét trùng lặp được loại bỏ khi chạy các công cụ pack.json (npm, sợi, v.v.) Tôi đã sử dụng một phiên bản băm cho phép đọc tốt hơn như nhiều dòng và khóa như

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

đó là 'hợp lệ' theo IDE của tôi làm khóa gốc, nhưng bên trong dependenciesnó phàn nàn về việc mong đợi một giá trị chuỗi.

Một hack khác. Tôi đã tạo một tập lệnh để đọc package.jsonlàm bối cảnh cho mẫu tay lái.

Mã dưới đây trong trường hợp ai đó thấy cách tiếp cận này hữu ích:

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;
  });
});

tập tin mẫu tay cầm 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"

}}}

Đối với npm pack.json đã tìm thấy 2 cách (sau khi đọc đoạn hội thoại này):

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

Nhưng với việc cập nhật hoặc cài đặt lại gói với "--save" hoặc "--save-dev, hãy bình luận như" ^ 4.1.0! bình luận "ở vị trí tương ứng sẽ bị xóa. Và tất cả điều này sẽ phá vỡ kiểm toán npm.

Tôi cảm thấy thất vọng vì không có bình luận nào trong JSON. Tôi tạo các nút mới, được đặt tên cho các nút mà chúng tham chiếu, nhưng có tiền tố là dấu gạch dưới. Điều này là không hoàn hảo, nhưng chức năng.

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