package.json

Principes

Les deux champs les plus importants de votre package.json sont name et version, sans lesquels le package ne pourra pas être installé. Les champs name et version sont utilisés ensemble pour créer un ID unique.

name 

{
  "name": "mon-super-package"
}

C’est le nom de votre package. Il est utilisé dans les URLs, comme argument en ligne de commande et comme nom de répertoire dans le répertoire node_modules.

yarn add [name]

node_modules/[name]


https://registry.npmjs.org/[name]/-/[name]-[version].tgz

Règles

  • Doit être inférieur ou égal à 214 caractères (en comptant le @scope/ pour les packages avec une portée limitée).
  • Ne doit pas commencer par un point (.) ou un tiret du bas (_).
  • Ne doit pas avoir de majuscules.
  • Doit uniquement contenir des caractères utilisables dans les URLs.

Conseils

  • N’utilisez pas le même nom qu’un module du noyau de Node.js.
  • Ne mettez pas js ou node dans le nom.
  • Gardez des noms courts mais descriptif. Vous souhaitez que les gens comprennent ce que c’est à partir du nom, mais il sera également utilisé dans les appels require().
  • Assurez-vous qu’il n’y a rien dans le registre avec le même nom.

version 

{
  "version": "1.0.0"
}

La version actuelle du package.

Info

description 

{
  "description": "Une courte description de mon super package"
}

La description est juste une chaîne de caractères qui aide les utilisateurs à comprendre le but de votre package. Elle peut également être utilisée lors de la recherche dans le gestionnaire de packages.

keywords 

{
  "keywords": ["mots clés", "pertinents", "courts", "pour", "la recherche"]
}

Les mots clés sont un tableau de chaînes de caractères utiles lors de la recherche du package dans le gestionnaire de packages.

license 

{
  "license": "MIT",
  "license": "(MIT or GPL-3.0)",
  "license": "SEE LICENSE IN NOM_DU_FICHIER_DE_LICENCE.txt",
  "license": "UNLICENSED"
}

Tous les packages devraient spécifier une licence afin que les utilisateurs sachent comment ils peuvent utiliser votre package et les restrictions que vous fixez dessus.

Vous êtes encouragés à utiliser la licence Open Source (approuvé par OSI) à moins que vous ayez des raisons spécifiques de ne pas le faire. Si vous créez un package dans le cadre de votre travail, le mieux est de vérifier avec votre société avant de choisir une licence.

Elle doit être, parmi les choix suivants :

  • Un identifiant SPDX valide si vous utilisez une licence standard.
  • Une expression de licence SPDX valide respectant la syntaxe 2.0 si vous utilisez plusieurs licences standards.
  • Une chaîne SEE LICENSE IN <nom_du_fichier> qui pointe vers <le_nom_du_ficher> au niveau le plus haut de votre package si vous utilisez une licence non-standard.
  • Une chaîne UNLICENSED si vous ne voulez pas autorisez les autres utilisateurs d’utiliser un package privé ou non-publié sous toutes conditions.

Liens

Différents liens vers la documentation, l’endroit où saisir de nouveaux problèmes rencontrés ou l’hébergement de votre code source.

homepage 

{
  "homepage": "https://votre-package.org"
}

La homepage est l’URL pointant vers la page d’accueil de la documentation de votre package.

bugs 

{
  "bugs": "https://github.com/user/repo/issues"
}

L’URL pointant vers votre gestionnaire de bugs. Peut également être quelque chose comme une adresse email. Cela procure un moyen aux utilisateurs pour trouver où ils peuvent renseigner un problème rencontré avec votre package.

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’endroit où se trouve le code source de votre package.

Mainteneurs

Les mainteneurs de votre projet.

author 

{
  "author": { "name": "Votre Nom", "email": "votre_email@exemple.com", "url": "http://votre-site.com" },
  "author": "Votre Nom <votre_email@exemple.com> (http://votre-site.com)"
}

Regroupe les informations de l’auteur. Un auteur est une personne.

contributors 

{
  "contributors": [
    { "name": "Votre Ami", "email": "votre_ami@exemple.com", "url": "http://site-de-votre-ami.com" }
    { "name": "Autre Ami", "email": "autre_ami@exemple.com", "url": "http://site-de-autre-ami.com" }
  ],
  "contributors": [
    "Votre Ami <votre_ami@exemple.com> (http://site-de-votre-ami.com)",
    "Autre Ami <autre_ami@exemple.com> (http://site-de-autre-ami.com)"
  ]
}

Les gens ayant contribué à votre package. Les contributeurs sont un tableau de personnes.

Fichiers

Vous pouvez spécifiez des fichiers qui seront inclus dans votre projet, avec le fichier de point d’entrée de votre projet.

files 

{
  "files": [
    "filename.js",
    "directory/",
    "glob/*.{js,json}"
  ]
}

Ce sont les fichiers qui sont inclus dans votre projet. Vous pouvez spécifier des fichiers de manière unitaire, des répertoires complets ou bien utiliser des expressions pour inclure tous les fichiers qui respectent un certain critère.

