Skip to main content
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.
Opzione B: Automatica (Predefinita) Genera il file immediatamente accettando tutte le impostazioni predefinite.
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.
A proposito dell’inizializzazione su Square Cloud: Per impostazione predefinita, Square Cloud esegue node MAIN (il file impostato in MAIN), ma 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:
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:
2. Imports (Alias di percorso): Evita lunghi percorsi relativi come ../../../utils. Con imports, crei scorciatoie interne native (richiede una versione recente di Node):
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: Tienilo in Git: registra l’esatto albero delle dipendenze che ha funzionato sulla tua macchina. La CLI di Square Cloud e l’estensione per VS Code escludono i lockfile dai caricamenti per impostazione predefinita, quindi Square Cloud installa le versioni più recenti consentite dagli intervalli in package.json. Quando ti servono le versioni fissate, includilo di nuovo con !package-lock.json nel tuo squarecloud.ignore.
  • 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

​
Prossimi passi

Con il tuo file package.json configurato:
  1. Effettua il commit nel tuo repository Git.
  2. Ospita il tuo progetto con la guida al runtime Node.js, oppure segui una guida a un framework come Express o Next.js.
  3. Fai il deploy automatico da GitHub a ogni push.