Installare Vue.js su Debian 12 passo dopo passo

Installare Vue.js su Debian 12: scelta corretta dello stack

Su Debian 12, il punto non è “installare Vue.js” come pacchetto di sistema, ma predisporre un ambiente JavaScript affidabile per sviluppare e buildare un progetto Vue. In pratica servono Node.js, npm e un tool di scaffolding come Vite. Vue gira nel browser, mentre su Debian installi gli strumenti per creare, eseguire in locale e compilare l’applicazione.

Se l’obiettivo è sviluppo, la strada più pulita è usare la versione LTS di Node.js, evitare pacchetti vecchi dei repository standard quando non allineati alla versione richiesta dal progetto, e verificare subito che la toolchain funzioni prima di passare alla creazione dell’app.

Prerequisiti e stato atteso

Stato atteso: Debian 12 aggiornato, accesso con un utente non root con privilegi sudo, rete funzionante, e una versione recente di Node.js compatibile con Vue 3 e Vite. Stato osservato tipico quando qualcosa non va: Node assente, npm troppo vecchio, permessi errati nella home, o build che fallisce per dipendenze mancanti.

Prima di toccare il sistema, verifica il contesto:

cat /etc/debian_version
whoami
sudo -v

Atteso: Debian 12.x, utente normale, sudo disponibile. Se il sistema è un server condiviso o una VM di produzione, considera il blast radius: installerai tool di sviluppo e pacchetti, senza toccare servizi esistenti, ma ogni update di Node può cambiare il comportamento delle build. Se serve rollback, devi sapere quale metodo di installazione stai usando.

Metodo consigliato: Node.js LTS su Debian 12

Per un ambiente pulito, la scelta più pratica è installare Node.js LTS dal repository NodeSource oppure usare un gestore versione come nvm. Se devi lavorare in team o su più progetti con requisiti diversi, nvm riduce i conflitti. Se invece vuoi una installazione di sistema semplice e stabile, NodeSource è più lineare.

Qui parto dal metodo di sistema con NodeSource, perché su Debian 12 è immediato e facile da verificare. Se ti serve un ambiente per singolo utente, dopo trovi anche l’alternativa con nvm.

Installazione di Node.js LTS con NodeSource

Aggiorna l’indice pacchetti e installa i prerequisiti:

sudo apt update
sudo apt install -y curl ca-certificates gnupg

Atteso: nessun errore sui repository e pacchetti installati correttamente. Poi aggiungi il repository NodeSource per la LTS corrente:

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

Questo comando configura il repository appropriato. Verifica che il repo sia stato aggiunto:

apt-cache policy nodejs

Atteso: in output compare la sorgente NodeSource con una priorità coerente. A questo punto installa Node.js:

sudo apt install -y nodejs

Verifica subito le versioni:

node -v
npm -v

Atteso: una versione Node recente e npm disponibile. Se `node -v` fallisce o mostra una versione inattesa, non andare avanti: prima correggi il repository o il path binario.

Alternativa: nvm per installazione per utente

Se vuoi isolare le versioni per progetto, nvm è più flessibile. È particolarmente utile su workstation o ambienti di sviluppo in cui non vuoi dipendere dal Node installato di sistema.

Installa nvm nel profilo utente:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Ricarica la shell oppure apri una nuova sessione:

source ~/.bashrc

Verifica che nvm sia presente:

command -v nvm

Atteso: il comando restituisce `nvm`. Poi installa la LTS e impostala come predefinita:

nvm install --lts
nvm alias default 'lts/*'
node -v
npm -v

Se usi nvm, il rollback è semplice: cambi versione con `nvm use` o rimuovi la versione installata. Il blast radius resta confinato all’utente corrente.

Creare un progetto Vue 3 con Vite

Oggi il percorso raccomandato è Vite, non il vecchio scaffolding basato su Vue CLI, salvo vincoli legacy. Vite è veloce, semplice e allineato all’ecosistema Vue 3.

