Si vous travaillez avec du code JavaScript, vous tombez sur un fichier package.json dans chaque projet. Chaque fois que vous lancez npm install ou yarn ces gestionnaires de paquets regardent ce fichier et saisissent les dépendances dont vous avez besoin. Cependant, ces fichiers regorgent d'informations précieuses et de fonctionnalités puissantes, plongeons-y !

Cet exemple nous servira de point de référence.

Et si vous recherchez un développeur react freelance sur Toulouse pensez à moi.

{
  "name": "example-package",
  "description": "A package that does a thing",
  "version": "1.0.0",
  "author": "@kovskyD",
  "repository": {
    "type": "git",
    "url": "https://github.com/some-project-here"
  },
  "dependencies": {
    "react": "16.8.6"
  },
  "devDependencies": {
    "prettier": "^1.18.2"
  },
  "keywords": ["react"],
  "license": "MIT",
  "main": "index.js",
  "scripts": {
    "test": "jest"
  },
  "bin": "./bin/executable.js"
}

Dans un fichier package.json nous pouvons distinguer plusieurs parties distinctes.

Les Metadata

Les premiers éléments d'un package.json sont descriptifs. La description, le dépôt et l'auteur (ou les contributeurs s'il y en a plusieurs) sont là pour fournir un contexte au sujet du projet. Si vous publiez le paquet sur npm, ces informations sont disponibles sur la page du paquet. Le nom et la version en font un peu plus.

name est un nom de paquet de type kebab-case. C'est le nom sous lequel vous le trouverez dans npm, c'est le nom que vous utiliserez pour installer le paquet, etc. Si vous êtes habitué à utiliser des paquets, vous êtes probablement familier avec une syntaxe comme celle-ci "react" : "16.8.6". Il s'agit d'un nom et d'un numéro de version.

La plupart des projets JavaScript suivent semver comme un moyen d'incrémenter intuitivement la version du paquet. Chaque fois que le paquet est publié sur npm, la version devrait augmenter. L'incrémentation du premier, du dernier ou du numéro intermédiaire dépend de l'importance des changements et de leur impact sur les autres utilisateurs

Parlons de "react" : "16.8.6" encore. Chaque dépendance est répertoriée comme une paire clé-valeur en utilisant le nom et la version du paquet. Cependant, il est possible d'ajouter des caractères supplémentaires devant la version

  • ~ : si vous ajoutez un tilde, votre gestionnaire de paquets installera la version que vous avez indiquée ou toute version de patch plus récente. Par exemple, ~16.8.6 signifie que vous obtiendrez la dernière version de 16.8.x, mais pas la 16.9.0.
  • ^ : Si vous ajoutez un caret, votre gestionnaire de paquets installera la version que vous avez indiquée ou tout autre correctif plus récent ou version mineure, mais pas une version majeure. Par exemple, ^16.8.6 signifie que vous obtiendrez la dernière version de 16.x.y, mais pas la 17.0.0.

Il existe également des caractères supplémentaires pris en charge, qui vous permettent de spécifier des plages. Tous ces caractères sont analysés à l'aide du paquet semver. Cela devient un peu confus, alors laissez-moi clarifier les choses. Semver est un ensemble de directives pour le versionnage de vos paquets. Puisque npm le suit et utilise ces directives comme base pour son gestionnaire de paquets, il a nommé le paquet de versionnement sémantique qu'il utilise en conséquence.

devDependencies, les dépendances de développement

Les dépendances sont légèrement différentes. Ce sont des dépendances qui sont nécessaires aux développeurs travaillant sur le paquet, par exemple les bibliothèques de test. Cependant, les utilisateurs finaux n'en ont pas besoin, c'est pourquoi elles sont incluses séparément. Elles sont incluses lorsque vous lancez l'installation npm dans un paquet exemple, mais pas lorsque vous installez un paquet exemple dans un autre projet.

peerDependencies

Il s'agit là d'un autre type de dépendance. Elle est surtout là pour les auteurs de paquets afin d'éviter les conflits lorsqu'ils utilisent un paquet que d'autres dépendances que vous avez utilisent également. Par exemple, il faut s'assurer que le paquet utilise la version de Babel de votre projet et non une version locale qui pourrait ne pas être compatible.

Keywords

Ce sont des mots-clés pour aider l'utilisateur lorsqu'il recherche un paquet sur npm comme cette bonne vieille balise meta-keyword.

Licence

Commentaire obligatoire "Je ne suis pas avocat" ici. Les licences sont un sujet sur lequel il y a des experts et je ne suis pas l'un d'entre eux. La ou les licences indiquées sont les conditions dans lesquelles vous êtes autorisé à utiliser le projet. Vous pouvez en savoir plus sur les différentes licences.

Main entry points, point d'entrée principal

C'est le fichier qui est référencé lorsque quelqu'un importe un colis. Il est donné "principal" : "index.js", const example = require("example-package") saisira l'exemple d'exportation de l'index.js.

Scripts

C'est là que nous entrons dans le vif du sujet. La section des scripts comprend davantage de paires clé-valeur. La clé est le nom de la commande et la valeur correspond aux instructions de la ligne de commande qui s'exécutent lorsque vous l'appelez.

Commençons par un exemple simple.

{
  "test": "npm run jest"
}

C'est plus un pseudonyme qu'autre chose. Il nous permet d'exécuter un test npm dans notre ligne de commande et il exécutera en fait le npm run jest.

Et pourquoi pas quelque chose d'un peu plus complexe ?

{
  "lint": "eslint --cache --ext .js,.jsx,.ts,.tsx ."
}

Cela se répercute sur l'ensemble du répertoire des projets avec certains flags spécifiques.

Rien ne vous empêche d'exécuter ces scripts vous-même. Vous donner une commande plus courte avec la bonne configuration participe à une meilleure expérience de développement.

Cependant, certains scripts sont destinés à construire le projet afin qu'il puisse être publié et installé dans d'autres projets sous forme de paquet. Il existe des clés spéciales qui exécutent les scripts à des moments précis, mais nous n'allons pas nous plonger dans ce domaine ici.

Nous allons plutôt examiner quelques types de scripts que vous pourriez voir et qui regroupent un projet et le préparent pour l'installation.

{
  "build": "babel src --out-dir . --ignore \"**/__tests__\""
}

Ce premier scénario utilise Babel. Il utilise un fichier de configuration à la racine du projet, qui prend tous les fichiers du répertoire src et les compile dans le répertoire racine. Il inclut également un flag pour ignorer les fichiers dans src/tests.

Example avec Microbundle

{
  "build": "microbundle -i src/example.js"
}

e script utilise le microbundle pour regrouper le projet. Dans ce cas, nous spécifions un src/example.js comme point d'entrée pour la construction.

Exécution des scripts

Les scripts sont exécutables. J'ai mentionné plus haut que npm test exécute npm jest et c'est le cas. Cependant, c'est parce que test est un alias de npm run test. Il y en a quelques-uns des comme ça.

Pour tout autre script personnalisé que vous spécifiez, un utilisateur doit exécuter npm run.

Bin

Encore une chose amusante ! En plus de la commande npm, il y a maintenant une commande npx. npx vous permet d'exécuter des commandes sans avoir à installer le paquet au préalable. 🤯

Les auteurs de paquets le permettent en utilisant la section bin du fichier package.json. Il peut être écrit comme une paire clé-valeur ou en utilisant la syntaxe ci-dessous.

{
  "bin": "./bin/executable.js"
}

Dans ce cas, le ./bin et l'extension sont supprimés et l'utilisateur peut exécuter l'exécutable npx. Si jamais vous décidez d'écrire un paquet qui implémente cela, notez que le chemin d'accès relatif au fichier est basé sur la version fournie du projet. Cela est logique, car il est exécuté directement à partir du paquet publié.

Quelque chose à ajouter ? Vous pouvez toujours ajouter un commentaire.