Come installare Next.js su Saplo

Next.js è oggi la scelta predefinita se stai creando un sito web o un'applicazione in React che deve caricarsi velocemente e posizionarsi bene nei risultati di ricerca. Il rendering lato server e l'App Router fanno una differenza che una classica applicazione SPA composta da un semplice build statico non può offrire. Il problema è che un'applicazione di questo tipo richiede un processo Node.js in esecuzione in background, non solo una directory con file HTML, quindi l'hosting su un hosting condiviso standard di solito non funziona. Su Saplo, installi Next.js come qualsiasi altra applicazione dal catalogo, e Saplo lo esegue immediatamente come servizio gestito con riavvio automatico. Di seguito, ti mostriamo come farlo da zero, inclusa la connessione del tuo repository Git.

Next.js su Saplo, a chi è destinato?

Prima di iniziare l'installazione, verifica se è la scelta giusta per il tuo progetto:

• hai o stai creando un progetto in Next.js con App Router - Saplo rileva la struttura del progetto ed esegue next start come servizio, non devi scrivere tu stesso la configurazione di pm2 o systemd,
• hai bisogno di SSR o ISR, non solo di una build statica - se il tuo sito è completamente statico, uno stack React o Astro dallo stesso Catalogo delle applicazioni sarà più economico e leggero,
• vuoi implementazioni con git push invece del caricamento manuale dei file - colleghi il repository una volta, e ogni push sul branch di produzione costruisce e implementa automaticamente una nuova versione,
• la tua fattura per l'hosting del progetto, che oggi si trova su Vercel o Netlify, sta aumentando - migri il codice uno a uno, next.config.* rimane invariato, paghi per il Box invece che per il consumo delle funzioni.

Se il tuo progetto è un frontend puro senza bisogno di rendering lato server, controlla nel Catalogo delle applicazioni lo stack React o Astro; entrambi sono più leggeri ed economici da mantenere.

Requisiti

Per ospitare Next.js su Saplo, hai bisogno di:

• Un Box nel piano L o superiore - Saplo raccomanda ufficialmente questo livello per Next.js, perché il rendering lato server richiede più RAM rispetto a un normale sito statico; i piani inferiori sono sufficienti solo per un traffico di test molto ridotto.
• Un minimo di 512 MB di RAM libera e 2 GB di spazio su disco solo per il processo dell'applicazione.
• Un Dominio o sottodominio *.saploapp.pl incluso in ogni piano, dove verrà ospitata l'applicazione.
• Un repository Git su GitHub, GitLab o Bitbucket, se vuoi utilizzare il deploy automatico (opzionale per iniziare, puoi anche caricare l'applicazione come archivio .zip tramite il Pannello).
• Di solito NON hai bisogno di un database separato, a meno che la tua applicazione non si connetta a uno; Saplo non te lo impone.

Installazione passo dopo passo

1. Nel Pannello Saplo, vai su Catalogo delle applicazioni e seleziona Next.js (categoria "Framework").
2. Seleziona un Box del piano L o superiore e il nome dell'applicazione - da questo verrà creato il sottodominio predefinito <name>.saploapp.pl; puoi aggiungere il tuo Dominio ora o in seguito.
3. Conferma l'installazione. Il motore provisiona il modulo sul Box e avvia lo scheletro di Next.js (equivalente a create-next-app), in modo che ci sia subito qualcosa da vedere sotto il Dominio prima di distribuire il tuo codice.
4. Saplo avvia l'applicazione come servizio gestito con riavvio automatico, e nginx sul Box instrada il traffico dal Dominio alla porta del processo Next.js.
5. Al termine dell'installazione, il Dominio del passo 2 mostra una pagina iniziale funzionante - da questo momento puoi distribuire il tuo progetto su di essa.

Deploy del tuo codice tramite Git

1. Nei dettagli dell'applicazione, trova la sezione Git / CI-CD e clicca su "Connetti GitHub", conferma l'installazione dell'app "Saplo Deploy" sul tuo account o organizzazione e indica il repository con il progetto Next.js.
2. Nella directory principale del repository, deve essere presente il file saplo.yaml, lo genererai con il comando saplo init oppure lo scriverai manualmente (esempio sotto).
3. Esegui il commit e il push del file saplo.yaml sul branch di produzione (di default main, lo cambierai nella sezione branches.production dello stesso file).
4. Ogni successivo git push su questo branch avvia una build e un deploy automatici, lo stato lo vedi nel pannello nella scheda Deploymenti e come un indicatore verde o rosso accanto al commit su GitHub.
5. Se la build o l'healthcheck falliscono, la precedente versione funzionante dell'applicazione rimane al suo posto, Saplo non la sostituisce con una danneggiata.

Esempio di un file saplo.yaml minimo per Next.js:

name: my-project
stack: nextjs
runtime:
  node: "22"
build:
  install: npm ci
  command: npm run build
start:
  command: npm start
  port: 3000

Il push di questo file è uguale a qualsiasi altro commit:

git add saplo.yaml
git commit -m "add saplo.yaml"
git push origin main

Next.js su Saplo vs. alternative

Domande frequenti

Devo collegare Git subito, o posso iniziare senza? Puoi iniziare senza Git. L'installazione dal Catalogo delle applicazioni crea uno scheletro Next.js funzionante e puoi effettuare la prima distribuzione del tuo codice caricando un archivio .zip nel Pannello. Puoi collegare Git in qualsiasi momento successivo.

Perché si raccomanda il Box L e non un piano inferiore? Perché il rendering lato server (SSR) mantiene il processo Node.js costantemente in memoria e risponde a ogni nuova richiesta, a differenza di una pagina statica, che una volta costruita risiede sul disco. I piani inferiori sono sufficienti per i test, ma sotto un traffico di produzione reale mancheranno di RAM sufficiente. Il Box L costa 139 € all'anno.

Cosa succede se il file saplo.yaml non è presente nel repository? Alla prima distribuzione senza questo file, il deploy fallirà. Nelle distribuzioni successive, se il file scompare da un commit specifico, Saplo utilizzerà la configurazione dell'ultima distribuzione riuscita.

Devo impostare manualmente la porta dell'applicazione? Non devi, la porta predefinita è 3000 e la maggior parte dei progetti Next.js non richiede la sua modifica. Se la tua applicazione la cambia, impostala nella sezione start.port del file saplo.yaml.

Posso avere più applicazioni Next.js su un singolo Box? Sì, il Catalogo delle applicazioni consente di installare molti moduli su un singolo Box, ciascuno con il proprio sottodominio o Dominio, finché ci sono sufficiente RAM e spazio su disco assegnati al piano.

Puoi configurare Next.js su Saplo da zero a un Dominio funzionante in pochi minuti, e ogni git push successivo distribuisce una nuova versione senza il tuo intervento. Se stai migrando un progetto esistente da Vercel o Netlify e qualcosa non funziona come dovrebbe, scrivici, ti aiuteremo a scegliere la configurazione in saplo.yaml.