Guide all'installazione

Installare Next.js e andare online

Una guida passo dopo passo per creare un progetto Next.js con create-next-app, capire la struttura delle cartelle dell'App Router e pubblicare il progetto su Vercel o sul vostro server.

Aurora YazılımRedazione 6 min di lettura
Installing Next.js and Going Live
Come si installa Next.js?

Per installare Next.js, installa la versione LTS corrente di Node.js, poi esegui npx create-next-app@latest nel terminale. La procedura guidata chiede di TypeScript, ESLint, Tailwind CSS e App Router. Entra nella cartella del progetto e avvia il server di sviluppo con npm run dev; il sito si apre su localhost:3000, mentre npm run build serve per la produzione.

Che cos'è Next.js e a chi serve

Next.js è un framework per applicazioni web basato su React. Mentre React si limita a renderizzare i componenti dell'interfaccia, Next.js offre già pronti routing, rendering delle pagine lato server, output di pagine statiche, ottimizzazione delle immagini ed endpoint API.

La differenza principale è che può generare le pagine come HTML sul server. I motori di ricerca e le anteprime dei social vedono direttamente il contenuto e il primo caricamento è più veloce. Per questo è più adatto delle applicazioni a pagina singola per siti aziendali ricchi di contenuti, pagine di catalogo e blog.

Se stai costruendo solo un pannello di amministrazione che richiede il login, può bastare una soluzione più semplice; per questo scenario, consulta la nostra guida sulla configurazione di React con Vite.

Prerequisiti

Next.js è esigente sulle versioni di Node.js supportate e abbandona il supporto alle versioni più vecchie nelle nuove major release. Per questo installare la versione LTS corrente da nodejs.org è la strada più semplice.

  • La versione LTS corrente di Node.js e npm (incluso con Node); si possono usare anche pnpm, yarn o bun.
  • Un editor di codice; per una configurazione con le estensioni consigliate, consulta l'articolo sull'installazione di VS Code.
  • Git e un repository remoto (GitHub, GitLab): i processi di deploy di solito partono dal repository.
  • Se farai il deploy sul vostro server, un server Linux con accesso SSH.

Installare e verificare Node.js

L'installazione di Node.js varia leggermente a seconda del sistema operativo; dopo l'installazione i comandi di Next.js sono gli stessi ovunque.

Windows

Scarica l'installer LTS da nodejs.org oppure usa winget; poi riapri il terminale.

powershell
winget install OpenJS.NodeJS.LTS node -v

macOS

Potete installarlo con il pacchetto ufficiale o con Homebrew.

bash
brew install node node -v

Linux

La versione presente nei repository delle distribuzioni può essere obsoleta; installare con nvm è più sicuro.

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

Creare un progetto con create-next-app

La procedura guidata create next app è lo strumento di avvio ufficiale e installa in un colpo solo tutti i pacchetti necessari. Quando esegui il comando, chiede il nome del progetto e alcune opzioni; se hai dubbi, accettare i valori predefiniti consigliati è un buon inizio.

