attention, n'utilisez pas package.json pour le nom du dossier si vous souhaitez cloner ce projet sur votre machine - cela casserait yarn ( An unexpected error occurred: "EISDIR: illegal operation on a directory, read". ).
Version originale de ce document copiée de Yarnpkg.
Voir aussi la documentation npm, std-pkg, clean-publish, package-json-validator, cosmiconfig, rc (comme approche opposée à cosmiconfig).
nameversiondescriptionkeywordslicensehomepagebugsrepositoryauthorcontributorsfilesmainbinmandirectoriesscriptsscripts spécifiques à npmconfigdependenciesdevDependenciespeerDependenciesoptionalDependenciesbundledDependenciesenginesoscpulibcprivatepublishConfigflatresolutionsworkspacesboltunpkgtypesflow:mainbrowserslistmodulebrowseresnextes2015esmmodule-browsermodules.rootjsnext:mainreact-nativesideEffectssource , umd:mainsource@std/esmjspmignoreformatregistryshimmapbrowserify.transformproxyhomepagebabeleslintConfigjeststylelintsize-limitpwmetricsavanycpreferGlobalstylelessstandard Les deux champs les plus importants de votre package.json sont name et version , sans eux, votre package ne pourra pas s'installer. Les champs name et version sont utilisés ensemble pour créer un identifiant unique.
name{
"name" : " my-awesome-package "
} C'est le nom de votre colis. Il est utilisé dans les URL, comme argument sur la ligne de commande et comme nom de répertoire dans node_modules .
yarn add [name] node_modules/[name]
https://registry.npmjs.org/[name]/-/[name]-[version].tgz
Règles
@scope/ pour les packages étendus).. ) ou un trait de soulignement ( _ ).Conseils
js ou node dans le nom.require() .version{
"version" : " 1.0.0 "
}La version actuelle de votre package.
description{
"description" : " My short description of my awesome package "
}La description n'est qu'une chaîne qui aide les gens à comprendre le but du package. Il peut également être utilisé lors de la recherche de packages dans un gestionnaire de packages.
keywords{
"keywords" : [ " short " , " relevant " , " keywords " , " for " , " searching " ]
}Les mots-clés sont un tableau de chaînes utiles lors de la recherche de packages dans un gestionnaire de packages.
license{
"license" : " MIT " ,
"license" : " (MIT or GPL-3.0) " ,
"license" : " SEE LICENSE IN LICENSE_FILENAME.txt " ,
"license" : " UNLICENSED "
}Tous les packages doivent spécifier une licence afin que les utilisateurs sachent comment ils sont autorisés à l'utiliser et toutes les restrictions que vous leur imposez.
Nous vous encourageons à utiliser une licence Open Source (approuvée OSI), sauf si vous avez une raison spécifique de ne pas le faire. Si vous avez créé votre package dans le cadre de votre travail, il est probablement préférable de vérifier auprès de votre entreprise avant de décider d'une licence.
Doit être l'un des éléments suivants :
SEE LICENSE IN <filename> qui pointe vers un <filename> au niveau supérieur de votre package si vous utilisez une licence non standard.UNLICENSED si vous ne souhaitez pas accorder à d'autres le droit d'utiliser un package privé ou non publié sous quelque condition que ce soit. Divers liens vers la documentation, les endroits où signaler les problèmes et l'endroit où se trouve réellement le code de votre package.
homepage{
"homepage" : " https://your-package.org "
}La page d'accueil est l'URL de la page de destination ou de la documentation de votre package.
Également utilisé par l'application Create React
bugs{
"bugs" : " https://github.com/user/repo/issues "
}L'URL du système de suivi des problèmes de votre projet. Cela peut également être quelque chose comme une adresse e-mail. Il offre aux utilisateurs un moyen de savoir où envoyer les problèmes liés à votre colis.
repository{
"repository" : { "type" : " git " , "url" : " https://github.com/user/repo.git " },
"repository" : " github:user/repo " ,
"repository" : " gitlab:user/repo " ,
"repository" : " bitbucket:user/repo " ,
"repository" : " gist:a1b2c3d4e5f "
}Le référentiel est l’emplacement où se trouve le code réel de votre package.
Les responsables de votre projet.
author{
"author" : { "name" : " Your Name " , "email" : " [email protected] " , "url" : " http://your-website.com " },
"author" : " Your Name <[email protected]> (http://your-website.com) "
}Informations sur l’auteur du package. Un auteur est une personne.
contributors{
"contributors" : [
{ "name" : " Your Friend " , "email" : " [email protected] " , "url" : " http://friends-website.com " }
{ "name" : " Other Friend " , "email" : " [email protected] " , "url" : " http://other-website.com " }
],
"contributors" : [
" Your Friend <[email protected]> (http://friends-website.com) " ,
" Other Friend <[email protected]> (http://other-website.com) "
]
}Ceux qui ont contribué à votre package. Les contributeurs sont un large éventail de personnes.
Vous pouvez spécifier les fichiers qui seront inclus dans votre projet, ainsi que le point d'entrée principal de votre projet.
files{
"files" : [
" filename.js " ,
" directory/ " ,
" glob/*.{js,json} "
]
}Ce sont des fichiers inclus dans votre projet. Vous pouvez spécifier des fichiers uniques, des répertoires entiers ou utiliser des caractères génériques pour inclure des fichiers répondant à certains critères.
main{
"main" : " filename.js "
}Il s’agit du principal point d’entrée pour les fonctionnalités de votre projet.
bin{
"bin" : " bin.js " ,
"bin" : {
"command-name" : " bin/command-name.js " ,
"other-command" : " bin/other-command "
}
}Fichiers exécutables inclus avec votre projet qui seront installés.
man{
"man" : " ./man/doc.1 " ,
"man" : [ " ./man/doc.1 " , " ./man/doc.2 " ]
}Si vous avez des pages de manuel associées à votre projet, ajoutez-les ici.
directories{
"directories" : {
"lib" : " path/to/lib/ " ,
"bin" : " path/to/bin/ " ,
"man" : " path/to/man/ " ,
"doc" : " path/to/doc/ " ,
"example" : " path/to/example/ "
}
}Lors de l'installation de votre package, vous pouvez spécifier les emplacements exacts pour placer les fichiers binaires, les pages de manuel, la documentation, les exemples, etc.
Votre package peut inclure des scripts exécutables ou une autre configuration.
scripts{
"scripts" : {
"build-project" : " node build-project.js "
}
} Les scripts sont un excellent moyen d'automatiser les tâches liées à votre package, telles que des processus de construction simples ou des outils de développement. En utilisant le champ "scripts" , vous pouvez définir différents scripts à exécuter en tant que yarn run <script> . Par exemple, le script build-project ci-dessus peut être invoqué avec yarn run build-project et exécutera node build-project.js .
Certains noms de scripts sont spéciaux. S'il est défini, le script preinstall est appelé par Yarn avant l'installation de votre package. Pour des raisons de compatibilité, les scripts appelés install , postinstall et prepublish seront tous appelés une fois l'installation de votre package terminée.
La valeur par défaut du script start est node server.js .
"scripts": {"start": "node server.js"}. S'il existe un fichier server.js à la racine de votre package, npm appliquera par défaut la commande start à node server.js.
"scripts":{"preinstall": "node-gyp rebuild"}. S'il existe un fichier contraignant.gyp à la racine de votre package, npm utilisera par défaut la commande de préinstallation pour compiler à l'aide de node-gyp.-- documents npm
scripts spécifiques à npm npm prend en charge la propriété scripts du fichier package.json , pour les scripts suivants :
prepublish : exécuté AVANT que le package ne soit compressé et publié, ainsi que lors de l'installation locale de npm sans aucun argument. (Voir ci-dessous)prepare : exécutez les deux AVANT que le package ne soit compressé et publié, et lors de l'installation locale de npm sans aucun argument (voir ci-dessous). Ceci est exécuté APRÈS la prépublication, mais AVANT la prépublication uniquement.prepublishOnly : exécuté AVANT que le package ne soit préparé et compressé, UNIQUEMENT sur npm submit. (Voir ci-dessous.)prepack : exécuté AVANT qu'une archive tar soit compressée (sur npm pack, npm submit et lors de l'installation des dépendances git)postpack : à exécuter APRÈS que l'archive tar ait été générée et déplacée vers sa destination finale.publish , postpublish : exécuté APRÈS la publication du package.preinstall : à exécuter AVANT que le package ne soit installéinstall , postinstall : Exécuté APRÈS l'installation du package.preuninstall , uninstall : Exécuté AVANT la désinstallation du package.postuninstall : à exécuter APRÈS la désinstallation du package.preversion : Exécuter AVANT de modifier la version du package.version : exécuter APRÈS avoir modifié la version du package, mais AVANT de valider.postversion : Exécuté APRÈS avoir modifié la version du package et APRÈS la validation.pretest , test , posttest : Exécutés par la commande npm test.prestop , stop , poststop : Exécuté par la commande npm stop.prestart , start , poststart : Exécuté par la commande npm start.prerestart , restart , postrestart : Exécuté par la commande npm restart . Remarque : npm restart exécutera les scripts d'arrêt et de démarrage si aucun script de redémarrage n'est fourni.preshrinkwrap , shrinkwrap , postshrinkwrap : Exécutés par la commande npm Shrinkwrap.Source : docs npm.
config{
"config" : {
"port" : " 8080 "
}
}Options de configuration ou paramètres utilisés dans vos scripts.
Votre forfait dépendra très probablement d’autres forfaits. Vous pouvez spécifier ces dépendances dans votre fichier package.json .
dependencies{
"dependencies" : {
"package-1" : " ^3.1.4 "
}
}Il s'agit de dépendances requises à la fois lors du développement et de la production de votre package.
Vous pouvez spécifier une version exacte, une version minimale (par exemple,
>=) ou une plage de versions (par exemple>= ... <).
devDependencies{
"devDependencies" : {
"package-2" : " ^0.4.2 "
}
}Il s'agit de packages qui ne sont requis que lors du développement de votre package mais qui ne seront pas installés en production.
peerDependencies{
"peerDependencies" : {
"package-3" : " ^2.7.18 "
}
}Les dépendances entre pairs vous permettent d'indiquer la compatibilité de votre package avec les versions d'autres packages.
optionalDependencies{
"optionalDependencies" : {
"package-5" : " ^1.6.1 "
}
}Les dépendances facultatives peuvent être utilisées avec votre package, mais ne sont pas obligatoires. Si le package facultatif n'est pas trouvé, l'installation continue.
bundledDependencies{
"bundledDependencies" : [
" package-4 "
]
}Les dépendances groupées sont un tableau de noms de packages qui seront regroupés lors de la publication de votre package.
Vous pouvez fournir des informations au niveau du système associées à votre package, telles que la compatibilité du système d'exploitation, etc.
engines{
"engines" : {
"node" : " >=4.4.7 <7.0.0 " ,
"zlib" : " ^1.2.8 " ,
"yarn" : " ^0.14.0 "
}
} Les moteurs spécifient les versions des clients qui doivent être utilisées avec votre package. Cela vérifie process.versions ainsi que la version actuelle de fil.
os{
"os" : [ " darwin " , " linux " ],
"os" : [ " !win32 " ]
} Ceci spécifie la compatibilité du système d’exploitation pour votre package. Il vérifie par rapport à process.platform .
cpu{
"cpu" : [ " x64 " , " ia32 " ],
"cpu" : [ " !arm " , " !mips " ]
} Utilisez-le pour spécifier que votre package ne fonctionnera que sur certaines architectures de processeur. Ceci vérifie par rapport à process.arch .
libc{
"libc" : [ " glibc " ],
"libc" : [ " musl " ]
} Utilisez ceci pour spécifier que votre package s'exécute uniquement sur une version spécifique de la libc. Cela vérifie le résultat de detect-libc .
private{
"private" : true
} Si vous ne souhaitez pas que votre package soit publié dans un gestionnaire de packages, définissez ceci sur true .
publishConfig{
"publishConfig" : {
...
}
}Ces valeurs de configuration seront utilisées lors de la publication de votre package. Vous pouvez par exemple étiqueter votre colis.
flat{
"flat" : true
} Si votre package n'autorise qu'une seule version d'une dépendance donnée et que vous souhaitez appliquer le même comportement que yarn install --flat sur la ligne de commande, définissez ceci sur true .
Notez que si votre package.json contient "flat": true et que d'autres packages dépendent du vôtre (par exemple, vous construisez une bibliothèque plutôt qu'une application), ces autres packages auront également besoin de "flat": true dans leur package.json ou be installé avec yarn install --flat sur la ligne de commande.
resolutions{
"resolutions" : {
"transitive-package-1" : " 0.0.29 " ,
"transitive-package-2" : " file:./local-forks/transitive-package-2 " ,
"dependencies-package-1/transitive-package-3" : " ^2.1.1 "
}
}Vous permet de remplacer une version d’une dépendance imbriquée particulière. Consultez la RFC sur les résolutions de versions sélectives pour connaître les spécifications complètes.
Notez que l'installation de dépendances via [ yarn install --flat ] ajoutera automatiquement un bloc resolutions à votre fichier package.json .
workspaces Si --use-workspaces est vrai, packages seront remplacés par la valeur de package.json/workspaces .
Source : --use-workspaces.
boltVoir Configuration
{
"bolt" : {
"workspaces" : [
" utils/* " ,
" apps/* "
]
}
}unpkg Si vous omettez le chemin du fichier (c'est-à-dire utilisez une URL « nue »), unpkg servira le fichier spécifié par le champ unpkg dans package.json , ou reviendra à main (source).
types Si votre package possède un fichier principal .js , vous devrez également indiquer le fichier de déclaration principal dans votre fichier package.json . Définissez la propriété types pour qu'elle pointe vers votre fichier de déclaration groupé. Par exemple:
{
"main" : " ./lib/main.js " ,
"types" : " ./lib/main.d.ts "
} Notez que le champ typings est synonyme de types et pourrait également être utilisé.
Notez également que si votre fichier de déclaration principal est nommé index.d.ts et se trouve à la racine du package (à côté de index.js ), vous n'avez pas besoin de marquer la propriété types , bien qu'il soit conseillé de le faire.
Source : Documentation TypeScript
Remarque : dans Flow, ils utilisent une approche différente
flow:mainNon officiellement pris en charge. La proposition est ici.
browserslist? Bibliothèque pour partager les navigateurs cibles entre différents outils front-end. Il est utilisé dans :
package.json ou browserslist pris en charge dans la version 2.0) Tous les outils qui s'appuient sur Browserslist trouveront automatiquement leur configuration lorsque vous ajoutez ce qui suit à package.json :
{
"browserslist" : [
" > 1% " ,
" last 2 versions "
]
}Source : liste des navigateurs.
Voir également : Créer un support pour l'application React.
Voir « Configuration de packages NPM multiplateformes » pour une introduction.
module pkg.module pointera vers un module qui a la syntaxe du module ES2015, mais sinon uniquement les fonctionnalités de syntaxe prises en charge par les environnements cibles. La description complète est ici.
Pris en charge par : rollup, webpack
browser Le champ browser est fourni par un auteur de module comme indice pour les bundles javascript ou les outils de composants lors du packaging de modules pour une utilisation côté client. La proposition est ici.
Pris en charge par : rollup, webpack, browserify
Support demandé : babel-plugin-module-resolver
esnextLa proposition complète est ici. Brève explication :
esnext : code source utilisant les fonctionnalités du stage 4 (ou plus ancien), non transpilé, dans les modules ES.main : pointe vers un module CommonJS (ou module UMD) avec un JavaScript aussi moderne que Node.js peut actuellement le gérer.module devraient être gérables via esnext .browser peut être géré via une version étendue d' esnext {
"main" : " main.js " ,
"esnext" : {
"main" : " main-esnext.js " ,
"browser" : " browser-specific-main-esnext.js "
}
}Voir aussi : Fournir du code source non transpilé via npm
es2015Code ES6 non transpilé. Source : Format de package angulaire (APF) v5.0
esmLa proposition est ici : proposition ajustée : module ES "esm": true flag package.json
Voir aussi :
module-browserVoir ce problème
Également appelé moduleBrowser , jsnext:browser .
modules.rootMentionné dans En défense de .js.
Il existe également modules.resolver .
jsnext:mainDÉCONSEILLÉ
jsnext:main a été remplacé par pkg.module , qui indique l'emplacement d'un fichier avec les déclarations d'import/export. La proposition originale est ici.
Pris en charge par : rollup.
react-native Fonctionne de manière similaire au browser , mais pour les modules spécifiques à React-Native. Source.
sideEffectsIndique que les modules du package n'ont aucun effet secondaire (sur l'évaluation) et exposent uniquement les exportations. Cela permet à des outils comme webpack d'optimiser les réexportations.
Voir aussi : exemple sideEffects , proposition de marquage des fonctions comme pures, eslint-plugin-tree-shaking.
source , umd:mainVoir Spécification des builds dans package.json.
sourceVoir colis-bundler/parcel#1652.
@std/esm Les développeurs ont des opinions bien arrêtées sur à peu près tout. Pour cela, @std/esm permet de débloquer des fonctionnalités supplémentaires avec le champ "@std/esm" ou "@std":{"esm":{}} dans votre package.json .
Source : @std/esm Déblocables
jspm Vous pouvez écrire toutes les propriétés du package à la base du package.json, ou si vous ne souhaitez pas modifier les propriétés existantes que vous souhaitez utiliser spécifiquement pour npm , vous pouvez écrire votre configuration spécifique à jspm dans la propriété jspm de package.json et jspm utiliseront ces options plutôt que les options de configuration au niveau racine.
Par exemple:
{
"name" : " my-package " ,
"jspm" : {
"main" : " jspm-main "
}
}Voir les spécifications complètes.
ignoreS'il y a certains fichiers ou dossiers spécifiques à ignorer, ils peuvent être répertoriés dans un tableau.
format Les options sont esm , amd , cjs et global .
Lors du chargement de modules depuis
npm, le format du module est traité commecjspar défaut et aucune détection automatique n'est exécutée. Pour charger des modules d'un autre format, vous devrez remplacer cette propriété manuellement.
Le format de module
esm(ECMAScript Module) n'est actuellement pas utilisé dans package.json.
registryjspm comprend les dépendances dans le contexte d'un registre.
Lors du chargement de packages à partir de npm, jspm définira le registre par défaut sur npm et traitera les dépendances en conséquence.
Lors du chargement de packages depuis GitHub, la propriété de dépendances est ignorée sans qu'une propriété de registre soit présente, car jspm n'a aucun moyen de savoir ce que signifient les dépendances pour les dépôts GitHub existants.
La définition de la propriété de registre détermine également la façon dont jspm interprète le package. Par exemple, un package GitHub avec registry: "npm" , en plus d'obtenir ses dépendances de npm, sera interprété comme CommonJS et prendra en charge des fonctionnalités telles que l'annuaire et JSON requis, exactement comme s'il avait été installé à partir du point de terminaison npm pour commencer.
Un package sur GitHub avec sa propriété de registre définie sur registry: "jspm" verra ses dépendances traitées comme des dépendances de style jspm.
shim Les packages écrits en tant que globaux nécessitent une configuration shim pour fonctionner correctement dans un environnement modulaire. Pour caler un fichier some/global.js au sein du package, on peut écrire :
{
"shim" : {
"some/global" : {
"deps" : [ " jquery " ],
"exports" : " globalExportName "
}
}
} deps et exports sont facultatifs.
exports sont détectées automatiquement par le chargeur SystemJS comme toutes les globales écrites par le script. Dans la plupart des cas, cette détection fonctionnera correctement.
Le raccourci "some/global": ["jquery"] est également pris en charge s'il n'y a pas exports .
mapLa configuration de la carte réécrira les exigences internes pour pointer vers différents modules locaux ou externes.
Considérons un package qui inclut sa propre dépendance, dep située dans third_party/dep . Il pourrait avoir une instruction require en interne, quelque chose comme :
require ( 'dep' ) ;Afin d'utiliser la version locale, on peut écrire :
{
"map" : {
"dep" : " ./third_party/dep "
}
}Il peut également être utile de référencer un package par son propre nom au sein des sous-modules :
{
"map" : {
"thispackage" : " . "
}
} Nous pouvons alors avoir des exigences internes pour import 'thispackage/module' .
La configuration de la carte peut également faire référence à des sous-modules de dépendance.
Nous pouvons également exclure entièrement les modules en les mappant au module vide :
{
"map" : {
"jquery" : " @empty "
}
}La valeur renvoyée sera alors un objet Module sans exportation.
browserify.transformLa documentation est ici
proxyLes utilisateurs servent souvent l'application React frontale à partir du même hôte et du même port que leur implémentation backend.
Source : Requêtes d'API proxy en cours de développement
homepageSource : Construire des chemins relatifs
babelVoir ce problème.
eslintConfigjest{
"jest" : {
"verbose" : true
}
}
Source : documents de plaisanterie
stylelintVoir : Nouveau chargeur de configuration
size-limit Si vous utilisez cette bibliothèque, vous pouvez définir sa configuration dans package.json :
{
"size-limit" : [
{
"limit" : " 9 KB " ,
"path" : " index.js "
}
]
}Source : limite de taille
pwmetrics Vous pouvez spécifier les options dans package.json :
{
"pwmetrics" : {
"url" : " http://example.com/ " ,
"expectations" : {
"ttfcp" : {
"warn" : " >=1500 " ,
"error" : " >=2000 "
}
}
}
}Toutes les options disponibles sont ici
Source : pwmetrics
avaExemple:
"ava" : {
"require" : [ " @std/esm " ]
}Source : ava
nycExemple:
"nyc" : {
"extension" : [ " .js " , " .mjs " ],
"require" : [ " @std/esm " ]
}Source : New York
preferGlobalDÉCONSEILLÉ
Cette option déclenchait un avertissement npm, mais elle n'avertirait plus. Il est là uniquement à titre informatif. Il est désormais recommandé d'installer tous les binaires en tant que dépendances de développement locales dans la mesure du possible.
style L'attribut style dans package.json est utile pour importer des packages CSS. La proposition est ici.
Pris en charge par : parcelify, npm-less, rework-npm, npm-css.
Voir aussi : istf-spec.
less Identique au style mais pour moins cher.
Pris en charge par : npm-less.
Les champs suivants sont réservés pour une expansion future : build , default , email , external , files , imports , maintainer , paths , platform , require , summary , test , using , downloads , uid .
Les champs suivants sont réservés aux registres de packages à utiliser à leur discrétion : id , type .
Toutes les propriétés commençant par _ ou $ sont également réservées aux registres de packages à leur discrétion.
Source : wiki CommonJS
standard Standard JS est un guide de style javaScript, un linter et un formateur, vous pouvez ajouter des propriétés à package.json, comme parser , ignore , globals , plugins .
Exemple:
"standard" : {
"parser" : " babel-eslint " ,
"ignore" : [
" **/out/ " ,
" /lib/select2/ " ,
" /lib/ckeditor/ " ,
" tmp.js "
]
}Voir aussi : JS standard
