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.

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.
winget install OpenJS.NodeJS.LTS node -vmacOS
Potete installarlo con il pacchetto ufficiale o con Homebrew.
brew install node node -vLinux
La versione presente nei repository delle distribuzioni può essere obsoleta; installare con nvm è più sicuro.
nvm install --lts nvm use --lts node -vCreare 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.
| Domanda | Consiglio |
|---|---|
| TypeScript | Sì; individua gli errori mentre scrivi |
| ESLint | Sì; per la qualità del codice |
| Tailwind CSS | Facoltativo; scegli in base al vostro design system |
| Cartella src/ | Facoltativo; separa i file di configurazione dal codice |
| App Router | Sì; la struttura consigliata per i nuovi progetti |
| Alias di importazione | Il valore predefinito @/* è sufficiente |
npx create-next-app@latest benim-sitem cd benim-sitem npm run devCapire 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.
| File | URL / scopo |
|---|---|
| app/layout.tsx | Scheletro radice dell'intero sito: html, body, header e footer condivisi |
| app/page.tsx | Home page (/) |
| app/hakkimizda/page.tsx | L'indirizzo /hakkimizda |
| app/blog/[slug]/page.tsx | Indirizzo dinamico: /blog/qualsiasi-articolo |
| app/not-found.tsx | Pagina 404 |
| app/api/iletisim/route.ts | Endpoint 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.
npm run build npm run startCome 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.
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 startupserver { 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.
| Sintomo | Soluzione |
|---|---|
| Avviso di versione di Node non supportata | Passa alla versione LTS corrente; se usi nvm, esegui nvm use --lts |
| Porta 3000 occupata | Scegli un'altra porta con npm run dev -- -p 3001 |
| Errore Hydration failed | Sposta 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 component | Aggiungi la direttiva use client in cima al file |
| La variabile d'ambiente è vuota in produzione | Definisci 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.


