Les pouvoirs insoupçonnés de package.json

August 14, 2026

Dans chacun de nos projets se trouve ce fichier familier que l'on ouvre qu'en de rares occasions avant de le refermer aussitôt : el famoso package.json.

Et c'est fort dommage, car cet incontournable des stacks web recèle quelques secrets et des pouvoirs insoupçonnés par la plupart des devs.

Faisons un point sur toutes les possibilités qu'offre le package.json pour doper votre workflow !

Les commandes personnalisées

Balayons un fait assez connu : la section scripts permet de créer des alias tels que dev, build, typecheck, test servant de raccourci pour exécuter des commandes récurrentes dans notre projet.

1{
2  "scripts": {
3    "dev": "vite",
4    "lint": "biome check ."
5  }
6}

Plus méconnus sont en revanche les hooks pre et post qui ajoutent encore plus de flexibilité à ces commandes.

Qu'est-ce donc ? Lorsque vous lancez un script build, par exemple, npm va spontanément chercher deux autres scripts : prebuild et postbuild. S'ils existent, prebuild sera exécuté avant build et postbuild juste après.

1{
2  "scripts": {
3    "prebuild": "rimraf dist", /* le dossier dist est supprimé */
4    "build": "vite build", /* le site est compilé */
5    "postbuild": "node tools/report-size.js" /* la taille du bundle est affichée */
6  }
7}

Cette convention vaut pour n'importe quel nom de script (on peut ainsi avoir des pretest, postdeploy, prerelease…) et permet d'attacher proprement des étapes de préparation ou de nettoyage autour d'une commande sans bourrer celle-ci de && et perdre en lisibilité.

Une façon bien plus propre d'écrire et de séparer les responsabilités au sein de vos scripts !

D'autres scripts cachés encore...

Il existe une seconde famille de scripts, autrement plus dangereuse : les scripts de cycle de vie que npm va déclencher tout seul à l'installation d'une dépendance. preinstall, install et postinstall s'exécutent en effet non seulement pour votre projet, mais pour chacune des dépendances que vous installez.

Historiquement il s'agissait de permettre à certaines librairies de compiler des modules natifs ou de télécharger un binaire utile à leur bon fonctionnement.

Mais cette facilité permet également à des librairies malveillantes exécuter du code arbitraire sur votre machine à chaque npm install ce qui en a fait le vecteur privilégié d'une série d'attaques de la chaîne d'approvisionnement (supply chain attacks) dans l'écosystème npm ces dernières années.

Conscient du problème et imitant en cela pnpm, Yarn et Bun qui bloquaient déjà ces scripts, npm v12 désactive dorénavant leur exécution par défaut.

Les paquets ayant réellement besoin de ces scripts pre ou post installation doivent désormais être explicitement autorisés avec la commande suivante :

1npm approve-scripts --allow-scripts-pending

Passer des arguments et lire l'environnement

Un script n'est pas toujours une commande figée et peut parfaitement recevoir des arguments pour en modifier le comportement. Par exemple, tout ce qui est placé après un double dash -- est transmis tel quel à la commande qui le précède :

1npm run test -- --watch
2npm run build -- --mode staging

Vos scripts peuvent également accéder à des variables d'environnement à commencer par les champs du package.json lui-même :

1{
2  "version": "2.4.0",
3  "scripts": {
4    "release": "echo \"Publication de la version $npm_package_version\""
5  }
6}

Pratique pour tagger une image Docker ou nommer une archive sans jamais dupliquer le numéro de version !

1{
2  "scripts": {
3    "build:staging": "cross-env NODE_ENV=production API_URL=https://staging.api vite build"
4  }
5}

Orchestrer plusieurs tâches parallèlement

Les projets réels enchaînent rarement une seule action. Le shell offre déjà deux opérateurs pour les articuler, le &et le && :

1{
2  "scripts": {
3    "ci": "npm run lint && npm run test && npm run build",
4    "dev": "npm run dev:css & npm run dev:server"
5  }
6}

Le && enchaîne les commandes en séquence qui s'interrompt totalement si l'une des étapes échoue. Le & simple les lance en parallèle…

Le & présente la même limite que celle vue précédemment pour les variables d'environnement personnalisées : il n'existe pas vraiment sous Windows qui lui donne une autre signification *windows fatigue intensifies*.

