Guida alla configurazione indipendente delle versioni Node.js per progetto con ServBay (macOS)

ServBay è un potente ambiente di sviluppo web locale pensato per gli sviluppatori, che offre una soluzione completa e integrata comprendente diversi linguaggi di programmazione (incluso Node.js), database e web server. Uno dei principali punti di forza di ServBay è il supporto nativo e la gestione flessibile di più versioni di Node.js. Con un semplice file di configurazione, puoi assegnare facilmente una specifica versione di Node.js per ogni singolo progetto, senza bisogno di ricorrere a gestori esterni come NVM, fnm o container Docker. Questo semplifica il flusso di lavoro ed evita sia conflitti di versione che la contaminazione dell’ambiente globale.

In questa guida vedremo come sfruttare il file .servbay.config di ServBay per controllare la versione di Node.js a livello di progetto.

Perché scegliere la gestione delle versioni di Node.js tramite .servbay.config di ServBay?

I metodi tradizionali per gestire le versioni di Node.js, come NVM o l’installazione manuale, possono comportare alcune complessità:

• Contaminazione globale e conflitti: Installare versioni globalmente o usare gestori versione per cambiare versione a livello globale può portare a conflitti di dipendenze tra i vari progetti.
• Installazione e compilazione lente: Installare nuove versioni o passare tra differenti architetture (come x86_64 e arm64) spesso richiede la ricompilazione dei moduli; un processo dispendioso di tempo e potenzialmente complesso.
• Overhead dei container Docker: Se ti serve solo una particolare versione di Node.js, usare un intero container Docker risulta troppo pesante e superfluo.

ServBay offre una soluzione più elegante grazie alla preinstallazione di numerose versioni di Node.js (al momento sono supportate tutte le versioni principali dalla v12 alla v23, gestibili nell’area “Pacchetti” dell’app ServBay) e all’uso di .servbay.config:

• Commutazione istantanea: Le versioni sono già preinstallate, quindi il passaggio da una versione all’altra è praticamente immediato.
• Isolamento tra progetti: La configurazione è valida solo nella directory del progetto, garantendo un reale isolamento delle versioni per ciascun progetto.
• Nessuna contaminazione globale: L’ambiente di sistema non viene modificato, mantenendo il ​​macOS pulito e stabile.
• Integrazione nativa con ServBay: Perfettamente integrato nell’ambiente di ServBay e utilizzabile insieme a tutti gli altri pacchetti gestiti (PHP, database, web server e altro).

Prerequisiti

Prima di iniziare, assicurati che:

1. ServBay sia installato e in funzione correttamente su macOS.
2. Tramite l’interfaccia dell’app ServBay, nella sezione “Pacchetti”, sia attiva la versione di Node.js richiesta dal tuo progetto.
3. Disponi della directory del progetto in cui vuoi configurare una versione specifica di Node.js.

Principio di funzionamento

Quando lavori nel terminale integrato di ServBay, l’app monitora la directory attuale. Ogni volta che esegui un comando cd e accedi a una cartella, ServBay cerca (dalla directory attuale verso l’alto) il file chiamato .servbay.config. Appena trova questo file (da preferire quello più vicino alla directory corrente), ServBay ne legge le opzioni e adatta dinamicamente le variabili d’ambiente della sessione del terminale—ad esempio, modificando la variabile PATH per puntare alla versione di Node.js specificata nel file.

Questo permette a ogni sessione di terminale di usare automaticamente la versione di Node.js appropriata, in base alla directory attiva, senza bisogno di cambiare versione manualmente.

Passaggi per la configurazione

Configurare una versione di Node.js indipendente per ciascun progetto è davvero semplice. Ecco i due passaggi fondamentali:

Passaggio 1: Crea e modifica il file .servbay.config

Nella directory principale del tuo progetto (di solito dove si trova anche il file package.json), crea il file .servbay.config.

Aprilo con il tuo editor di testo preferito e aggiungi:

# Specifica la versione principale di Node.js da usare nel progetto
# ServBay selezionerà automaticamente l’ultima versione già installata di quel ramo principale
NODE_VERSION=20

# Opzionale: imposta un mirror npm o pnpm per velocizzare l’installazione delle dipendenze
# Per sviluppatori in Cina, si consiglia un mirror locale
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# Opzionale: specifica la directory cache di npm o pnpm
# Consigliato salvare la cache nella cartella temporanea di ServBay per evitare occupazione o contaminazione di spazio nel sistema
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

Spiegazione delle opzioni:

• NODE_VERSION: Obbligatorio. Definisce la versione principale di Node.js richiesta dal progetto. Ad esempio, impostando 20, ServBay userà l’ultima versione disponibile della famiglia Node.js 20.x. Ricorda di controllare che la versione sia già installata e attiva su ServBay.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: Opzionale. Imposta l’URL del registry per Yarn o npm, utilissimo in caso di connessioni lente o problemi con i mirror ufficiali.
• NPM_CONFIG_CACHE: Opzionale. Definisce la directory in cui npm/pnpm salveranno la cache. Posizionarla nella directory temporanea di ServBay (/Applications/ServBay/tmp/npm/cache) consente una gestione centralizzata ed evita che i file di cache si disperdano nel sistema.

Salva e chiudi il file .servbay.config.

