L'ecosistema Angular è uno dei più robusti e scalabili nel panorama dello sviluppo frontend. Grazie alla sua architettura modulare e al supporto continuo della community, Angular si evolve rapidamente, introducendo nuove funzionalità, miglioramenti delle prestazioni e aggiornamenti di sicurezza. Tuttavia, mantenere un progetto aggiornato alle ultime versioni può essere una sfida, soprattutto per applicazioni di grandi dimensioni o legacy.

In questo tutorial, esploreremo passo dopo passo come aggiornare un progetto Angular a una versione superiore, riducendo al minimo i rischi di incompatibilità e downtime. Affronteremo non solo l'aggiornamento del framework, ma anche delle dipendenze principali, delle librerie di terze parti e dei test automatizzati. Inoltre, vedremo come risolvere i problemi più comuni che possono emergere durante il processo.

Che tu sia uno sviluppatore esperto o un neofita di Angular, questa guida ti fornirà tutti gli strumenti necessari per affrontare l'aggiornamento in modo consapevole e strutturato. Aggiornare regolarmente il tuo progetto non solo garantisce la sicurezza del codice, ma ti permette di sfruttare appieno le innovazioni offerte dal team di Angular, mantenendo la tua applicazione performante e al passo con i tempi.

Verifica dei prerequisiti

Prima di aggiornare un progetto Angular, è importante assicurarsi che il tuo ambiente di sviluppo sia configurato correttamente. La versione di Node.js è uno degli elementi più critici, in quanto Angular richiede una versione specifica per funzionare. Per verificare quale versione hai attualmente installato, utilizza il comando:

node -v

Confronta questa versione con i requisiti indicati nella documentazione ufficiale di Angular.

Se la versione di Node.js non è compatibile, è consigliabile utilizzare nvm (Node Version Manager), uno strumento indispensabile per gestire più versioni di Node.js sullo stesso sistema. Con nvm puoi passare rapidamente da una versione di Node.js all'altra senza modificare manualmente l'ambiente. Per installare nvm, segui le istruzioni fornite nella pagina ufficiale di nvm su GitHub.

Dopo aver installato nvm, verifica che funzioni correttamente con il comando:

nvm --version

Successivamente, puoi installare la versione di Node.js richiesta dal tuo progetto con:

nvm install <versione>

Attiva la versione installata con:

nvm use <versione>

Infine, verifica di avere una versione aggiornata di npm (Node Package Manager) con:

npm -v

Se necessario, aggiorna npm utilizzando:

npm install -g npm

Utilizzo del comando `ng update`

Una volta verificati i prerequisiti e configurato correttamente l'ambiente di sviluppo, il comando ng update ci permette di controllare rapidamente quali pacchetti possono essere aggiornati nel progetto Angular. Questo comando analizza le dipendenze del progetto e suggerisce i passaggi necessari per portarle alla versione più recente supportata.

Per iniziare, assicurati di trovarti nella directory principale del progetto Angular e lancia il comando:

ng update

Questo comando restituirà una lista dei pacchetti che possono essere aggiornati, suddivisi in due sezioni: Major Updates (aggiornamenti principali) e Minor Updates (aggiornamenti minori o patch). Ad esempio, potresti vedere un output simile:

Using package manager: npm
Collecting installed dependencies...
Found 2 dependencies.
    @angular/cli                       17.1.0 -> 19.0.0
    @angular/core                      17.1.0 -> 19.0.0
Run "ng update @angular/cli @angular/core" to update.

Per applicare gli aggiornamenti consigliati, puoi utilizzare lo stesso comando fornito nell'output:

ng update @angular/cli@19 @angular/core@19

Se desideri aggiornare tutte le dipendenze del progetto, puoi utilizzare il comando:

ng update --all

Tuttavia, aggiorna tutto con attenzione, poiché potrebbero verificarsi breaking changes o incompatibilità tra i pacchetti. Dopo l'aggiornamento, verifica sempre che l'applicazione funzioni come previsto eseguendo un build e i test unitari.

Problema delle dipendenze incompatibili durante l'aggiornamento

Quando esegui il comando ng update, può capitare di incorrere in un errore come questo:

Fetching dependency metadata from registry...
Package "ngx-cookie-service-ssr" has an incompatible peer dependency to "@angular/ssr" (requires "^17.0.0", would install "18.2.12").
✖ Migration failed: Incompatible peer dependencies found.
Peer dependency warnings when installing dependencies means that those dependencies might not work correctly together.
You can use the '--force' option to ignore incompatible peer dependencies and instead address these warnings later.
  See "/tmp/ng-nWvJ7G/angular-errors.log" for further details.

Questo errore si verifica quando una dipendenza nel file package.json richiede una versione di un'altra libreria (in questo caso, @angular/ssr) che non è compatibile con la versione che si sta cercando di installare. Di conseguenza, l'aggiornamento viene interrotto per evitare potenziali malfunzionamenti.

