- Générateur package.json Node.js

Comprendre le fichier package.json

Pour qui : Développeurs Node.js, intégrateurs front-end, équipes Angular/React/Next.js, créateurs de bibliothèques npm.

Le fichier package.json est le manifeste central de tout projet JavaScript/Node.js. Placé à la racine du projet, il remplit plusieurs rôles essentiels :

• ✔ Identité du projet — nom, version, description, auteur, licence
• ✔ Gestion des dépendances — liste tous les packages npm nécessaires
• ✔ Scripts d'automatisation — raccourcis pour build, test, lint, déploiement
• ✔ Contraintes d'environnement — versions Node.js et npm requises
• ✔ Métadonnées de publication — informations pour npmjs.com si vous publiez

// package.json minimal — seuls name et version sont obligatoires pour npm
{
  "name": "mon-projet",
  "version": "1.0.0"
}

// package.json complet — application Angular typique
{
  "name": "mon-app-angular",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build",
    "test": "ng test"
  },
  "dependencies": {
    "@angular/core": "^19.0.0",
    "rxjs": "~7.8.0"
  },
  "devDependencies": {
    "@angular/cli": "^19.0.0",
    "typescript": "^5.5.0"
  }
}

Les champs essentiels expliqués

name et version — identité du package

Ces deux champs sont obligatoires si vous publiez sur npm. Le name doit être unique sur le registre npm, en minuscules, sans espaces (tirets autorisés). La version suit le Semantic Versioning (MAJOR.MINOR.PATCH).

// Conventions de nommage
"name": "mon-projet"            // ✅ Basique
"name": "@scope/mon-projet"     // ✅ Package scopé (organisation ou user npm)
"name": "Mon Projet"            // ❌ Espaces et majuscules interdits
"name": "mon_projet"            // ⚠️ Déconseillé (tirets préférés)

// Versioning sémantique
"version": "1.0.0"   // Version stable initiale
"version": "0.1.0"   // Avant la v1 — API instable
"version": "2.3.1"   // Bugfix en patch (2.3.0 → 2.3.1)
"version": "2.4.0"   // Nouvelle fonctionnalité rétrocompatible
"version": "3.0.0"   // Breaking change — majeur

private — protéger contre la publication accidentelle

// ✅ Recommandé pour toutes les applications (pas les libs)
{
  "private": true
}
// npm refusera de publier ce package même avec npm publish
// Idéal pour les apps Angular, React, Next.js, Node.js privées

type — format de modules JavaScript

// "module" → tous les .js sont traités comme ESM (import/export)
{
  "type": "module"
}
// Requis pour utiliser import/export sans bundler (Node.js 12+)
// Vite et les bibliothèques modernes utilisent ce mode

// Omis ou "commonjs" → tous les .js utilisent require/module.exports
// Par défaut pour Node.js classique et Express

// Exemple de coexistence : .mjs pour ESM, .cjs pour CommonJS
// indépendamment de la valeur de "type"

main, module et exports — points d'entrée

// Bibliothèque avec plusieurs formats
{
  "name": "ma-lib",
  "main": "./dist/index.cjs",          // CommonJS — Node.js classique
  "module": "./dist/index.mjs",        // ESM — bundlers modernes
  "types": "./dist/index.d.ts",        // Types TypeScript
  "exports": {
    ".": {
      "import": "./dist/index.mjs",    // import ma-lib
      "require": "./dist/index.cjs",   // require('ma-lib')
      "types": "./dist/index.d.ts"
    },
    "./utils": {
      "import": "./dist/utils.mjs",
      "require": "./dist/utils.cjs"
    }
  }
}
// Le champ "exports" est prioritaire sur "main" en Node.js 12+

Scripts npm — automatiser votre workflow

Les scripts npm permettent de standardiser les commandes de votre projet. Tout script défini dans "scripts" s'exécute avec npm run <nom>.

Scripts conventionnels reconnus par npm

