Passer au contenu principal

​
📋 Fichier package.json pour Node.js

Le fichier package.json est le cœur de tout projet Node.js. Il agit comme un manifeste qui liste les dépendances, définit les scripts d’automatisation et configure le comportement du projet. Ce guide vous apprend à configurer un package.json robuste, garantissant que votre projet est reproductible, organisé et compatible avec l’environnement Square Cloud.
1

Initialiser le projet

La manière la plus sûre de créer le fichier est d’utiliser la CLI NPM. Placez-vous à la racine de votre projet et choisissez l’une des options :Option A : Interactive (Recommandée pour les débutants) Répondez aux questions étape par étape pour configurer des métadonnées personnalisées.
npm init
Option B : Automatique (Par défaut) Génère le fichier immédiatement en acceptant tous les paramètres par défaut.
npm init -y
2

Configurer les métadonnées essentielles

Ouvrez le package.json généré. Pour un projet professionnel, assurez-vous que ces champs sont correctement remplis :
  • name : Identifiant unique du projet (utilisez le kebab-case, par ex. my-project-api).
  • version : Suit la norme SemVer (par ex. 1.0.0).
  • main : Le point d’entrée de l’application (généralement index.js ou src/index.js).
  • type : Définissez-le sur "module" si vous utilisez les ES Modules (import/export) ou supprimez-le pour utiliser CommonJS (require).
3

Configurer les scripts d'exécution

La section scripts est essentielle pour l’automatisation. C’est ici que vous définissez comment votre application doit être démarrée, testée ou compilée.
"scripts": {
  "start": "node index.js",
  "test": "echo \"Error: no test specified\" && exit 1"
}
À propos de l’initialisation sur Square Cloud : Bien que l’environnement recherche des schémas courants, Square Cloud offre une flexibilité totale. Vous pouvez (et devriez) configurer explicitement quelle commande le système doit exécuter pour démarrer votre application.Par exemple, vous pouvez configurer la Commande de démarrage dans le dashboard ou dans le fichier de configuration Square pour exécuter npm run start, garantissant que le script défini ci-dessus est respecté.
4

Gérer les dépendances

Ici se trouvent les bibliothèques essentielles pour que votre code s’exécute en production. Pour installer et enregistrer automatiquement dans cette liste :
npm install package-name
Attention à devDependencies et au Build sur Square Cloud : Les outils utilisés uniquement en développement local (comme eslint ou prettier) restent dans devDependencies.
Important : Square Cloud effectue l’installation en mode production par défaut, ce qui signifie que les paquets listés dans devDependencies NE sont PAS installés.Si vous devez exécuter un processus de build dans le cloud (par ex. compiler du TypeScript ou exécuter des scripts post-install), vous devez déplacer ces outils vers dependencies. Sinon, le build échouera en raison de paquets manquants.
5

Utiliser les fonctionnalités avancées

Pour les projets plus complexes, package.json offre de puissantes fonctionnalités de contrôle :1. Overrides (Forcer les versions) : Utile lorsqu’une dépendance que vous utilisez installe une sous-dépendance présentant plusieurs vulnérabilités. Vous pouvez forcer la résolution vers une version sûre :
"overrides": {
  "vulnerable-package": "2.0.1"
}
2. Imports (Alias de chemins) : Évitez les longs chemins relatifs comme ../../../utils. Avec imports, vous créez des raccourcis internes natifs (nécessite une version récente de Node) :
"imports": {
  "#utils/*": "./src/utils/*.js",
  "#database": "./src/core/database.js"
}
Cela permet d’importer dans le code en utilisant import db from '#database'.

​
💡 Conseils et bonnes pratiques

  • Versionnage sémantique : Préférez figer les versions critiques en supprimant le ^ (par ex. utilisez "14.14.1" au lieu de "^14.14.1") pour empêcher les mises à jour automatiques de casser votre code en production.
  • Sécurité : Exécutez npm audit régulièrement pour identifier les vulnérabilités dans vos dépendances. Le champ overrides présenté ci-dessus est la solution idéale pour corriger ces problèmes.
  • Package-lock.json : Ne supprimez et n’ignorez jamais ce fichier dans .gitignore. C’est la garantie que Square Cloud installera l’arbre de dépendances exact qui fonctionnait sur votre machine.
  • Organisation : Gardez le fichier propre. Si la section scripts devient trop volumineuse, envisagez d’utiliser des outils d’automatisation externes ou de la répartir dans des fichiers.

​
📄 Exemple de fichier final

Ci-dessous, un exemple de package.json moderne et optimisé :
package.json
{
  "name": "square-cloud-project",
  "version": "1.0.0",
  "description": "Professional Node.js API",
  "main": "src/index.js",
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "lint": "eslint ."
  },
  "imports": {
    "#services/*": "./src/services/*.js"
  },
  "dependencies": {
    "discord.js": "14.14.1",
    "dotenv": "16.3.1",
    "typescript": "5.3.3" 
  },
  "devDependencies": {
    "eslint": "8.56.0"
  }
}

​
🚀 Étapes suivantes

Une fois votre fichier package.json configuré :
  1. Committez-le dans votre dépôt Git.
  2. Hébergez votre projet sur Square Cloud.
  3. Configurez le deploy automatique via GitHub.
  4. Bienvenue dans l’hébergement professionnel d’applications Node.js !
Un fichier package.json bien structuré est la base de toute application Node.js réussie, garantissant que votre application fonctionne parfaitement sur Square Cloud.