Crea una directory di lavoro e genera il progetto:

mkdir -p ~/projects
cd ~/projects
npm create vue@latest

Durante la procedura interattiva ti verranno chiesti nome progetto e opzioni come TypeScript, Router, Pinia, test e lint. Se non hai requisiti specifici, puoi partire con la configurazione minima e aggiungere il resto dopo.

Entra nella directory del progetto e installa le dipendenze:

cd nome-progetto
npm install

Atteso: il file `package.json` viene popolato e `node_modules` viene creato senza errori. Se `npm install` fallisce, controlla prima la connessione, poi la versione di Node, poi eventuali proxy o certificati aziendali.

Avvio in sviluppo e verifica funzionale

Il test più importante è avviare il server di sviluppo e aprire l’app nel browser. Questo conferma che la toolchain è coerente, che il bundler parte e che Vue risponde correttamente.

npm run dev

Atteso: il terminale mostra un URL locale, in genere `http://localhost:5173/`, e il server resta in ascolto. Apri l’indirizzo nel browser. Se vuoi esporlo in rete locale, Vite può ascoltare su tutte le interfacce:

npm run dev -- --host 0.0.0.0

Questo aumenta la superficie d’esposizione: usalo solo in rete fidata e, se necessario, limita il firewall. Per una workstation va bene; per un host condiviso valuta attentamente il rischio.

Verifica minima da terminale:

curl -I http://127.0.0.1:5173/

Atteso: risposta HTTP 200 o 304 a seconda dello stato della pagina. Se ottieni connection refused, il dev server non è partito o sta ascoltando su un’altra interfaccia. Se ottieni 5xx, guarda l’output del terminale del processo Vite.

Struttura del progetto Vue

Un progetto Vue creato con `npm create vue@latest` include una struttura già pronta per partire. In genere trovi:

• src/ con componenti, router e logica applicativa
• public/ per asset statici serviti così come sono
• vite.config.* per la configurazione del bundler
• package.json con script e dipendenze

Il punto operativo è questo: modifica soprattutto `src/`, non i file generati dal tool se non sai esattamente perché. Se devi cambiare la base URL, il proxy o la build, intervieni in `vite.config.js` o `vite.config.ts` con un diff tracciabile.

Esempio di componente semplice in `src/App.vue`:

<template>
  <h1>Vue su Debian 12</h1>
  <p>Installazione completata correttamente.</p>
</template>

Se la pagina non si aggiorna, controlla la console del browser e il terminale di Vite. Le cause tipiche sono errori di sintassi, import sbagliati o dipendenze mancanti.

Build di produzione

Quando il progetto funziona in sviluppo, il passo successivo è la build di produzione. È il controllo che conta davvero prima di pubblicare su un web server o dentro un container.

npm run build

Atteso: generazione della directory `dist/` senza errori. Se la build fallisce, non ignorare il problema: sviluppo e produzione possono divergere per plugin, variabili ambiente, compatibilità sintattica o dipendenze non risolte.

Per verificare l’output in locale:

npm run preview

Atteso: il sito compilato risponde correttamente su una porta locale. Questo è utile per validare il risultato prima del deploy. Se il progetto deve stare dietro Nginx o Apache, il contenuto di `dist/` è quello da servire come static assets.

Aggiornare Vue, Node e dipendenze senza rompere il progetto

Il rischio più comune non è “installare Vue”, ma ritrovarsi con dipendenze incoerenti dopo mesi. La regola pratica è aggiornare in modo controllato: prima leggi le release notes, poi prova su branch o clone, poi aggiorna in produzione solo se la build resta pulita.

Comandi utili:

npm outdated
npm update
npm run build

Atteso: `npm outdated` mostra cosa è fuori versione, `npm update` aggiorna entro i vincoli semver, e la build continua a passare. Se serve un salto di versione importante, usa il changelog del framework e del bundler, non un aggiornamento cieco.