{
  "scripts": {
    // Cycle de vie spéciaux (npm start / npm test — sans "run")
    "start":      "node dist/index.js",         // npm start
    "test":       "jest --coverage",            // npm test
    "stop":       "pm2 stop all",               // npm stop

    // Hooks pré/post — s'exécutent automatiquement avant/après
    "prebuild":   "npm run lint",               // Avant npm run build
    "build":      "tsc && vite build",          // npm run build
    "postbuild":  "cp -r public dist/",         // Après npm run build
    "pretest":    "npm run build",              // Avant npm test

    // Scripts personnalisés
    "dev":        "vite",                       // npm run dev
    "lint":       "eslint src --ext .ts,.tsx",  // npm run lint
    "format":     "prettier --write \"src/**\"",// npm run format
    "typecheck":  "tsc --noEmit",              // npm run typecheck
    "clean":      "rimraf dist",               // npm run clean
    "ci":         "npm run lint && npm test && npm run build"
  }
}

Scripts Angular CLI

// Angular utilise ng comme runner — Angular CLI doit être installé
{
  "scripts": {
    "ng":     "ng",
    "start":  "ng serve",                   // http://localhost:4200
    "build":  "ng build",                   // Production build
    "watch":  "ng build --watch --configuration development",
    "test":   "vitest run",                 // Tests Vitest
    "lint":   "ng lint",                    // ESLint via Angular CLI
    "e2e":    "ng e2e",                     // Tests end-to-end
    "analyze":"ng build --stats-json && webpack-bundle-analyzer dist/stats.json"
  }
}

Scripts avec variables d'environnement

// cross-env pour compatibilité Windows/Mac/Linux
// npm install --save-dev cross-env
{
  "scripts": {
    "build:prod":    "cross-env NODE_ENV=production webpack",
    "build:staging": "cross-env NODE_ENV=staging vite build",
    "start:debug":   "cross-env DEBUG=* node dist/index.js"
  }
}

// npm-run-all pour exécuter plusieurs scripts en parallèle ou en séquence
// npm install --save-dev npm-run-all
{
  "scripts": {
    "start":     "run-p server watch:css watch:ts",  // Parallèle
    "server":    "node src/server.js",
    "watch:css": "sass --watch src/scss:dist/css",
    "watch:ts":  "tsc --watch"
  }
}

Gérer les dépendances efficacement

Différence entre dependencies et devDependencies

Syntaxe des versions npm (SemVer)

// Syntaxe des intervalles de versions dans package.json
{
  "dependencies": {
    "react":   "18.3.1",    // Version exacte — risqué en pratique
    "express": "^4.21.0",   // ^ = >=4.21.0 <5.0.0 (MAJOR figé) ← recommandé
    "lodash":  "~4.17.21",  // ~ = >=4.17.21 <4.18.0 (MINOR figé)
    "axios":   ">=1.0.0",   // >= = toute version ≥ 1.0.0 (peu restrictif)
    "jest":    "*",          // * = n'importe quelle version (dangereux !)
    "vite":    "latest"      // latest = dernière publiée (très risqué)
  }
}

// Bonne pratique : ^ (caret) est le choix par défaut de npm install
// Il permet les mises à jour patch et minor automatiques

devDependencies recommandées par type de projet

// Projet TypeScript universel (minimum recommandé)
{
  "devDependencies": {
    "typescript":                      "^5.5.0",
    "@typescript-eslint/eslint-plugin": "^7.18.0",
    "@typescript-eslint/parser":        "^7.18.0",
    "eslint":                          "^8.57.0",
    "prettier":                        "^3.3.0"
  }
}

// Tests — Jest (Node.js / Express)
{
  "devDependencies": {
    "jest":       "^29.7.0",
    "ts-jest":    "^29.2.0",
    "@types/jest": "^29.5.0"
  }
}

// Tests — Vitest (Vite / React / bibliothèques)
{
  "devDependencies": {
    "vitest":              "^1.6.0",
    "@vitest/coverage-v8": "^1.6.0"
  }
}

// Git hooks — Husky + lint-staged
{
  "devDependencies": {
    "husky":      "^9.0.0",
    "lint-staged": "^15.2.0"
  },
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md}": ["prettier --write"]
  }
}

