Prima di iniziare
Installa Node.js 20 o successivo, npm, Git e la CLI Adios. Servono anche un account Adios e un repository Git di destinazione se vuoi eseguire il push dei sorgenti finali.
Crea il progetto Next.js
Questo comando rende esplicite le scelte: TypeScript, Tailwind, ESLint, App Router, la directory src , l’alias di importazione predefinito e npm.
npx create-next-app@latest ./my-project \
--ts \
--tailwind \
--eslint \
--app \
--src-dir \
--import-alias "@/*" \
--use-npm
cd my-project
npm run devAperto http://localhost:3000 e conferma che la pagina iniziale si carichi. Ferma il server di sviluppo prima di continuare se vuoi riutilizzare il terminale.
Sostituisci la pagina iniziale
Sostituisci src/app/page.tsx con una piccola pagina renderizzata sul server. Tenere i metadati nella pagina rende l’esempio completo senza modificare il layout radice generato.
import type { Metadata } from "next";
export const metadata: Metadata = {
title: "Northstar — A small app ready to ship",
description:
"A production-ready Next.js example with health and search metadata routes.",
};
const checks = [
"Responsive App Router page",
"Production health endpoint",
"Sitemap and robots routes",
"Repeatable Adios deployment",
];
export default function Home() {
return (
<main className="min-h-screen bg-slate-950 px-6 py-20 text-white">
<div className="mx-auto max-w-5xl">
<p className="text-sm font-semibold uppercase tracking-[0.18em] text-cyan-300">
Next.js on Adios
</p>
<h1 className="mt-5 max-w-3xl text-5xl font-bold tracking-tight sm:text-7xl">
Build the app. Keep the deployment clear.
</h1>
<p className="mt-6 max-w-2xl text-lg leading-8 text-slate-300">
This project has the files a production release needs, from a health
check to the runtime contract stored beside the source.
</p>
<div className="mt-12 grid gap-4 sm:grid-cols-2">
{checks.map((check) => (
<div
key={check}
className="rounded-xl border border-white/10 bg-white/5 p-5 text-base text-slate-200"
>
{check}
</div>
))}
</div>
<a
href="/api/health"
className="mt-10 inline-flex rounded-lg bg-white px-5 py-3 font-semibold text-slate-950"
>
Check application health
</a>
</div>
</main>
);
}Crea la route di integrità
Aggiungi src/app/api/health/route.ts. Adios richiederà questa route prima di promuovere il rilascio candidato.
export function GET() {
return Response.json({ status: "ok" });
}Mantieni rapida questa route. Se l’applicazione non può gestire il traffico senza un database o un altro servizio necessario, decidi se il controllo di disponibilità debba verificare anche quella dipendenza.
Aggiungi le route per sitemap e robots
I file di metadati Next.js generano gli endpoint pubblici /sitemap.xmle /robots.txt . Il fallback locale permette di lavorare in sviluppo; la produzione deve usare l’URL pubblico definitivo.
import type { MetadataRoute } from "next";
const siteUrl =
process.env.NEXT_PUBLIC_SITE_URL ?? "http://localhost:3000";
export default function sitemap(): MetadataRoute.Sitemap {
return [
{
url: siteUrl + "/",
lastModified: new Date(),
changeFrequency: "weekly",
priority: 1,
},
];
}import type { MetadataRoute } from "next";
const siteUrl =
process.env.NEXT_PUBLIC_SITE_URL ?? "http://localhost:3000";
export default function robots(): MetadataRoute.Robots {
return {
rules: {
userAgent: "*",
allow: "/",
},
sitemap: siteUrl + "/sitemap.xml",
};
}Crea adios.yaml nella radice del progetto
Questo file va accanto a package.json. Il file indica come Adios deve installare, compilare, avviare e controllare il progetto attuale.
name: my-nextjs-app
region: de
replicas: 1
build_cmd: npm ci && npm run build
start_cmd: npm start
env:
NEXT_PUBLIC_SITE_URL: https://replace-with-your-route.adios.run
runtime:
name: node@24
port: 3000
health_path: /api/health
memory_mb: 1024Mantieni il nome host segnaposto per la prima distribuzione. Quando Adios restituisce la route generata, sostituiscilo con l’origine HTTPS reale e distribuisci di nuovo, così la sitemap contiene l’URL corretto.
Esegui i controlli di produzione in locale
Il caricamento di una pagina in sviluppo non basta. Esegui il linter e la stessa compilazione di produzione che verrà usata per la distribuzione.
npm run lint
npm run buildSe uno dei comandi non riesce, correggi il primo errore e riesegui entrambi i controlli prima di distribuire.
Accedi e distribuisci i sorgenti attuali
Esegui i comandi dalla directory che contiene adios.yaml. Verifica le autorizzazioni richieste prima di consentire alla distribuzione di proseguire.
adios login
adios upAdios carica i sorgenti attuali, esegue la compilazione, avvia il processo di produzione, controlla /api/health, e restituisce una route HTTPS generata dopo che il rilascio ha superato i controlli di integrità.
Visita e verifica l’app in produzione
Apri il nome host generato e controlla tutte e quattro le risposte:
/mostra la nuova pagina./api/healthrestituisce{"status":"ok"}./robots.txtconsente la scansione e indica la sitemap./sitemap.xmlcontiene l'URL di produzione pubblica.
Sostituisci il segnaposto NEXT_PUBLIC_SITE_URL in adios.yaml con il nome host generato o il tuo dominio personalizzato, esegui adios up di nuovo e ripeti i controlli. Usa Domini e reindirizzamenti quando associ un nome host di produzione.
Verifica i sorgenti funzionanti, esegui il commit e il push
Verifica le modifiche prima di registrarle nella cronologia. Il diff deve mostrare la pagina, la route di integrità, le route dei metadati per i motori di ricerca e il manifest che hai appena verificato.
git status
git diff
git add src/app/page.tsx src/app/api/health/route.ts \
src/app/sitemap.ts src/app/robots.ts adios.yaml
git diff --cached
git commit -m "Build and deploy the Next.js app"
git remote -v
git push -u origin mainConferma il repository remoto e il branch prima del comando finale. Se git remote -v è vuoto, crea prima il repository remoto e aggiungi il suo URL come origin.
Progetto finito
Controlla i file prima della prossima funzionalità.
my-project/
├── adios.yaml
├── package.json
├── package-lock.json
└── src/
└── app/
├── api/
│ └── health/
│ └── route.ts
├── page.tsx
├── robots.ts
└── sitemap.tsProblemi comuni
Perché l’app Next.js ha bisogno di una route di integrità?
Adios usa la route di integrità per confermare che il processo di produzione sia pronto prima di promuovere il rilascio. Mantieni rapida la risposta e restituisci uno stato di successo solo quando l’app è in grado di gestire il traffico.
Perché devo sostituire l’URL del sito dopo la prima distribuzione?
Una sitemap richiede URL assoluti di produzione. La prima distribuzione su Adios crea il nome host generato: sostituisci il segnaposto in adios.yaml con quel nome host e distribuisci ancora una volta prima di considerare definitiva la sitemap.
Cosa succede se npm run build non riesce?
Correggi la compilazione locale di produzione prima di distribuire. Parti dal primo errore, verifica la versione di Node e il lockfile e non considerare un server di sviluppo funzionante come prova che la compilazione di produzione funzioni.
E se il rilascio si avvia ma non supera mai i controlli di integrità?
Verifica che package.json abbia uno script start che esegue next start, che l’app sia in ascolto sulla porta 3000 e che adios.yaml usi la stessa porta e il percorso /api/health. Poi esamina i log dell’ambiente di esecuzione per trovare il primo errore di avvio o del controllo di integrità prima di distribuire di nuovo.
E se il progetto non ha un repository Git remoto?
Crea un repository vuoto con il tuo fornitore Git, aggiungilo come origin, conferma il nome del branch, poi esegui il push. Non eseguire il comando push di esempio finché git remote -v non mostra la destinazione prevista.
Continua a sviluppare
Usa lo stesso contratto con un agente di programmazione con IA.
La guida all’IA trasforma questi stessi file e controlli in prompt per Codex, ChatGPT, Gemini e Claude.
Apri il workflow con IA