Écosystème npm et package.json

Le registre npm, le manifeste package.json, les dépendances et les scripts — le cœur de l'écosystème Node.js.

📦 npm — le registre de paquets

npm (Node Package Manager) est fourni avec Node.js. Il gère deux choses :

Le registre : le plus grand dépôt de paquets open source au monde (plus de 2 millions de packages). Chaque package est installable avec npm install <nom>.
L'outil CLI : npm en ligne de commande pour installer, mettre à jour, exécuter des scripts et auditer les dépendances.

npm install express    # Installer un package
npm install -D typescript  # Package de développement uniquement
npm run dev            # Exécuter un script déclaré dans package.json
npm audit              # Vérifier les vulnérabilités connues

📄 package.json — le manifeste du projet

Chaque projet Node.js a un package.json à la racine. C'est le fichier de configuration du projet :

{
  "name": "mon-api",
  "version": "1.0.0",
  "description": "Une API Node.js avec Express",
  "main": "src/index.ts",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "test": "vitest"
  },
  "dependencies": {
    "express": "^4.18.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "@types/node": "^20.0.0",
    "@types/express": "^4.17.0",
    "tsx": "^4.0.0",
    "vitest": "^1.0.0"
  }
}

Champs essentiels

Champ	Rôle
`name`	Nom du package (unique sur le registre npm)
`version`	Version sémantique du projet
`main`	Point d'entrée du package (pour les imports CommonJS)
`scripts`	Scripts exécutables via `npm run <nom>`
`dependencies`	Packages nécessaires à l'exécution
`devDependencies`	Outils de développement (compiler, tester, linter)

dependencies vs devDependencies

npm install express          # → dependencies (nécessaire en production)
npm install -D typescript    # → devDependencies (utile au dev, pas en prod)
npm install -D @types/node   # Types pour les API Node.js (dev only)
npm install -D tsx           # Exécution TypeScript directe (dev only)

En production, npm install --production installe seulement les dependencies. Les devDependencies (outils de build, tests, linters) ne sont pas installés — elles alourdissent l'image Docker.

🔧 package-lock.json — reproductibilité

npm génère automatiquement un package-lock.json (ou npm-shrinkwrap.json) qui fige les versions exactes de toutes les dépendances et de leurs dépendances transitives.

{
  "name": "mon-api",
  "lockfileVersion": 3,
  "dependencies": {
    "express": {
      "version": "4.18.2",
      "resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz",
      "integrity": "sha512-..."
    }
  }
}

Toujours commiter package-lock.json

Sans lui, npm install peut installer des versions différentes d'un jour à l'autre (selon la plage de versions dans package.json). Le lock assure que tout le monde et tous les environnements (dev, CI, production) utilisent exactement les mêmes versions.

📡 Installation et résolution des paquets

npm install                    # Installer toutes les dépendances (lit package.json + lock)
npm install express            # Ajouter une dépendance → écrit dans package.json + lock
npm install -D vitest          # Ajouter une devDependency
npm install --save-dev @types/node  # alias de -D
npm uninstall express          # Retirer une dépendance
npm update                     # Mettre à jour vers les versions compatibles
npm outdated                   # Lister les paquets pouvant être mis à jour
npm audit                     # Scanner les vulnérabilités connues
npm audit fix                  # Corriger automatiquement si possible

semver — versioning sémantique

Les versions suivent le format MAJOR.MINOR.PATCH :

1.0.0 → version de base
1.1.0 → nouvelle fonctionnalité (compatible)
1.1.1 → correction de bug (compatible)
2.0.0 → breaking change (incompatible)

Dans package.json : "^4.18.0" accepte 4.x.x mais pas 5.0.0. "~4.18.0" accepte 4.18.x mais pas 4.19.0.

⚙️ Les scripts npm

Les scripts définis dans package.json sont exécutables via npm run <nom> :

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "lint": "eslint src/",
    "test": "vitest",
    "typecheck": "tsc --noEmit"
  }
}

npm run dev        # Exécuter le script "dev"
npm run build      # Exécuter le script "build"
npm test           # Exécuter le script "test" (raccourci : npm test)
npm run lint       # Exécuter le script "lint"

npm run accepte des arguments passés après -- :

npm run build -- --verbose

🔗 Imports avec les paquets npm

Avec TypeScript et moduleResolution: "NodeNext", les imports de paquets npm utilisent le nom du package :

// Import d'un paquet npm
import express from "express"
import { Request, Response } from "express"

// Import d'un sous-module
import { createHash } from "node:crypto"

TypeScript utilise @types/<package> pour typer les paquets npm qui n'ont pas de types intégrés :

npm install -D @types/express   # Types pour Express

// Sans @types/express, express() retourne any
// Avec @types/express, Request et Response sont pleinement typés
import express, { Request, Response } from "express"

const app = express()

app.get("/api/ping", (req: Request, res: Response) => {
  res.json({ status: "ok" })
})

Quiz du chapitre

3 questions

0 / 3 répondue0%

Node.js

Terminez le quiz du chapitre pour le marquer comme complété.

Tableau de bord

Système de fichiers et flux en Node.js

Module fs pour lire et écrire des fichiers, et streams pour traiter efficacement de grandes quantités de données de manière asynchrone.

Premier serveur HTTP en Node.js

Créer un serveur HTTP natif avec le module http, gérer les requêtes et réponses, et retourner du JSON — le point de départ de toute API Node.js.

Écosystème npm et package.json

On this page