Formations — 1 037 leçons en français

Accueil › Node.js › package.json, le contrat du projet

package.json, le contrat du projet

Modules et npmdebutant

package.json est le contrat du projet. Quatre champs portent l'essentiel.

{
  "name": "mon-api",
  "version": "1.4.0",
  "type": "module",
  "engines": { "node": ">=22" },
  "exports": {
    ".": "./src/index.js",
    "./routes/*": "./src/routes/*.js"
  },
  "scripts": {
    "test": "node --test",
    "dev": "node --watch --env-file=.env src/index.js"
  },
  "dependencies": { "express": "^5.1.0" },
  "devDependencies": { "eslint": "^9.0.0" }
}

exports remplace main

import app from "mon-api";                    // → ./src/index.js
import sante from "mon-api/routes/sante";     // → ./src/routes/sante.js
import x from "mon-api/src/interne.js";       // ⛔ ERR_PACKAGE_PATH_NOT_EXPORTED

exports n'est pas une liste de raccourcis : c'est une liste d'autorisation. Tout chemin absent devient inimportable, même si le fichier existe. L'auteur gagne le droit de réorganiser son arborescence interne sans casser ses utilisateurs.

Quand exports est présent, main est ignoré.

Les conditions

"exports": {
  ".": {
    "import": "./dist/index.mjs",
    "require": "./dist/index.cjs",
    "default": "./dist/index.mjs"
  }
}

Node retient la première clé applicable, dans l'ordre d'écriture. default se met donc en dernier — devant, il rend tout le reste inatteignable.

Ce que Node fait désormais seul

"scripts": {
  "test": "node --test",
  "dev": "node --watch --env-file=.env src/index.js"
}

Pas de lanceur de tests, pas de surveillance de fichiers, pas de chargeur de variables d'environnement à installer : trois dépendances en moins.

Les termes à connaître

`package.json`

Le manifeste du projet. Il déclare le nom, le format des modules, les dépendances, les scripts, et ce que le paquet laisse importer.

`main`

L'ancien point d'entrée unique. Toujours lu, mais seulement quand exports est absent : exports l'emporte.

`exports`

La carte des chemins importables. Elle déclare les points d'entrée et interdit tout le reste — c'est son apport principal.

Export conditionnel

Une entrée de exports qui choisit un fichier selon la condition active — import, require, node, default, dans l'ordre d'écriture.

Sous-chemin

Un chemin dans un paquet (paquet/utils). Autorisé seulement s'il figure dans exports, littéralement ou par un joker *.

`engines`

La plage de versions de Node que le paquet déclare supporter. npm avertit par défaut, et refuse l'installation avec engine-strict.

`ERR_PACKAGE_PATH_NOT_EXPORTED`

L'erreur d'un sous-chemin absent de exports. Le fichier existe sur le disque ; le paquet refuse de le laisser importer.

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.