Le package.json

Chaque projet JavaScript ou TypeScript a un package.json à sa racine. C'est le fichier que ton gestionnaire de paquets lit pour savoir quoi installer, quels scripts exécuter, et comment ton projet est versionné.

Générer un package.json

La commande la plus rapide pour démarrer :

$npm init -y

Ou avec pnpm :

$pnpm init

Le flag -y répond "oui" à toutes les questions. Tu obtiens un fichier minimal que tu peux éditer à la main.

Structure complète annotée

{
  "name": "mon-projet",
  "version": "1.0.0",
  "description": "Description courte du projet",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest"
  },
  "dependencies": {
    "react": "^18.3.0",
    "react-dom": "^18.3.0"
  },
  "devDependencies": {
    "vite": "^5.2.0",
    "vitest": "^1.6.0",
    "@types/react": "^18.3.0"
  },
  "engines": {
    "node": ">=20.0.0"
  }
}

Les champs essentiels

name : identifiant unique du projet (en minuscules, sans espaces). Obligatoire si tu publies sur npm.

version : numéro de version au format semver (MAJOR.MINOR.PATCH). Commence à 1.0.0 pour un projet publié, 0.1.0 pour un projet en cours.

type : "module" pour utiliser import/export (ESM), rien ou "commonjs" pour require(). La valeur "module" est la norme en 2026.

scripts : les commandes que tu lances avec pnpm run <nom>. Les noms courants : dev, build, test, start, lint.

dependencies : les paquets nécessaires en production (runtime).

devDependencies : les paquets utilisés uniquement pendant le développement (compilateurs, linters, tests). Ils ne sont pas inclus dans le build final.

engines : version minimale de Node requise. Utile pour éviter les surprises sur des machines avec une vieille version.

peerDependencies

Un quatrième type de dépendance existe : peerDependencies. Il s'utilise quand tu développes une bibliothèque qui suppose que l'application hôte a déjà installé un paquet (ex : un plugin React qui exige React 18). L'utilisateur de ta lib doit installer lui-même ces pairs.

Éditer le package.json à la main

Contrairement à ce qu'on pourrait croire, éditer package.json à la main est tout à fait courant. Ajoute un script "lint": "eslint .", change le type, ajuste une version. Après chaque modification, relance pnpm install pour resynchroniser le lockfile.