Configurations par framework

Angular 19 — package.json complet

{
  "name": "mon-app-angular",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "ng":    "ng",
    "start": "ng serve",
    "build": "ng build",
    "watch": "ng build --watch --configuration development",
    "test":  "ng test",
    "lint":  "ng lint"
  },
  "dependencies": {
    "@angular/animations":                "^19.0.0",
    "@angular/common":                    "^19.0.0",
    "@angular/compiler":                  "^19.0.0",
    "@angular/core":                      "^19.0.0",
    "@angular/forms":                     "^19.0.0",
    "@angular/platform-browser":          "^19.0.0",
    "@angular/platform-browser-dynamic":  "^19.0.0",
    "@angular/router":                    "^19.0.0",
    "rxjs":                               "~7.8.0",
    "tslib":                              "^2.6.0",
    "zone.js":                            "~0.14.0"
  },
  "devDependencies": {
    "@angular-devkit/build-angular":       "^19.0.0",
    "@angular/cli":                        "^19.0.0",
    "@angular/compiler-cli":               "^19.0.0",
    "typescript":                          "~5.5.0",
    "@typescript-eslint/eslint-plugin":    "^7.18.0",
    "@typescript-eslint/parser":           "^7.18.0",
    "eslint":                             "^8.57.0"
  }
}

React 18 + Vite + TypeScript

{
  "name": "mon-app-react",
  "version": "0.1.0",
  "type": "module",
  "private": true,
  "scripts": {
    "dev":     "vite",
    "build":   "tsc && vite build",
    "preview": "vite preview",
    "lint":    "eslint . --ext ts,tsx",
    "test":    "vitest"
  },
  "dependencies": {
    "react":     "^18.3.0",
    "react-dom": "^18.3.0"
  },
  "devDependencies": {
    "@types/react":                    "^18.3.0",
    "@types/react-dom":                "^18.3.0",
    "@typescript-eslint/eslint-plugin": "^7.18.0",
    "@typescript-eslint/parser":        "^7.18.0",
    "@vitejs/plugin-react":            "^4.3.0",
    "eslint":                          "^8.57.0",
    "typescript":                      "^5.5.0",
    "vite":                            "^5.4.0",
    "vitest":                          "^1.6.0"
  }
}

Node.js + Express — API REST TypeScript

{
  "name": "mon-api-nodejs",
  "version": "1.0.0",
  "main": "dist/index.js",
  "private": true,
  "scripts": {
    "start":  "node dist/index.js",
    "dev":    "ts-node-dev --respawn src/index.ts",
    "build":  "tsc",
    "test":   "jest --coverage",
    "lint":   "eslint src/**/*.ts",
    "format": "prettier --write \"src/**/*.ts\""
  },
  "engines": {
    "node": ">=18.0.0",
    "npm":  ">=9.0.0"
  },
  "dependencies": {
    "cors":    "^2.8.5",
    "dotenv":  "^16.4.0",
    "express": "^4.21.0",
    "helmet":  "^7.2.0",
    "morgan":  "^1.10.0"
  },
  "devDependencies": {
    "@types/cors":                     "^2.8.0",
    "@types/express":                  "^4.17.0",
    "@types/morgan":                   "^1.9.0",
    "@types/node":                     "^20.0.0",
    "@typescript-eslint/eslint-plugin": "^7.18.0",
    "@typescript-eslint/parser":        "^7.18.0",
    "eslint":      "^8.57.0",
    "jest":        "^29.7.0",
    "prettier":    "^3.3.0",
    "ts-jest":     "^29.2.0",
    "ts-node-dev": "^2.0.0",
    "typescript":  "^5.5.0"
  }
}

Champs avancés — exports, engines, workspaces

workspaces — monorepos npm

// package.json racine du monorepo
{
  "name": "monorepo",
  "private": true,
  "workspaces": [
    "packages/*",       // Tous les sous-dossiers de packages/
    "apps/*"            // Toutes les applications
  ],
  "scripts": {
    "build": "npm run build --workspaces",          // Tous les workspaces
    "test":  "npm run test -w packages/core",        // Workspace spécifique
    "dev":   "npm run dev -w apps/web"
  }
}