main 

{
  "main": "filename.js"
}

C’est le point d’entrée principal de votre projet.

bin 

{
  "bin": "bin.js",
  "bin": {
    "ma-commande": "bin/ma-commande.js",
    "une-autre-commande": "bin/une-autre-commande"
  }
}

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 man associées à votre projet, ajoutez-les ici.

directories 

{
  "directories": {
    "lib": "chemin/vers/bibliotheques/",
    "bin": "chemin/vers/binaires/",
    "man": "chemin/vers/manuels/",
    "doc": "chemin/vers/doc/",
    "example": "chemin/vers/exemple/"
  }
}

Lorsque vous installez votre package, vous pouvez spécifier des chemins précis où mettre les fichiers binaires, les pages de manuel, la documentation, les exemples, etc.

Tâches

Votre package peut contenir des scripts exécutables ou de la configuration additionnelle.

scripts 

{
  "scripts": {
    "build-project": "node build-project.js"
  }
}

Les scripts sont un super moyen pour automatiser des tâches relatives à votre package, comme un processus de build simple ou des outils de développement. En utilisant le champs "scripts", vous définissez divers scripts qui peuvent être exécutés en lançant yarn run <script>. Par exemple, le script build-project plus haut peut être lancé avec yarn run build-project et exécutera node build-project.js.

Certains noms de scripts sont particuliers. S’il est défini, le script preinstall sera appelé par yarn avant que votre package ne soit installé. Pour des raisons de compatibilité, les scripts install, postinstall et prepublish seront tous appelés après l’installation de votre package.

Le script start a pour valeur de défaut node server.js.

config 

{
  "config": {
    "port": "8080"
  }
}

Options de configuration ou paramètres utilisés par vos scripts.

Dépendances

Votre package va probablement dépendre d’autres packages. Vous pouvez spécifier ces dépendances dans votre fichier package.json.

dependencies 

{
  "dependencies": {
    "package-1": "^3.1.4"
  }
}

Ces dépendances sont nécessaires à la fois pour le développement et l’exécution en production de votre package.

Vous pouvez spécifier des versions précises, un version minium (par exemple >=) ou un intervalle de versions (par exemple >= ... <).

devDependencies 

{
  "devDependencies": {
    "package-2": "^0.4.2"
  }
}

Ce sont des packages qui seront uniquement nécessaires pour développer dans votre package, mais ne seront pas installés en production.

peerDependencies 

{
  "peerDependencies": {
    "package-3": "^2.7.18"
  }
}

Les dépendances peer permettent de définir la compatibilité de votre package avec les versions d’autres packages.

optionalDependencies 

{
  "optionalDependencies": {
    "package-5": "^1.6.1"
  }
}

Les dépendances optionnelles peuvent être utilisées avec votre package, mais ne sont pas requises. Si un package optionnel n’est pas trouvé, l’installation continuera.

bundledDependencies 

{
  "bundledDependencies": [
    "package-4"
  ]
}

Les dépendances “bundled” sont un tableau de nom de packages qui seront empaquetés ensemble lors de la publication de votre package.

flat 

{
  "flat": true
}

Si votre package n’autorise qu’une version d’une dépendance donnée et que vous voulez forcer le même comportement que la commande yarn install --flat en ligne de commande, vous pouvez mettre ce paramètre à true.

Notez que si votre package.json contient "flat": true et que d’autres packages dépendent du votre (par exemple si vous être en train de créer une bibliothèque plutôt qu’une application), alors les autres packages auront également besoin de "flat": true dans leur package.json ou bien devront être installés en ligne de commande avec yarn install --flat.

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

Permet de substituer une version d’une dépendance particulière imbriquée. Voir les résolutions des versions sélectives RFC pour 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.

Système

Vous pouvez fournir des informations sur le système dans votre package, comme la compatibilité avec le système d’exploitation, etc.

engines 

{
  "engines": {
    "node": ">=4.4.7 <7.0.0",
    "zlib": "^1.2.8",
    "yarn": "^0.14.0"
  }
}

Cela permet de spécifier les versions ou les clients qui doivent être utilisés avec votre package. Cela vérifie en comparant avec process.versions ainsi qu’avec la version courante de yarn.

os 

{
  "os": ["darwin", "linux"],
  "os": ["!win32"]
}

Permet de spécifier les systèmes d’exploitation compatibles avec votre package. Vérifier par rapport à process.platform.

cpu 

{
  "cpu": ["x64", "ia32"],
  "cpu": ["!arm", "!mips"]
}

Utilisez ceci pour spécifier que votre package ne fonctionnera qu’avec certaines architectures de CPU particulières. Cela compare avec process.arch.

Publication

private 

{
  "private": true
}

Si vous ne souhaitez pas que votre package soit publié dans un gestionnaire de packages, mettez cette valeur à true.

publishConfig 

{
  "publishConfig": {
    ...
  }
}

Ces valeurs de configuration seront utilisées lors de la publication de votre package. Vous pouvez taguer votre package, par exemple.

← Configuration envvars →