1 31/10/2026 9 min

Su Ubuntu 20.04 LTS, il modo più pulito per lavorare con React non è “installare React” come pacchetto di sistema, ma preparare un ambiente Node.js coerente e poi generare l’app con lo scaffolding giusto. In pratica: scegli una versione di Node supportata, crei il progetto, avvii il server di sviluppo e verifichi che il ciclo di build funzioni davvero. È il percorso che riduce gli errori più comuni: dipendenze rotte, versioni troppo vecchie, permessi sbagliati e installazioni fatte con privilegi inutili.

Prerequisiti su Ubuntu 20.04 LTS

Prima di partire conviene controllare il sistema e aggiornare i pacchetti base. Su una macchina fresca, questo evita di incappare in librerie obsolete o in problemi con SSL e compilazione di moduli nativi. Se lavori su un server o su una VM condivisa, verifica anche di avere un utente non root con privilegi sudo: è la scelta più sensata per creare e gestire il progetto.

Per una base pulita, aggiorna l’indice dei pacchetti e installa gli strumenti minimi necessari:

sudo apt update
sudo apt upgrade -y
sudo apt install -y curl git build-essential

Perché questi pacchetti: curl serve per scaricare installer e verificare endpoint, git è utile sia per il versionamento sia perché molti template lo usano, build-essential copre compilatori e tool di base che diventano utili quando una dipendenza npm include moduli nativi.

Scelta del runtime: Node.js e npm

React non gira da solo: ha bisogno di Node.js per installare dipendenze, lanciare il dev server e produrre la build finale. Su Ubuntu 20.04 il punto critico è non affidarsi a versioni casuali dei repository di sistema, perché spesso sono vecchie rispetto alle esigenze di tool moderni come Vite, React Scripts o altri starter aggiornati.

La via più ordinata è usare un gestore di versioni come nvm. Così puoi tenere più versioni di Node sulla stessa macchina, cambiare versione per progetto e ridurre il rischio di rovinare l’ambiente globale. Se preferisci una gestione centralizzata a livello di sistema, puoi usare i repository ufficiali di NodeSource, ma per sviluppo locale nvm resta la scelta più flessibile.

Installazione di nvm

Installa nvm nel profilo utente, non come root. Questo mantiene separati i binari di Node dal sistema operativo e semplifica molto eventuali rollback.

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

Dopo l’installazione, verifica che il comando sia disponibile:

command -v nvm

L’output atteso è nvm. Se non compare, il problema è quasi sempre nel caricamento del profilo shell: controlla ~/.bashrc o il file di configurazione della shell che usi davvero.

Installazione della versione di Node

Per un progetto React recente, una versione LTS moderna di Node è la scelta più sicura. La versione esatta può cambiare nel tempo, quindi l’approccio corretto è installare l’LTS corrente disponibile nel tuo momento operativo, non una release arbitraria presa a caso. Se il progetto ha vincoli specifici, segui quelli del repository o del file package.json.

nvm install --lts
nvm use --lts
node -v
npm -v

Verifica minima: node -v e npm -v devono restituire versioni coerenti. Se npm non è presente, l’installazione di Node è incompleta o il profilo non è stato caricato correttamente.

Creare una nuova app React

Oggi il modo più lineare per creare un’app React è usare un tool moderno come Vite. È più rapido di molti starter storici, genera un progetto pulito e rende più semplice la gestione del dev server. Se stai seguendo un repository esistente, puoi usare il tool richiesto dal progetto; se invece parti da zero, Vite è una base pratica e attuale.

Per creare un progetto React con Vite, esegui:

npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install

Se vuoi la variante con TypeScript, usa il template dedicato:

npm create vite@latest my-react-app -- --template react-ts
cd my-react-app
npm install

Perché questo passaggio conta: il comando crea la struttura iniziale, aggiunge i file corretti e prepara le dipendenze dichiarate nel progetto. Evita di fare installazioni manuali sparse con npm install react react-dom dentro una cartella vuota: funziona solo a metà e ti lascia senza configurazione di build, dev server e asset pipeline.

Struttura del progetto generato

Dopo la creazione, la directory del progetto include una struttura simile a questa:

my-react-app/
├── index.html
├── package.json
├── node_modules/
├── public/
└── src/ ├── App.jsx ├── main.jsx └── assets/

La parte importante è src/: qui vive il codice dell’app. main.jsx è il punto di ingresso, mentre App.jsx contiene il componente principale. package.json definisce script, dipendenze e metadati del progetto.

Avvio del server di sviluppo

A questo punto puoi avviare l’ambiente di sviluppo locale:

npm run dev

In condizioni normali il terminale mostra un indirizzo locale, spesso http://localhost:5173 o simile. Apri l’URL nel browser e verifica che la pagina iniziale del template sia caricata. Se il browser non si apre, il problema non è React: può essere un firewall locale, un binding sull’interfaccia sbagliata o semplicemente il fatto che stai lavorando su una macchina remota senza port forwarding.

Se vuoi esporre il dev server sulla rete locale, controlla la documentazione del tool in uso. Con Vite, ad esempio, il binding può essere modificato in modo esplicito nel comando o nella configurazione. Non farlo alla cieca su una macchina esposta: un dev server non è un servizio di produzione.

Primo componente React

Una volta verificato che il progetto parte, conviene sostituire il contenuto di esempio con un componente semplice ma reale. Questo ti permette di confermare che JSX, rendering e hot reload funzionano come previsto.