DomandaConsiglio
TypeScriptSì; individua gli errori mentre scrivi
ESLintSì; per la qualità del codice
Tailwind CSSFacoltativo; scegli in base al vostro design system
Cartella src/Facoltativo; separa i file di configurazione dal codice
App RouterSì; la struttura consigliata per i nuovi progetti
Alias di importazioneIl valore predefinito @/* è sufficiente
bashInstallazione e server di sviluppo
npx create-next-app@latest benim-sitem cd benim-sitem npm run dev

Capire la struttura dell'App Router

L'App Router di Next.js genera il routing a partire dalla struttura delle cartelle. Ogni cartella dentro la cartella app è un segmento dell'URL; il file page.tsx in quella cartella definisce la pagina, mentre layout.tsx definisce lo scheletro condiviso di quella sezione.

Nell'App Router i componenti sono per impostazione predefinita server component: vengono eseguiti sul server, possono recuperare i dati direttamente e non inviano JavaScript al browser. Per i componenti che richiedono interazione, come i clic o lo stato dei moduli, aggiungi la direttiva use client in cima al file per renderli client component.

FileURL / scopo
app/layout.tsxScheletro radice dell'intero sito: html, body, header e footer condivisi
app/page.tsxHome page (/)
app/hakkimizda/page.tsxL'indirizzo /hakkimizda
app/blog/[slug]/page.tsxIndirizzo dinamico: /blog/qualsiasi-articolo
app/not-found.tsxPagina 404
app/api/iletisim/route.tsEndpoint API (handler POST e GET)

Metadati per la SEO

Ogni file di pagina o di layout può esportare un oggetto metadata per definire titolo, descrizione e tag Open Graph. Per le pagine dinamiche si usa la funzione generateMetadata. Questa struttura semplifica la gestione, a livello di pagina, dei tag necessari per un web design ottimizzato per la SEO.

Build e variabili d'ambiente

Prima di andare online, crea una build di produzione con npm run build. L'output della build indica se ogni pagina viene generata in modo statico o dinamico; una pagina che risulta dinamica in modo inatteso è un primo segnale di carico inutile sul server.

Le variabili d'ambiente si conservano nel file .env.local. Al browser vengono inviate solo le variabili con il prefisso NEXT_PUBLIC_; le password del database e le chiavi segrete delle API devono restare senza prefisso ed essere usate solo nel codice server.

bash
npm run build npm run start

Come dovrebbe essere renderizzata ogni pagina?

La forza di Next.js sta nel poter scegliere una strategia di rendering diversa per ogni pagina. Una scelta sbagliata significa costi di server inutili oppure contenuti non aggiornati, quindi classifica le vostre pagine per tipo subito dopo l'installazione.

Le pagine che cambiano raramente, come chi siamo, servizi e contatti, sono ideali per la generazione statica: vengono generate una sola volta in fase di build e servite dalla CDN in meno di un secondo. Quasi tutte le pagine di un sito web aziendale appartengono a questo gruppo.

Per le pagine aggiornate di tanto in tanto, come gli elenchi di blog e prodotti, rigenerarle a intervalli prestabiliti (revalidate) è un buon compromesso. Le dashboard personalizzate per utente, i carrelli o le schermate di prenotazione con disponibilità in tempo reale devono essere generati sul server a ogni richiesta. Quest'ultimo gruppo è uno scenario frequente nei software di settore come i sistemi per hotel e agenzie e richiede di progettare insieme database, cache e autorizzazioni.

Opzioni di deploy per Next.js

Esistono tre strade comuni per il deploy di Next.js. Quale scegliere dipende dal traffico, dal budget, dalla posizione dei dati e dall'esperienza del vostro team nella gestione dei server.

  • Vercel: la piattaforma dell'azienda che sviluppa Next.js. Colleghi il repository e ogni push produce una build automatica e un URL di anteprima.
  • Il vostro server Node.js: un gestore di processi come PM2 mantiene l'app in esecuzione con npm run start, con Nginx davanti. Offre pieno controllo, ma la manutenzione è a vostro carico.
  • Esportazione statica: con l'impostazione output: 'export' nel file next.config, il sito viene trasformato in semplici file HTML. Le funzioni dinamiche che richiedono server component non funzionano in questa modalità.

Messa online con PM2 e Nginx

Su un server basato su Ubuntu, dopo aver installato Node.js, scarica il progetto dal repository, esegui la build e avvialo con PM2. Il comando startup di PM2 vi chiede di eseguire con sudo la riga che stampa a schermo; quella riga fa avviare l'app automaticamente al riavvio del server.

bash
git clone https://github.com/kullanici/benim-sitem.git cd benim-sitem npm ci npm run build sudo npm install -g pm2 pm2 start npm --name benim-sitem -- start pm2 save pm2 startup
nginxConfigurazione del reverse proxy Nginx
server { listen 80; server_name ornek.com www.ornek.com; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

Errori comuni e soluzioni

La maggior parte degli errori nei progetti Next.js deriva da incompatibilità di versione o dalla mescolanza di codice server e client. Per i problemi di gestione dei pacchetti può aiutarti anche la nostra guida sui comandi npm.

SintomoSoluzione
Avviso di versione di Node non supportataPassa alla versione LTS corrente; se usi nvm, esegui nvm use --lts
Porta 3000 occupataScegli un'altra porta con npm run dev -- -p 3001
Errore Hydration failedSposta il codice che produce un output diverso su server e browser (date, numeri casuali, uso di window) in un client component o dentro useEffect
useState non può essere usato in un server componentAggiungi la direttiva use client in cima al file
La variabile d'ambiente è vuota in produzioneDefinisci la variabile anche sul server; se vi serve nel browser, usa il prefisso NEXT_PUBLIC_ e ripeti la build

Domande frequenti

01Devo usare il Pages Router o l'App Router?

Per i nuovi progetti la raccomandazione ufficiale è l'App Router; funzioni come i server component, i layout annidati e il rendering in streaming esistono solo in questa struttura. Il Pages Router è ancora supportato, quindi non hai fretta di migrare un vecchio progetto.

02Vercel è obbligatorio per Next.js?

No. Next.js è open source e funziona su qualsiasi server o container Docker in grado di eseguire Node.js. Vercel semplifica l'installazione; il vostro server può offrire vantaggi in termini di costi, posizione dei dati e controllo.

03Un progetto Next.js funziona su un hosting condiviso?

Un progetto che richiede funzioni server non funziona sul classico hosting condiviso dove non è possibile eseguire un processo Node.js. Se il vostro sito è completamente statico, potete caricare i file generati con output: export; altrimenti serve un VPS o un ambiente con Node abilitato.

Installare Next.js richiede solo pochi comandi; sono la giusta strategia di rendering e un ambiente di hosting solido a rendere un progetto duraturo. Se stai pianificando un'applicazione su misura per la vostra attività, come prenotazioni, annunci o un pannello di amministrazione, scopri le nostre soluzioni software; per un sito veloce e orientato ai contenuti, conosci il nostro team di web design.