Per Node.js, se usi nvm il rollback è immediato:

nvm install 20
nvm use 20

Se usi NodeSource a livello di sistema, il rollback richiede reinstallare la versione desiderata o rimuovere il repository aggiunto e tornare ai pacchetti Debian, con attenzione alla compatibilità del progetto. In quel caso conserva nota della versione precedente prima di cambiare.

Troubleshooting essenziale su Debian 12

Se qualcosa non va, isola prima il layer: sistema, Node, npm, progetto, browser. Non saltare direttamente a “Vue è rotto”. Quasi sempre il problema sta nella toolchain o nell’ambiente.

1. Node assente o vecchio: verifica con node -v e npm -v. Se fallisce, correggi l’installazione.
2. Permessi errati: se `npm install` crea errori su home o cache, controlla con ls -ld ~ ~/.npm. Non usare sudo per installare dipendenze del progetto utente.
3. Porta occupata: se Vite non parte, controlla con ss -ltnp | grep 5173.
4. Dipendenze corrotte: elimina `node_modules` e `package-lock.json` solo se necessario e ricrea l’installazione con attenzione.

Per una pulizia controllata della cartella dipendenze, il rischio è basso ma il blast radius riguarda il progetto corrente:

rm -rf node_modules
npm install

Usalo solo nel progetto giusto. Se sei in dubbio, fai prima un backup del `package-lock.json` o lavora su branch separato.

Deploy statico dietro Nginx o Apache

Se il progetto Vue è pronto per la pubblicazione, il contenuto della build va servito come file statici. In genere configuri il web server per puntare a `dist/` e, se usi routing lato client, devi impostare il fallback verso `index.html`.

Esempio concettuale: Nginx o Apache devono restituire `index.html` per le route gestite dal router Vue, altrimenti al refresh ottieni 404. Questo non è un problema di Vue, ma di server web.

Verifica minima dopo il deploy:

• la home risponde con HTTP 200
• una route interna dell’app funziona anche con refresh
• gli asset statici vengono caricati senza 404

Se il sito mostra pagina bianca, apri la console browser: spesso trovi errore JavaScript, base path errato, o asset referenziati con path sbagliato. Se il sito restituisce 404 sulle route interne, il problema è quasi sempre la configurazione del web server.

Manutenzione e buone pratiche operative

Su Debian 12, l’approccio più robusto è mantenere separati sistema operativo e runtime applicativo. Aggiorna Debian per sicurezza, ma non usare il package manager di sistema per imporre versioni casuali di Node se il progetto richiede un ciclo di release più veloce. In quel caso nvm o un container sono più adatti.

Conserva sempre questi punti di controllo:

• versione di Node documentata nel progetto
• lockfile presente e versionato
• build verificata prima del deploy
• configurazione del web server allineata al router

Per un team, aggiungi nel repository una nota tecnica con la versione minima supportata di Node e il comando di bootstrap. Riduce errori in onboarding e differenze tra workstation.

Sequenza minima consigliata, in sintesi operativa

Se vuoi andare dritto al punto, la sequenza pratica è questa:

1. aggiorna Debian e installa i prerequisiti
2. installa Node.js LTS con NodeSource oppure nvm
3. verifica `node -v` e `npm -v`
4. genera il progetto con `npm create vue@latest`
5. installa dipendenze con `npm install`
6. avvia con `npm run dev`
7. valida la build con `npm run build`
8. pubblica `dist/` dietro il web server corretto

Assunzione: stai creando un progetto Vue 3 con Vite su Debian 12 per sviluppo o preproduzione; se hai vincoli enterprise su proxy, certificati o versioni Node, verifica prima quei requisiti e adatta la procedura.

Se vuoi, posso anche prepararti la versione specifica per Apache, Nginx o deploy in produzione con systemd e reverse proxy.