Pour du parallélisme fiable entre toutes les plateformes, deux outils dédiés ont fait leurs preuves : npm-run-all2 (le fork maintenu de l'historique npm-run-all) et concurrently :

1{
2  "scripts": {
3    "dev:css": "tailwindcss -i src/app.css -o dist/app.css --watch",
4    "dev:js": "vite",
5    "dev:api": "node server.js",
6    "dev": "run-p dev:*"
7  }
8}

run-p pour parallel, run-s pour sequential, et un dev:* qui ramasse automatiquement tous les scripts partageant le même préfixe.

Exécuter du javascript avec une commande

Les alias de commande peuvent vite devenir limités dès que vous avez besoin d'une condition (« supprimer ce dossier seulement s'il existe »), d'une boucle ou d'une gestion d'erreur. Non seulement la commande en une ligne devient un enfer illisible mais elle peut ne pas fonctionner à l'identique d'un système d'exploitation à l'autre.

Dans ce cas, il est préférable de faire pointer votre alias vers un vrai fichier JavaScript contenant toute la logique d'exécution.

1{
2  "scripts": {
3    "release": "node tools/release.js",
4    "generate:icons": "node tools/generate-icons.js"
5  }
6}

J'utilise par exemple souvent un script personnalisé de lint qui vient toiletter mes fichiers de traduction en les réordonnant, vérifier que chaque fichier de langue est exhaustif et qui repère les clefs de traduction mortes lorsque la librairie que j'utilise n'offre pas de telles fonctionnalités.

Ajouter sa propre CLI

Et là on rentre carrément dans les arcanes du package.json là où peu s'aventurent. Avec un champ bin, vous pouvez associer un nom de commande à un fichier exécutable.

1{
2  "name": "@monprojet/tooling",
3  "bin": {
4    "exec": "./tools/cli.js"
5  }
6}

Le fichier ciblé doit commencer par un shebang pour préciser le runtime.

1#!/usr/bin/env node
2
3// tools/cli.js
4const [command, ...args] = process.argv.slice(2);
5// ...

Une fois le lien établi, la commande devient disponible comme n'importe quel outil installé :

1exec new component Button
2# ✨ src/components/button/button.tsx créé

C'est de cette manière que Vite, Angular, ESLint ou Prisma mettent à disposition leur propre CLI sans nécessiter un npm run.

Rien ne vous empêche donc d'en faire autant : vos collègues récupèreront les mêmes commandes sans rien devoir installer de plus. Votre codebase peut inclure sa propre CLI pour uniformiser le workflow entre ses contributeurs.

Les champs oubliés

La section scripts monopolise l'attention, mais quelques autres champs méritent largement le détour :

• imports définit des alias d'import résolus nativement par Node, sans configuration de bundler ni de TypeScript. Les clés doivent commencer par # :

1{
2  "imports": {
3    "#utils/*": "./src/utils/*.js"
4  }
5}

• engines et packageManager verrouillent respectivement la version de Node et celle du gestionnaire de paquets attendues par le projet. De quoi mettre fin aux écarts de version entre deux machines qui donnent des résultats différents.

1{
2  "engines": {
3    "node": ">=24"
4  },
5  "packageManager": "pnpm@10.15.0"
6}

• overrides (ou son équivalent resolutions chez Yarn) force la version d'une dépendance transitive, ce qui reste le seul moyen de corriger une faille de sécurité dans un paquet que vous n'installez même pas directement.

1{
2  "overrides": {
3    "cross-spawn": "^7.0.5", /* partout dans l'arbre de dépendances */
4    "vite": {
5      "esbuild": "^0.25.0" /* uniquement lorsqu'il est requis par vite */
6    }
7  }
8}

• files liste ce qui sera réellement embarqué lors d'une publication sur npm.

1{
2  "files": [
3    "dist",
4    "!dist/**/*.test.js"
5  ]
6}

• workspaces, enfin, transforme votre dépôt en monorepo et fait le lien avec les avantages d'un monorepo.

1{
2  "private": true,
3  "workspaces": [
4    "apps/*",
5    "packages/*"
6  ]
7}

Faut-il jeter les gros orchestrateurs pour autant ?

Il serait malhonnête de conclure que le package.json remplace tout. Sur un monorepo conséquent, la mise en cache des tâches, leur parallélisation intelligente et l'exploitation du graphe de dépendances — ce que font Turborepo ou Nx — restent hors de portée d'une section scripts, et le sont de plus en plus à mesure que le projet grossit.

Mais il faut reconnaître que l'écrasante majorité des projets frontend n'en arrive jamais là, et que la tentation est grande d'installer l'orchestrateur avant d'en avoir le besoin. Or une dizaine de scripts bien nommés que vous comprenez intégralement vieilliront toujours mieux qu'un fichier de configuration que vous n'osez plus toucher, dont la moitié des options ont été copiées d'un article de blog et dont une mise à jour surprise peut casser la CI du jour au lendemain.