// Installation cross-workspace
// npm install lodash -w packages/utils  → dans packages/utils uniquement
// npm install -g @angular/cli           → global (pas dans workspaces)

engines — contraindre Node.js et gestionnaires de paquets

{
  "engines": {
    "node":  ">=18.0.0",    // Node.js 18 LTS minimum
    "npm":   ">=9.0.0",     // npm 9+ requis
    "yarn":  ">=4.0.0"      // Si Yarn est utilisé
  },
  // Avec "engineStrict": true dans .npmrc, npm refusera de fonctionner
  // si la version Node.js actuelle ne correspond pas

  // packageManager — verrouillage avec Corepack (Node.js 16+)
  "packageManager": "pnpm@9.1.0"  // Force pnpm 9.1.0 via Corepack
}

files — contrôle des fichiers publiés sur npm

// Pour une bibliothèque publiée sur npm
{
  "files": [
    "dist",           // Dossier build uniquement
    "README.md",
    "LICENSE"
    // ❌ src/, tests/, .env, node_modules/ sont exclus automatiquement
  ]
}
// Alternative : .npmignore (comme .gitignore mais pour npm publish)

config — variables de configuration

{
  "config": {
    "port":   "3000",
    "prefix": "/api/v1"
  }
}
// Accessible dans les scripts npm via process.env.npm_package_config_port
// Override possible : npm config set mon-projet:port 8080

Erreurs courantes et bonnes pratiques

Erreur : "Cannot find module" après npm install

// ❌ Problème : package dans devDependencies mais utilisé en production
// Le serveur Node.js plante en prod car npm install --production n'installe
// pas les devDependencies
{
  "dependencies": { },
  "devDependencies": {
    "express": "^4.21.0"  // ❌ Express doit être dans dependencies !
  }
}

// ✅ Solution
{
  "dependencies": {
    "express": "^4.21.0"  // ✅ Runtime → production
  },
  "devDependencies": {
    "@types/express": "^4.17.0"  // Types seulement → dev
  }
}

Erreur : "peer dep conflict" avec npm 7+

// Depuis npm 7, les peer conflicts bloquent l'installation
// Solution 1 : --legacy-peer-deps (contourne les vérifications)
npm install --legacy-peer-deps

// Solution 2 : Vérifier les incompatibilités
npm ls            // Voir l'arbre de dépendances
npm outdated      // Voir les versions dépassées

// Solution 3 : Forcer la résolution avec overrides (npm 8.3+)
{
  "overrides": {
    "semver": "^7.5.2"  // Force une version spécifique d'un sous-package
  }
}

Sécurité — audit des dépendances

// Audit de sécurité npm
npm audit                   // Rapport des vulnérabilités
npm audit fix               // Corrige automatiquement les safe updates
npm audit fix --force       // Force la mise à jour (peut casser l'API !)

// Mise à jour contrôlée des dépendances
npm update                  // Respecte les contraintes SemVer (^ ou ~)
npx npm-check-updates       // Affiche toutes les mises à jour disponibles
npx npm-check-updates -u    // Met à jour package.json vers les dernières

// Pinning des versions pour la reproductibilité CI/CD
// Toujours committer package-lock.json dans git !

Bonnes pratiques organisation package.json

// ✅ Ordre conventionnel des champs (lisibilité)
{
  "name":             "",   // 1. Identité
  "version":          "",
  "description":      "",
  "keywords":         [],
  "author":           "",
  "license":          "",
  "private":          true,
  "type":             "",   // 2. Configuration module
  "main":             "",
  "module":           "",
  "exports":          {},
  "types":            "",
  "files":            [],   // 3. Publication
  "scripts":          {},   // 4. Scripts
  "engines":          {},   // 5. Contraintes d'environnement
  "dependencies":     {},   // 6. Dépendances (prod en premier)
  "devDependencies":  {},
  "peerDependencies": {}
}