NPM, Vite e struttura progetto

NPM è un package manager: ti aiuta a installare, aggiornare e registrare le librerie usate dal progetto.

Vite invece è un build tool e dev server: durante lo sviluppo serve i file in locale, aggiorna velocemente la pagina e, quando serve, genera la cartella finale per la pubblicazione.

In pratica lavorano insieme:

• NPM legge package.json e installa quello che serve;
• gli script NPM ti danno comandi brevi e condivisi;
• Vite avvia il server locale o crea la build finale;
• la cartella di output, spesso dist, è quella che poi finisce online.

Il vantaggio non è avere più strumenti per complicarsi la vita. È avere un modo prevedibile per far girare lo stesso progetto su più computer e in deploy.

Il file package.json è una specie di carta d'identità tecnica del progetto.

Dentro trovi informazioni come nome, versione, script e dipendenze. Non devi ricordare tutto a memoria, ma devi sapere dove guardare quando vuoi capire come si avvia o si costruisce il progetto.

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {},
  "devDependencies": {
    "vite": "^8.0.7"
  }
}

La parte più utile all'inizio è scripts: contiene i comandi ufficiali del progetto. Se lavori in team o riprendi un progetto dopo mesi, è il primo posto da controllare.

Gli script sono scorciatoie condivise. Invece di ricordare ogni comando interno, usi comandi stabili come questi:

npm install
npm run dev
npm run build
npm run preview

• npm install installa le dipendenze dichiarate nel progetto;
• npm run dev avvia il server locale di sviluppo;
• npm run build genera la versione finale;
• npm run preview prova localmente la build prodotta.

Questa distinzione è importante: dev serve mentre lavori, build serve per preparare l'output, preview serve per controllare l'output finale prima del deploy.

Una dipendenza è un pacchetto esterno usato dal progetto: una libreria, un tool, un plugin o un framework.

Quando esegui npm install, NPM scarica i pacchetti dentro node_modules. Quella cartella può diventare enorme e normalmente non va committata su Git.

I file importanti da tenere nel repository sono invece:

• package.json, perché dichiara cosa serve al progetto;
• package-lock.json, perché blocca versioni precise e rende le installazioni più ripetibili;
• .gitignore, perché evita di tracciare cartelle generate come node_modules e dist.

Se cloni un progetto da zero, non copi node_modules: installi di nuovo le dipendenze con npm install.

Il working tree è la cartella di lavoro del progetto sul tuo computer. È il posto concreto in cui vedi file, cartelle, modifiche locali, dipendenze installate e output generati.

Quando apri un progetto in VSCode, quello che stai guardando è il working tree. Quando Git ti dice che hai file modificati, non tracciati o puliti, sta leggendo lo stato di questa cartella rispetto all'ultimo commit.

Dentro al working tree convivono cose diverse:

• file tracciati da Git, come package.json, src, pages e configurazioni;
• file modificati ma non ancora committati;
• file non tracciati, appena creati e non ancora aggiunti a Git;
• cartelle ignorate, come node_modules, che servono localmente ma non vanno nel repository;
• output generati, come dist, che arrivano dalla build e non dovrebbero essere modificati a mano.

Capire questa distinzione evita molta confusione: non tutto quello che vedi nella cartella ha lo stesso ruolo, e non tutto deve essere committato.

Ogni progetto può organizzarsi in modo diverso, ma alcune cartelle ricorrono spesso.

src

contiene sorgenti: CSS, JS, componenti, immagini importate dal codice e logica dell'app.

public

contiene file serviti così come sono: favicon, manifest, immagini statiche o asset che non passano dal bundler.

pages

in questo progetto raccoglie le pagine HTML sorgente usate da Vite come entry.

dist

è l'output generato dalla build. Si controlla, ma normalmente non si modifica a mano.

La regola mentale è semplice: lavori sui sorgenti, lasci che gli strumenti generino l'output e pubblichi ciò che la build produce.

Durante lo sviluppo usi il server locale. È veloce, comodo e pensato per lavorare.

La build invece è un passaggio diverso: Vite prende i sorgenti, risolve import, ottimizza asset e genera file finali. In molti progetti questi file finiscono in dist.

Per questo è utile fare almeno una build locale prima di pubblicare:

npm run build
npm run preview

Se la build fallisce in locale, fallirà molto probabilmente anche sul servizio di hosting. Meglio scoprirlo prima, quando puoi leggere l'errore con calma e sistemarlo.

Quando apri o riprendi un progetto NPM/Vite, puoi seguire questa routine:

1. controlla package.json per capire gli script disponibili;
2. esegui npm install se le dipendenze non sono installate;
3. avvia npm run dev per lavorare in locale;
4. modifica i sorgenti, non l'output generato;
5. prima del deploy esegui npm run build;
6. se disponibile, usa npm run preview per controllare la build finale.

Questa routine ti evita molti falsi problemi: dipendenze mancanti, script sbagliato, output vecchio o cartelle generate modificate a mano.

Quando qualcosa si rompe, spesso il problema rientra in pochi casi ricorrenti.

• npm install non è stato eseguito dopo clone, pull o cambio branch.
• Stai usando uno script che non esiste in package.json.
• Una dipendenza è in devDependencies ma viene usata come se fosse runtime.
• Hai modificato dist invece dei file sorgente.
• La build funziona in dev ma fallisce perché c'è un path, import o asset non corretto.
• Il provider di deploy usa una versione Node diversa da quella locale.

Il primo passo non è cambiare tutto. Leggi il messaggio di errore, guarda quale comando stava girando e torna al file che definisce quel comando.

Quando capisci NPM, Vite e struttura progetto, molte parti del workflow diventano meno misteriose: perché esistono le dipendenze, cosa fa una build, cosa va online e cosa resta solo in sviluppo.

Da qui puoi collegare meglio le altre guide:

• VSCode essenziale: per usare terminale integrato, task e debug con più ordine.
• Browser e DevTools: per controllare cosa arriva davvero nel browser.
• Deploy base: per capire come la build viene pubblicata online.
• Git pratico senza panico: per salvare modifiche e tornare indietro senza ansia.

Ecco la tabella di riferimento rapido per la gestione dei pacchetti NPM e comandi Vite:

Crea il tuo primo progetto guidato da terminale usando NPM: