Vai al contenuto principale

​
📋 File package.json per Node.js

Il file package.json è il cuore di qualsiasi progetto Node.js. Funge da manifesto che elenca le dipendenze, definisce gli script di automazione e configura il comportamento del progetto. Questa guida insegna come configurare un package.json robusto, garantendo che il tuo progetto sia riproducibile, organizzato e compatibile con l’ambiente di Square Cloud.
1

Inizializza il progetto

Il modo più sicuro per creare il file è utilizzare la CLI di NPM. Naviga alla radice del tuo progetto e scegli una delle opzioni:Opzione A: Interattiva (Consigliata per i principianti) Rispondi alle domande passo dopo passo per configurare metadati personalizzati.
npm init
Opzione B: Automatica (Predefinita) Genera il file immediatamente accettando tutte le impostazioni predefinite.
npm init -y
2

Configura i metadati essenziali

Apri il package.json generato. Per un progetto professionale, assicurati che questi campi siano compilati correttamente:
  • name: Identificatore univoco del progetto (usa kebab-case, ad es. my-project-api).
  • version: Segue lo standard SemVer (ad es. 1.0.0).
  • main: Il punto di ingresso dell’applicazione (di solito index.js o src/index.js).
  • type: Imposta come "module" se usi ES Modules (import/export) oppure rimuovilo per usare CommonJS (require).
3

Configura gli script di esecuzione

La sezione scripts è fondamentale per l’automazione. È qui che definisci come la tua applicazione deve essere avviata, testata o compilata.
"scripts": {
  "start": "node index.js",
  "test": "echo \"Error: no test specified\" && exit 1"
}
A proposito dell’inizializzazione su Square Cloud: Sebbene l’ambiente cerchi pattern comuni, Square Cloud offre piena flessibilità. Puoi (e dovresti) configurare esplicitamente quale comando il sistema deve eseguire per avviare la tua applicazione.Ad esempio, puoi configurare il Start Command nella dashboard o nel file di configurazione di Square per eseguire npm run start, assicurando che lo script definito sopra venga rispettato.
4

Gestisci le dipendenze

Qui risiedono le librerie essenziali affinché il tuo codice venga eseguito in produzione. Per installare e salvare automaticamente in questo elenco:
npm install package-name
Attenzione a devDependencies e Build su Square Cloud: Gli strumenti utilizzati solo nello sviluppo locale (come eslint o prettier) restano in devDependencies.
Importante: Square Cloud esegue l’installazione in modalità produzione per impostazione predefinita, il che significa che i pacchetti elencati in devDependencies NON vengono installati.Se hai bisogno di eseguire un processo di build nel cloud (ad es. compilare TypeScript o eseguire script post-install), devi spostare questi strumenti in dependencies. In caso contrario, la build fallirà a causa dei pacchetti mancanti.
5

Usa le funzionalità avanzate

Per progetti più complessi, package.json offre potenti funzionalità di controllo:1. Overrides (Forzare le versioni): Utile quando una dipendenza che usi installa una sotto-dipendenza con più vulnerabilità. Puoi forzare la risoluzione a una versione sicura:
"overrides": {
  "vulnerable-package": "2.0.1"
}
2. Imports (Alias di percorso): Evita lunghi percorsi relativi come ../../../utils. Con imports, crei scorciatoie interne native (richiede una versione recente di Node):
"imports": {
  "#utils/*": "./src/utils/*.js",
  "#database": "./src/core/database.js"
}
Questo consente di importare nel codice usando import db from '#database'.

​
💡 Consigli e buone pratiche

  • Versionamento semantico: Preferisci fissare le versioni critiche rimuovendo ^ (ad es. usa "14.14.1" invece di "^14.14.1") per evitare che gli aggiornamenti automatici compromettano il tuo codice in produzione.
  • Sicurezza: Esegui npm audit regolarmente per identificare le vulnerabilità nelle tue dipendenze. Il campo overrides illustrato sopra è la soluzione ideale per risolvere questi problemi.
  • Package-lock.json: Non eliminare né ignorare mai questo file in .gitignore. È la garanzia che Square Cloud installerà l’esatto albero delle dipendenze che ha funzionato sulla tua macchina.
  • Organizzazione: Mantieni il file pulito. Se la sezione scripts diventa troppo grande, considera l’uso di strumenti di automazione esterni o la suddivisione in file.

​
📄 Esempio finale di file

Di seguito, un esempio di un package.json moderno e ottimizzato:
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"
  }
}

​
🚀 Prossimi passi

Con il tuo file package.json configurato:
  1. Effettua il commit nel tuo repository Git.
  2. Ospita il tuo progetto su Square Cloud.
  3. Configura il deploy automatico tramite GitHub.
  4. Benvenuto nell’hosting professionale di applicazioni Node.js!
Un file package.json ben strutturato è la base per qualsiasi applicazione Node.js di successo, garantendo che la tua applicazione funzioni perfettamente su Square Cloud.