Per risolvere il problema, la prima cosa da fare è verificare quali pacchetti stanno causando il conflitto. Nella maggior parte dei casi, dovrai aggiornare manualmente le dipendenze incompatibili. Per esempio, nell'errore riportato, il pacchetto ngx-cookie-service-ssr richiede la versione ^17.0.0 di @angular/ssr, ma l'aggiornamento propone di installare la versione 18.2.12. Puoi controllare se una versione aggiornata del pacchetto è disponibile, visitando la pagina npm del pacchetto, come nel caso di ngx-cookie-service-ssr.

Se una versione aggiornata non è disponibile, potresti considerare di cercare un pacchetto alternativo o decidere se il pacchetto è realmente necessario per il progetto.

Nel caso in cui non riesca a risolvere immediatamente il conflitto, puoi procedere con un aggiornamento forzato utilizzando l'opzione --force. Tuttavia, tieni presente che questa opzione ignora i conflitti e potrebbe causare problemi a livello di runtime se le dipendenze non sono compatibili tra loro. Esegui il comando:

ng update --force

Assicurati comunque di testare l'applicazione in modo approfondito per verificare eventuali malfunzionamenti.

Un altro problema che può bloccare l'aggiornamento è quando ci sono modifiche locali non salvate nel repository Git. In questo caso, riceverai un errore simile a questo:

Error: Repository is not clean. Please commit or stash any changes before updating.

Per risolvere, basta fare il commit delle modifiche non salvate con:

git add .
git commit -m "Salvataggio modifiche prima dell'aggiornamento"

Se non vuoi fare il commit, puoi accantonare temporaneamente le modifiche con:

git stash

Dopo aver aggiornato il progetto, potrai riprendere le modifiche con:

git stash pop

Aggiornamento delle dipendenze e risoluzione dei conflitti

Dopo l'aggiornamento, è sempre una buona idea controllare se ci sono dipendenze obsolete o vulnerabilità con:

npm audit fix --force

Questo comando prova a risolvere automaticamente i problemi di sicurezza e aggiornare i pacchetti in base alle versioni compatibili. Tuttavia, forzare le modifiche può rompere il progetto se qualche pacchetto aggiornato non è compatibile con il resto delle dipendenze.

Se dopo l'aggiornamento alcuni pacchetti risultano incompatibili o generano errori, il primo passo è rimuoverli e reinstallarli:

npm uninstall <nome-pacchetto> && npm install <nome-pacchetto>

Ma non sempre è così semplice. Alcuni pacchetti potrebbero richiedere versioni specifiche di altre dipendenze, quindi dovrai controllare la loro compatibilità direttamente sulla documentazione ufficiale di Angular o sulla pagina del pacchetto su npmjs.com.

Se un pacchetto non è aggiornato e causa problemi, verifica quale sia l'ultima versione stabile compatibile con la tua versione di Angular. Puoi farlo con:

npm show <nome-pacchetto> versions

Se serve una versione specifica, installala direttamente:

npm install <nome-pacchetto>@<versione>

A volte, dopo l'aggiornamento, alcuni pacchetti risultano ancora rotti. In questi casi, il metodo più drastico ma efficace è eliminare la cartella node_modules e il file package-lock.json, poi reinstallare tutto da zero:

rm -rf node_modules package-lock.json  
npm install

Eseguire le Migrazioni Angular

Dopo aver aggiornato i pacchetti, potrebbe essere necessario eseguire le migrazioni per applicare le modifiche ai file di configurazione e al codice. Angular non aggiorna solo le dipendenze, ma a volte richiede modifiche specifiche ai file del progetto.

Se provi a eseguire:

ng update --migrate-only

Riceverai un errore, perché il comando richiede un pacchetto specifico. Per eseguire le migrazioni dopo aver aggiornato Angular Core, usa:

ng update @angular/core --migrate-only --from=17 --to=19

Se hai aggiornato anche l’Angular CLI, potresti dover eseguire anche:

ng update @angular/cli --migrate-only --from=17 --to=19

Se hai aggiornato più pacchetti, dovrai eseguire il comando per ognuno di essi. Questo passaggio assicura che i tuoi file di configurazione vengano adattati alle nuove versioni senza che Angular modifichi di nuovo package.json o reinstalli i pacchetti.

Alla fine del processo, testa il progetto, avvia l’app con ng serve e verifica che tutto funzioni senza errori. Se ci sono problemi, potresti dover risolvere manualmente alcune dipendenze o fare un downgrade di qualche pacchetto per garantire la compatibilità.

Verifica dei prerequisiti

Utilizzo del comando ng update

Problema delle dipendenze incompatibili durante l'aggiornamento

Aggiornamento delle dipendenze e risoluzione dei conflitti

Eseguire le Migrazioni Angular

Utilizzo del comando `ng update`