Guide all'installazione

Configurare React con Vite

Vi mostriamo come creare un progetto React e TypeScript con Vite, avviare il server di sviluppo, fare la build, distribuirlo e risolvere gli errori comuni.

Aurora YazılımRedazione 6 min di lettura
Setting Up React with Vite
Come si configura React con Vite?

Per configurare React con Vite, installate prima la versione LTS attuale di Node.js. Poi eseguite npm create vite@latest nel terminale, inserite il nome del progetto e scegliete il template React e TypeScript. Entrate nella cartella del progetto, installate le dipendenze con npm install e avviate il server di sviluppo con npm run dev; il sito si apre per impostazione predefinita su localhost:5173.

Che cos'è Vite e perché usarlo?

Vite è un build tool e server di sviluppo pensato per i progetti web moderni. Durante lo sviluppo serve il codice sfruttando il supporto nativo dei moduli ES del browser ed elabora solo il file richiesto. Per questo il server si avvia in pochi secondi anche quando il progetto cresce, e una modifica salvata compare sullo schermo senza ricaricare la pagina.

Per la produzione, Vite raggruppa il codice in file minimizzati e suddivisi, con nomi adatti alla cache. Offre template pronti per librerie come React, Vue e Svelte ed è diventato uno dei punti di partenza più comuni nell'ecosistema React.

Vite come alternativa a Create React App

Per molti anni i progetti React sono stati avviati con Create React App. Il team di React non raccomanda più questo strumento per i nuovi progetti; la documentazione ufficiale suggerisce di partire da un framework (come Next.js) o da un build tool come Vite. Se cercate un'alternativa a Create React App, Vite è il percorso di migrazione più rapido e con meno configurazione.

Se vi servono rendering delle pagine lato server, routing basato su file e output di pagine già pronto per la SEO, consultate la nostra guida alla configurazione di Next.js. Per un pannello di amministrazione, uno strumento interno o un'applicazione a pagina singola (SPA), Vite è di solito la scelta più semplice.

Prerequisiti

L'unico vero prerequisito di Vite è Node.js. Le nuove versioni di Vite abbandonano il supporto per le versioni più vecchie di Node, quindi installare l'ultima versione LTS da nodejs.org è la strada più sicura. npm è incluso in Node.js.

  • La versione LTS attuale di Node.js e l'npm incluso.
  • Un editor di codice; per l'installazione e le estensioni consigliate, consultate il nostro articolo sulla configurazione di VS Code.
  • Terminale: PowerShell o Windows Terminal su Windows, Terminal su macOS e la shell che preferite su Linux.
  • Facoltativo: Git per il controllo di versione.

Node.js per sistema operativo

Potete scaricare e installare Node.js da nodejs.org. Se userete versioni diverse di Node in più progetti, scegliere un gestore di versioni vi semplificherà la vita in seguito.

Windows

Scaricate l'installer LTS da nodejs.org e installatelo con le opzioni predefinite, oppure usate winget in PowerShell. Dopo l'installazione, chiudete e riaprite il terminale per aggiornare il PATH.

powershell
winget install OpenJS.NodeJS.LTS node -v npm -v

macOS

Potete usare l'installer ufficiale oppure installare con un solo comando se Homebrew è disponibile.

bash
brew install node node -v npm -v

Linux

La versione di Node presente nei repository delle distribuzioni è spesso obsoleta. Installare a livello utente con nvm vi offre una versione aggiornata ed elimina la necessità di sudo; dopo aver installato nvm con lo script presente sulla sua pagina GitHub, eseguite i comandi seguenti.

bash
nvm install --lts nvm use --lts node -v

Passaggi per creare un progetto React

Quando Node.js è pronto, la creazione di un progetto React è uguale su ogni sistema operativo. Il comando vi guida in modo interattivo: chiede il nome del progetto, il framework (React) e la variante (TypeScript). Se volete indicare direttamente il template nel comando, usate il formato seguente; in npm i parametri aggiuntivi vanno dopo il doppio trattino.

  • Se volete lavorare con JavaScript, il nome del template è react; per TypeScript è react-ts.
  • Aprite nel browser l'indirizzo mostrato nella riga Local del terminale (per impostazione predefinita localhost:5173).
  • Cambiate un testo in src/App.tsx e salvate; se la pagina si aggiorna senza ricaricarsi, l'HMR (hot module replacement) funziona.
bashCreare ed eseguire il progetto
npm create vite@latest benim-uygulamam -- --template react-ts cd benim-uygulamam npm install npm run dev
bashSe usate pnpm o yarn
pnpm create vite benim-uygulamam --template react-ts yarn create vite benim-uygulamam --template react-ts

Conoscere la struttura del progetto

La prima cosa che si nota in un progetto Vite è che index.html si trova nella directory radice. Vite usa questo file come punto di ingresso e il tag script al suo interno richiama src/main.tsx.

File / cartellaFinalità
index.htmlLa pagina di ingresso dell'app; qui si trovano il titolo e i meta tag
src/main.tsxIl file iniziale che monta React nella pagina
src/App.tsxIl componente principale; da qui costruite le vostre pagine
public/File copiati così come sono, senza elaborazione: favicon, robots.txt
vite.config.tsPlugin, alias, impostazioni del server e della build
package.jsonDipendenze e script di sviluppo, build e anteprima

