Npm kurulumu için package.json dosyasına nasıl yorum ekleyebilirim?

Basit bir package.json dosyam var ve yorum eklemek istiyorum. Bunu yapmanın bir yolu var mı, yoksa bu işi yapmak için herhangi bir kesmek var mı?

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

Yukarıdaki örnek yorum npm sonu olarak çalışmaz. Ben de // tarzı yorumları denedim.

Bu kısa bir süre önce node.js posta listesinde tartışılmıştır .

Npm oluşturan Isaac Schlueter'e göre:

... "//" tuşu hiçbir zaman npm tarafından hiçbir amaçla kullanılmaz ve yorumlar için ayrılır ... Birden çok satırlı yorum kullanmak istiyorsanız, bir dizi veya birden çok "//" kullanabilirsiniz anahtarlar.

Her zamanki aletlerinizi (npm, iplik vb.) Kullanırken birden fazla "//" tuşu kaldırılacaktır. Bu hayatta kalır:

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

Bu hayatta kalamayacak:

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

İşte JSON'a yorum eklemek için başka bir kesmek. Dan beri:

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

Eşittir

{"a": 2}

Gibi bir şey yapabilirsiniz:

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

Karmaşık ve hacky çözümler üzerinde bir saat harcadıktan sonra, içinde büyük hacimli bağımlılıklarımı yorumlamak için hem basit hem de geçerli bir çözüm buldum package.json. Aynen böyle:

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

Aynı şekilde sıralandığında, git bağımlılıklarında veya editörde çalışırken bu bağımlılık / yorum çiftlerini izlemem artık çok kolay package.json.

Ekstra bir araç yok, sadece sade ve geçerli JSON.

Umarım bu herkese yardımcı olur.

Birçok ilginç fikir.

Yaptığım şey şudur:

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

Bu şekilde hem komut dosyasında "sözde yorum" okuyabilir ve ayrıca terminalde bir tür yardım görmek için aşağıdaki gibi bir şey çalıştırabilirsiniz:

npm run about
npm run about:watch

Bu tartışma için 2 sentim :)

NPS (Düğüm Paketi Komut Dosyaları) bu sorunu benim için çözdü. NPM komut dosyalarınızı ayrı bir JS dosyasına koymanızı sağlar; burada yorum bolluğu ve ihtiyacınız olan diğer JS mantıklarını ekleyebilirsiniz. https://www.npmjs.com/package/nps

package-scripts.jsProjelerimin birinden örnek

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

Sadece yerel bir kurulum yaptım npm install nps -save-devve bunu package.jsonscriptlerime koydum .

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

Yinelenen anahtarların üzerine yazıldığı gerçeğini her zaman kötüye kullanabilirsiniz. Ben sadece bu yazdım:

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

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

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

Ancak, JSON çoğaltılmış anahtarlara izin verip vermediği açık değildir ( JSON sözdizimi bir nesnede yinelenen anahtarlara izin veriyor mu? Bölümüne bakın.

Önerilen kesmek "//"anahtarları kullanmaktır ( nodejs posta listesinden ). Test ettiğimde, "bağımlılıklar" bölümleri ile çalışmadı. Ayrıca, "//"gönderideki örnekte, npm'nin çoğaltılan anahtarlarla JSON dosyalarını reddetmediği anlamına gelen birden çok anahtar kullanılır. Başka bir deyişle, yukarıdaki kesmek her zaman iyi olmalıdır.

Güncelleme: Çoğaltılan anahtar kesmek için can sıkıcı bir dezavantaj, npm install --savetüm kopyaları sessizce ortadan kaldırmasıdır. Ne yazık ki, gözden kaçırmak çok kolay ve iyi niyetli yorumlarınız gitti.

"//"Göründüğü gibi kesmek hala en güvenli olduğunu. Ancak, çok satırlı yorumlar da tarafından kaldırılacaktır npm install --save.

Komik bir hack fikrim var.

Npm paket adını uygun şekilde yorum bölücü olarak oluşturun dependenciesve devDependenciespackage.json içinde engelleyinx----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": "*"
    }
}