Passaggio 2: Verifica la versione nel terminale di ServBay

1. Apri l’interfaccia principale di ServBay.

2. Fai clic su “Terminale” per avviare il terminale integrato di ServBay.

3. Usa cd per accedere alla directory del tuo progetto.

   cd /Applications/ServBay/www/your-project-name

   (sostituisci /Applications/ServBay/www/your-project-name con il path corretto del tuo progetto)

4. Esegui il comando node -v per verificare la versione attualmente attiva di Node.js.

   node -v

   Il risultato dovrebbe mostrare il numero di versione specificato in .servbay.config (ad esempio v20.x.x).

5. Puoi anche controllare la versione dei gestori pacchetti con npm -v (o pnpm -v, yarn -v) per assicurarti che siano correttamente collegati alla versione di Node.js attiva.

A questo punto, ogni comando Node.js (insieme a npm/pnpm/yarn) eseguito nella directory del progetto userà la versione e i registry specificati nel file .servbay.config.

Esempio pratico

Ecco un esempio che mostra come .servbay.config permette la commutazione automatica delle versioni Node.js tra progetti differenti.

Supponiamo di avere due progetti: project-a richiede Node.js v18, project-b ha bisogno di Node.js v20.

1. Crea le directory dei progetti e i file di configurazione:

   # Crea le cartelle di esempio nella directory www di ServBay
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # Crea il file .servbay.config per project-a, impostando Node.js v18
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # Crea il file .servbay.config per project-b, impostando Node.js v20
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. Verifica il cambio versione via terminale ServBay:

   Apri il terminale in ServBay ed esegui:

   # Vai in project-a
   cd /Applications/ServBay/www/project-a
   # Controlla la versione di Node.js
   node -v
   # Risultato atteso: v18.x.x
   
   # Accedi a project-b
   cd ../project-b
   # Controlla la versione di Node.js
   node -v
   # Risultato atteso: v20.x.x
   
   # Torna in project-a
   cd ../project-a
   # Controlla la versione di Node.js
   node -v
   # Risultato atteso: v18.x.x

Da questo esempio si nota come ServBay, rilevando la posizione corrente, carichi e applichi automaticamente la NODE_VERSION definita nel .servbay.config, consentendo il passaggio trasparente tra versioni diverse di Node.js.

L’immagine sotto mostra un esempio di cambio versione automatico in base al progetto selezionato (l’aspetto reale dell’interfaccia potrebbe variare):

Note aggiuntive

• Il file .servbay.config deve trovarsi nella directory del progetto o in una cartella superiore. ServBay seleziona il primo file trovato risalendo la gerarchia (quello più vicino alla cartella corrente).
• Lavora sempre nel terminale integrato di ServBay o in un terminale esterno che sia stato correttamente configurato con le variabili d’ambiente di ServBay.
• La versione definita tramite NODE_VERSION deve essere effettivamente installata e abilitata nell’applicazione ServBay. Se la versione non è disponibile, ServBay passerà a quella predefinita o potrebbe non trovare affatto Node.js.
• Le impostazioni definite nel file .servbay.config influenzano SOLO la sessione terminale corrente e i suoi processi figli—non l’intero sistema o applicazioni esterne a ServBay.

Domande frequenti (FAQ)

D: Cosa succede se il mio progetto non contiene un file .servbay.config?

R: Se né la directory attuale né le sue cartelle superiori contengono un .servbay.config, ServBay userà la configurazione globale o la versione di Node.js predefinita (di solito quella contrassegnata come “predefinita” nell’app ServBay).

D: Come posso sapere quali versioni di Node.js supporta ServBay?

R: Apri l’applicazione ServBay e vai nella sezione laterale “Pacchetti”: qui troverai l’elenco di tutti i pacchetti disponibili e installati, incluse tutte le versioni di Node.js attivabili o disattivabili con una semplice spunta.

D: Le opzioni di .servbay.config influenzano tutto il mio sistema operativo?

R: No. Il file .servbay.config modifica temporaneamente solo l’ambiente della sessione terminale di ServBay (e dei relativi processi). Nessuna variabile d’ambiente di sistema viene alterata e nulla cambia per le applicazioni eseguite al di fuori di ServBay. Questo è il principio essenziale su cui si basa l’isolamento dei progetti.

D: Oltre a NODE_VERSION, posso configurare altri parametri di ServBay usando .servbay.config?

R: Sì. Il file .servbay.config è uno strumento generico pensato per impostare variabili d’ambiente specifiche per ogni progetto. Al di là di Node.js, puoi configurare ulteriori parametri che saranno attivi per ogni comando eseguito dal terminale in quella directory. Le possibilità cresceranno con le future versioni di ServBay, ma la funzione centrale resta la gestione delle variabili d’ambiente a livello di progetto.

Conclusione

Utilizzando il file .servbay.config di ServBay puoi assegnare e gestire facilmente una versione di Node.js distinta per ciascun progetto locale. Questo metodo, molto più leggero e pratico rispetto ai tradizionali gestori di versioni o ai container, si integra perfettamente con l’ambiente ServBay e ti aiuta a impostare un flusso di lavoro più stabile e collaborativo. Prova oggi stesso .servbay.config nel tuo prossimo progetto e scopri la comodità di un ambiente di sviluppo sempre pulito, modulare e privo di conflitti!