Variabili d'ambiente

Vite espone al codice client solo le variabili che iniziano con il prefisso VITE_ e vi si accede tramite import.meta.env. Queste variabili sono incorporate nel bundle inviato al browser; non inseritevi mai elementi come chiavi segrete delle API, tenetele lato server.

bash.env.local
VITE_API_URL=https://api.ornek.com

Build e distribuzione

Il server di sviluppo serve solo per il lavoro in locale. La versione da distribuire si produce con npm run build; l'output viene scritto nella cartella dist. npm run preview permette di testare quell'output in locale in modo vicino alla vera produzione.

La cartella dist è composta da semplici file HTML, CSS e JavaScript; può essere caricata su qualsiasi hosting statico o su un server web come Nginx. Per la velocità è importante che i file siano compressi e serviti con intestazioni di cache di lunga durata; spieghiamo queste impostazioni in dettaglio nella nostra pagina sulla gestione di velocità e prestazioni.

  • Se l'app sarà pubblicata in una sottocartella (example.com/panel/), impostate l'opzione base in vite.config.ts su quel percorso.
  • Se usate React Router, aggiungete sul server una regola che reindirizzi tutti gli indirizzi sconosciuti a index.html.
  • Per le pagine di contenuto che devono comparire nei motori di ricerca, il solo rendering lato client può non bastare; qui diventa importante un approccio di web design orientato alla SEO.
bash
npm run build npm run preview

Errori comuni e soluzioni

La maggior parte degli errori in una configurazione Vite deriva dalla versione di Node, dalla porta o dalle impostazioni di distribuzione. La tabella seguente riassume i casi più comuni; per altri comandi, consultate la nostra guida ai comandi npm.

SintomoPerchéSoluzione
Avviso “Vite requires Node.js version...”Versione di Node vecchiaPassate alla versione LTS attuale
La porta 5173 è in usoLa porta è occupata da un altro processoVite prova la porta successiva; impostate server.port per una porta fissa
Comando node non trovatoPATH non aggiornatoChiudete e riaprite il terminale, riavviate il computer se necessario
Pagina bianca in produzionePercorso base erratoCorreggete l'impostazione base in modo che corrisponda alla cartella di distribuzione
404 al ricaricamento della paginaNessun routing SPA sul serverReindirizzate tutti i percorsi a index.html

Prossimi passi

Quando avete un progetto funzionante, potete aggiungere strumenti come React Router per il routing, TanStack Query per il recupero dei dati e Tailwind CSS o CSS Modules per lo stile. Per la qualità del codice, estendete le impostazioni di ESLint incluse nel template in base al vostro progetto.

Vite e React insieme sono una base solida per applicazioni aziendali come un pannello prenotazioni, una schermata di magazzino, il monitoraggio degli appuntamenti o la gestione di menu con codice QR. In prodotti di questo tipo, modello dei dati, autorizzazioni e backup contano quanto l'interfaccia; se preferite partire da una base già pronta, le soluzioni software di settore possono far risparmiare tempo.

Il design dell'interfaccia conta quanto la base tecnica: pianificare il flusso utente e il layout delle schermate prima di scrivere i componenti è alla base del processo di progettazione UI/UX. Pensare ai breakpoint mobile fin dall'inizio costa molto meno che correggerli dopo per un design ottimizzato per i dispositivi mobili.

Domande frequenti

01TypeScript è obbligatorio in un progetto Vite React?

No, il template react funziona con JavaScript puro. Ma nei progetti medio-grandi TypeScript individua gli errori mentre scrivete e facilita il lavoro di squadra. Migrare in seguito è possibile, ma partire fin dall'inizio con react-ts richiede meno lavoro.

02Posso migrare a Vite il mio progetto Create React App esistente?

Sì. I passaggi di base sono spostare index.html nella directory radice, installare Vite e il plugin React al posto di react-scripts e cambiare le variabili con prefisso REACT_APP_ in quelle con prefisso VITE_. Per i progetti grandi, provate prima in un branch separato ed eseguite i test.

03Un sito creato con Vite è abbastanza buono per la SEO?

Per dashboard e schermate di app va bene. Per le pagine di contenuto che devono posizionarsi nei motori di ricerca è più sano che il contenuto sia generato come HTML sul server; per questo si preferisce un framework come Next.js o una soluzione di pre-rendering.

04Devo usare pnpm al posto di npm?

pnpm usa lo spazio su disco in modo più efficiente e velocizza le installazioni; Vite funziona bene con entrambi i gestori di pacchetti. Far usare a tutto il team lo stesso strumento conta più di quale scegliete.

Configurare React con Vite richiede pochi minuti; il vero impegno sta nell'architettura dell'applicazione che costruite sopra. Se vi serve un pannello su misura, un software di prenotazione o di gestione per la vostra attività, scoprite le nostre soluzioni software di settore; per un sito veloce e originale, date un'occhiata al nostro servizio di web design.