NOT : *Blokta olduğu gibi geçerli sürümle son yorum ayırıcı satırı eklenmelidir .

Bu konudan esinlenerek , kullandığımız şey :

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

Şimdiye kadar, çoğu "hack" JSON'u kötüye kullanmayı öneriyor. Ama bunun yerine, neden altyazı dilini kötüye kullanmıyorsunuz?

Düzenle İlk yanıt, açıklamayı # add comments heresarmak için sağa koymaktı; ancak, Windows'ta çalışmaz, çünkü bayraklar (örn. npm run myframework - --myframework-flags) yok sayılır. Tüm platformlarda çalışmasını sağlamak için yanıtımı değiştirdim ve okunabilirlik amacıyla bazı girintiler ekledim.

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

Bu irade:

1. JSON uyumluluğunu kırmayın (veya en azından bir kesmek değildir ve IDE'niz size garip, tehlikeli şeyler yapmak için uyarı vermeyecektir)
2. Çapraz platformda çalışır (Linux'ta iyi çalışacağını varsayarak macOS ve pencerelerde test edilmiştir)
3. Koşma yoluna girmez npm run myframework -- --help
4. Çalışırken anlamlı bilgiler verir npm run(mevcut komut dosyaları hakkında bilgi almak için çalıştırılacak gerçek komuttur)
5. Daha açık bir yardım komutu sunar (bazı geliştiricilerin npm çalıştırmasının bu tür çıktılar sunduğunun farkında olmaması durumunda)
6. Komutun kendisini çalıştırırken her iki komutu VE açıklamasını gösterecektir
7. Sadece açarken biraz okunabilir package.json(kullanarak lessveya en sevdiğiniz IDE)

package.json/ İçindeki yorumları almam bower.json:

Ben package.json.jsgerçek bir komut dosyası içeren var package.json. Senaryoyu çalıştırmak eskisinin üzerine yazar package.jsonve hangi değişiklikleri yaptığını söyler, npmyapılan otomatik değişiklikleri takip etmenize yardımcı olmak için mükemmeldir . Bu şekilde hangi paketleri kullanmak istediğimi programlı olarak tanımlayabilirim.

En son homurdanma görevi burada: https://gist.github.com/MarZab/72fa6b85bc9e71de5991

Ben böyle bir sonuçla sona erdi scripts:

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

Buradaki amacım bir satırı açıklığa kavuşturmak değil, sadece arka uç, ön uç vb. İçin komut dosyalarım arasında bir çeşit sınırlayıcı bulundurmak.

Ben 1a, 1b, 1c, 2a, ... büyük bir hayranı değilim ama tuşları farklı ve böyle bir sorunum yok.

As Bu cevap açıklıyor, //anahtar ayrıldı, bu yüzden yorumlar için geleneksel olarak kullanılabilir. Sorun //comment içeri kullanılamaz olmasıdır dependenciesve devDependenciesversiyon sınırlama olarak bir dize ile düzenli bağımlılık olarak:

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

bir hatayı tetikler,

npm ERR! EINVALIDPACKAGENAME kodu

npm ERR! Geçersiz paket adı "//": ad yalnızca URL uyumlu karakterler içerebilir

Dize olmayan değerlere sahip anahtarlar geçersiz bağımlılıklar olarak kabul edilir ve verimli bir şekilde yoksayılır:

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

Bir bağımlılığın kendisi de aynı şekilde yorumlanabilir:

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

Package.json, NPM tarafından değiştirildiğinde, bağımlılıklar sıralandığından, başvurduğu bir bağımlılığın üzerine bir yorum eklemek pratik değildir:

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

Yorum anahtarı, belirli bir satıra başvuruyorsa buna göre adlandırılmalıdır, bu nedenle taşınmaz:

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

Belirli bağımlılığa uygulanabilecek bir yorum, semver'in bir parçası olarak eklenebilir:

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

Önceki ilk bölüm OReşleşmezse, bir yorumun ayrıştırılabileceğine dikkat edin, ör.1.x .

Bu geçici çözümler mevcut tüm NPM sürümleriyle (6 ve daha düşük) uyumludur.

Çoğu geliştirici etiket / ek açıklama tabanlı dokümantasyona aşina olduğundan, kullanmaya başladığım kural benzerdir. İşte bir tat:

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

Not: For dependencies, devDependenciesçünkü vb bölümlerde, yorum açıklamalar doğrudan yapılandırma nesnesinin içinde bireysel paket bağımlılıkları yukarıda eklenemez npmbir npm paketinin adı olması için anahtar bekliyor. Bu nedenle@comment dependencies .

Not: Scriptler nesnesi gibi belirli bağlamlarda, bazı editörler / IDE'ler dizi hakkında şikayette bulunabilir. Komut dosyaları bağlamında, VS Kodu değer için bir dize bekler - dizi değil.

@Sembol normal bildirimlerden göze çarptığı için JSON'a yorum ekleme ek açıklama / etiket stili yolunu seviyorum .

Tüm bu cevapları özetlemek gerekirse:

1. Yorum dizesi içeren adlı tek bir üst düzey alan ekleyin //. Bu işe yarıyor ama berbat çünkü yorum yaptıkları şeylerin yanına yorum koyamazsınız.

2. İle başlayan birden fazla üst düzey alan ekleyin , örneğin bir yorum dizesi içerir. Bu daha iyidir, ancak yine de yalnızca üst düzey yorumlar yapmanıza izin verir. Bireysel bağımlılıkları yorumlayamazsınız. ////dependencies

3. İçin echokomutlar ekleyin scripts. Bu işe yarıyor ama berbat çünkü sadece içinde kullanabilirsiniz scripts.

Bu çözümlerin hepsi de çok okunaklı değildir. Tonlarca görsel parazit ekler ve IDE'ler sözdizimi olarak yorum yapmaz.

Bence tek makul çözüm package.jsonbaşka bir dosyadan oluşturmaktır. En basit yol JSON'unuzu Javascript olarak yazmak ve Düğüm'ü yazmak için kullanmaktır package.json. Bu dosyayı package.json.mjs, chmod +xbunun, ve o zaman sadece oluşturmak için çalıştırabilirsiniz 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));

