Ouvrez n'importe quel projet JavaScript sérieux : à la racine se trouve un fichier package.json. C'est lui qui répond aux questions que se posent les outils avant de faire quoi que ce soit.
Quel est le nom du projet, de quoi dépend-il, quelles commandes sait-il lancer, ses fichiers .js sont-ils des modules ? Tout tient dans un seul objet JSON.
Définition
package.json est le fichier de description d'un projet JavaScript. npm s'en sert pour installer les dépendances et lancer les scripts, Node.js pour savoir comment interpréter les fichiers, et les outils de build pour trouver le point d'entrée du paquet.
{
"name": "boutique",
"version": "1.4.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"lint": "eslint ."
},
"dependencies": {
"zod": "^3.23.8"
},
"devDependencies": {
"eslint": "^9.9.0",
"vite": "^5.4.0"
}
}Le fichier obéit à la syntaxe JSON stricte : guillemets doubles obligatoires, aucun commentaire, aucune virgule finale. Une virgule en trop et toutes les commandes du projet s'arrêtent.
Les champs qui comptent vraiment
- name et version : l'identité du paquet. Indispensables pour publier, facultatifs sur une application privée, qui pose alors
"private": true. - type :
"module"fait lire les.jscomme des Module ES, son absence les traite en CommonJS. - scripts : des raccourcis de commandes, lancés par
npm run. - dependencies : ce dont l'application a besoin pour fonctionner une fois en ligne.
- devDependencies : ce qui ne sert qu'à la fabrication, comme Vite ou ESLint.
- engines : la version de Node attendue, utile pour éviter une mauvaise surprise au déploiement.
Lire une version et son préfixe
Une version se lit en trois nombres, majeur, mineur et correctif, et le signe qui la précède décide de ce qu'une installation peut ramener de plus récent.
| Notation | Ce qu'elle autorise |
|---|---|
3.23.8 | Exactement cette version, rien d'autre |
~3.23.8 | Les correctifs, jusqu'à 3.23.x |
^3.23.8 | Les correctifs et les ajouts, jusqu'à 3.x.x |
* | N'importe quoi, à proscrire sur un projet réel |
Le fichier package-lock.json qui l'accompagne note la version exacte réellement installée, dépendances des dépendances comprises. C'est lui qui garantit que deux machines obtiennent le même code : il se versionne, il ne se supprime pas.
Questions fréquentes
Faut-il envoyer package.json sur le dépôt de code ?
Oui, lui et le fichier de verrouillage, toujours. En revanche le dossier node_modules reste hors du dépôt : il se reconstruit en une commande à partir de ces deux fichiers, et il pèse souvent plus lourd que le projet entier.
Quelle différence entre dependencies et devDependencies ?
Les premières partent en production avec l'application, les secondes restent sur la machine de fabrication. Le classement compte surtout pour un paquet publié, dont les utilisateurs récupèrent les dépendances : y glisser un outil de test alourdit inutilement leurs installations.
Peut-on écrire un commentaire dedans ?
Non, JSON ne le permet pas. L'usage consiste à ajouter une clé de plus, par exemple "//" ou un champ maison ignoré par les outils, pour laisser une note à l'équipe. Une explication un peu longue a de toute façon sa place dans le fichier README du projet.