Apri src/App.jsx e usa un contenuto minimale:

function App() { return ( <main> <h1>La mia prima app React</h1> <p>React è installato e il progetto risponde correttamente.</p> </main> )
} export default App

Salvando il file, il browser dovrebbe aggiornarsi in automatico. Se non succede, verifica che il terminale non mostri errori e che il dev server sia ancora attivo. In caso di errore di sintassi, il messaggio di build è di solito abbastanza esplicito: spesso basta un tag JSX non chiuso o un export mancante.

Entry point e rendering nel DOM

Il rendering della tua app passa da src/main.jsx. In un progetto Vite standard, il file monta il componente principale nel nodo DOM con id root. Se questo file è rotto, la pagina resta bianca anche se il componente è corretto.

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css' ReactDOM.createRoot(document.getElementById('root')).render( <React.StrictMode> <App /> </React.StrictMode>
)

Controllo utile: se apri il file index.html, deve esserci un elemento <div id="root"></div>. Senza quel nodo, React non ha dove montarsi e la pagina non mostrerà nulla.

Dipendenze aggiuntive e gestione pacchetti

Una volta creata l’app, aggiungerai quasi sempre librerie esterne: router, client HTTP, form library, state management o componenti UI. Il punto importante è installare solo ciò che serve davvero e tenere sotto controllo il file package.json. Ogni pacchetto in più aumenta superficie di manutenzione, tempi di build e possibilità di conflitti.

Per esempio, se ti serve il routing lato client:

npm install react-router-dom

Dopo l’installazione, verifica che il pacchetto sia comparso tra le dipendenze di package.json e che il lockfile sia stato aggiornato. Se lavori in team, il lockfile va versionato: è il modo più semplice per mantenere build ripetibili tra ambienti diversi.

Script utili in package.json

Il file package.json contiene gli script che userai ogni giorno. In un progetto standard, trovi almeno start/dev, build e preview. Se devi adattare il progetto a un flusso di lavoro più serio, puoi aggiungere lint, test e formatter, ma la base resta questa.

{ "scripts": { "dev": "vite", "build": "vite build", "preview": "vite preview" }
}

Verifica pratica: npm run build deve completarsi senza errori. Se la build fallisce ma il dev server funziona, di solito il problema è legato a import non risolti, variabili non definite o asset referenziati in modo scorretto.

Errori comuni su Ubuntu 20.04 LTS

Su Ubuntu 20.04 i problemi più frequenti non sono legati a React in sé, ma all’ambiente. Il primo è la versione di Node troppo vecchia: sintassi moderne, dipendenze recenti o strumenti di build possono smettere di funzionare senza avviso chiaro. Il secondo è l’uso di sudo npm install, che inquina permessi e ownership della directory del progetto. Il terzo è l’aver installato pacchetti globali senza un motivo preciso, creando differenze tra macchine diverse.

Se incontri errori di permessi, controlla la proprietà dei file nella cartella del progetto con attenzione. In generale, un progetto frontend dovrebbe appartenere al tuo utente, non a root. Se noti EACCES o permission denied, la correzione giusta è ripristinare ownership e smettere di usare installazioni globali improprie, non forzare ancora di più il sistema.

Se il browser mostra pagina bianca, la sequenza di controllo è semplice: terminale senza errori, file main.jsx corretto, nodo root presente nell’HTML, componente exportato bene e CSS non bloccante. Nella maggior parte dei casi il problema è uno di questi cinque punti.

Preparazione per produzione

Il dev server non è un ambiente di produzione. Quando sei pronto a pubblicare, esegui la build statica e servi i file generati con un web server adatto, come Nginx o un hosting statico. Il comando di riferimento resta npm run build, che produce una cartella pronta da distribuire secondo il tool usato.

Prima di distribuire, conviene controllare almeno tre aspetti: dimensione del bundle, assenza di errori in console e comportamento delle route lato client. Se usi React Router, devi configurare correttamente il fallback delle richieste, altrimenti il refresh su una rotta interna può restituire un errore 404 dal web server.

In un contesto reale, la qualità del setup non si misura dal fatto che “parte sul mio PC”, ma dal fatto che la build è ripetibile, le versioni sono dichiarate e il progetto è leggibile da chiunque entri dopo di te. Su questo React è abbastanza indulgente: se imposti bene l’ambiente iniziale, il resto del lavoro diventa molto più lineare.

Checklist operativa finale

Prima di considerare chiusa l’installazione, passa in rassegna questi punti:

  • Ubuntu 20.04 aggiornato con pacchetti base installati.
  • Node.js attivo e verificato con node -v e npm -v.
  • Progetto creato con un template moderno, non con installazioni manuali sparse.
  • Server di sviluppo avviato con npm run dev.
  • Componente React modificato e visualizzato correttamente nel browser.
  • Build finale completata con npm run build.

Se uno di questi punti fallisce, non saltare subito a soluzioni drastiche. Fermati sul layer giusto: sistema, runtime, progetto, rendering o build. È il modo più rapido per capire dove si è rotto il flusso e correggerlo senza introdurre altro rumore.

Assunzione operativa: ambiente Ubuntu 20.04 LTS standard, progetto nuovo, sviluppo locale su macchina singola con shell Bash e nessun vincolo particolare di CI/CD o reverse proxy.