//Anahtarı, kullanıcıları düzenlemesi konusunda uyarmak için kullanır . \x40generatedkasıtlıdır. Bu dönüşür @generatedinpackage.json ve bazı kod incelemesi sistemleri varsayılan olarak bu dosyayı çökecek demektir.

Yapı sisteminizde ekstra bir adımdır, ancak buradaki diğer tüm saldırıları yener.

Yinelenen yorum anahtarları, package.json tools (npm, iplik, vb.)

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

IDE'ye kök anahtar olarak 'geçerli', ancak içinde dependenciesbir dize değeri beklemekten şikayet ediyor.

Başka bir kesmek. package.jsonBir gidon şablonunun bağlamı olarak okumak için bir komut dosyası oluşturdum .

Birinin bu yaklaşımı yararlı bulması durumunda aşağıdaki kod:

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

gidon şablon dosyası 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"

}}}

Npm package.json için 2 yol bulduk (bu konuşmayı okuduktan sonra):

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

Ancak paketin "--save" veya "--save-dev ile güncellenmesi veya yeniden yüklenmesi ile" ^ 4.1.0! comment "ilgili yerde silinecek ve tüm bunlar npm denetimini kıracak.

JSON yorum yok hayal kırıklığı benim. Başvurdukları düğümler için adlandırılmış, ancak alt çizgi ile ön ek oluşturulmuş yeni düğümler oluşturuyorum. Bu kusurlu ama işlevsel.

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