Collegare un sito Next.js

Questa guida collega un sito web Next.js (App Router) esistente a un ambiente di Sviluppo di Atlas. Nulla cambia sul Suo sito pubblico finché non distribuisce Lei stesso il codice.

Nota

Studio contiene gli stessi passaggi con i Suoi valori reali già inseriti (Guide → Collegare il sito web), compresi brief pronti per un agente di programmazione IA.

Prima di iniziare

• Un sito in Atlas Studio e un contratto del sito attivo. Vedere Contratto del sito.
• Il Suo sito web può eseguire codice server: server component, route handler, Node o Cloudflare Workers.
• L’origine HTTPS su cui gira il Suo sito web di Sviluppo (oppure http://localhost mentre lavora in locale).

1. Creare un token di consegna

In Studio apra Integrations → Website → New delivery token. Scelga una durata (da 1 a 365 giorni). Il token viene mostrato una sola volta; Atlas ne conserva solo un’impronta.

Inserisca i valori nell’ambiente server del Suo sito web, per esempio .env.local o le impostazioni di ambiente del Suo host:

ATLAS_CMS_ORIGIN=https://delivery.atlas.example
ATLAS_ENVIRONMENT_ID=env_XXXXXXXX
ATLAS_DELIVERY_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Tenga il token sul server

Non lo faccia mai precedere da NEXT_PUBLIC_, non lo invii mai al browser e non ne faccia mai il commit. Chiunque possieda il token può leggere i contenuti pubblicati di quell’ambiente.

2. Aggiungere un piccolo client solo lato server

lib/atlas.ts

import 'server-only';

export type AtlasSection = {
  id: string;
  component: { id: string; version: string }; // a component from your site contract
  props: Record<string, unknown>;
  hidden: boolean;
};
export type AtlasPage = {
  page: { id: string; route: string; title: string };
  document: { regions: Record<string, AtlasSection[]> }; // region keys come from your page type
  seo: { title: string; description: string; noindex: boolean; canonicalPath?: string };
  assets: Record<string, { url: string; alt?: string }>;
};

const base = `${process.env.ATLAS_CMS_ORIGIN}/v1/delivery/environments/${process.env.ATLAS_ENVIRONMENT_ID}`;

export async function atlas<T>(path: string, init?: { revalidate?: number }): Promise<T | null> {
  try {
    const response = await fetch(`${base}${path}`, {
      headers: { Authorization: `PublishedConsumer ${process.env.ATLAS_DELIVERY_TOKEN}` },
      next: { revalidate: init?.revalidate ?? 60, tags: ['atlas'] },
      signal: AbortSignal.timeout(5000),
    });
    if (response.status === 404) return null;
    if (!response.ok) throw new Error(`Atlas ${response.status}`);
    return (await response.json()) as T;
  } catch (error) {
    console.error('Atlas unavailable, using built-in content', error);
    return null; // the caller falls back to the site's own content
  }
}

Il client restituisce null quando Atlas non è raggiungibile. È ciò che fa funzionare il fallback.

3. Generare una pagina dalle sue sezioni

L’endpoint pages restituisce la pagina pubblicata per un percorso. Le sue document.regions contengono le sezioni in ordine; ogni sezione indica uno dei componenti del Suo contratto e riporta i valori dei suoi campi.

app/[[...slug]]/page.tsx

import { notFound } from 'next/navigation';
import { atlas, type AtlasPage } from '@/lib/atlas';
import { renderSection } from '@/atlas/sections';
import { builtInPage } from '@/content/built-in';

export const revalidate = 300;

export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
  const route = '/' + ((await params).slug ?? []).join('/');
  const page = await atlas<AtlasPage>(`/pages?route=${encodeURIComponent(route)}`);

  if (!page) {
    const fallback = builtInPage(route); // today's content, unchanged
    if (!fallback) notFound();
    return fallback;
  }
  const sections = (page.document.regions.main ?? []).filter((section) => !section.hidden);
  return <main>{sections.map((section) => renderSection(section, page.assets))}</main>;
}

renderSection associa ogni component.id (per esempio acme.home.hero) del Suo contratto al Suo componente React esistente. Renda i valori dei campi come testo o tramite i Suoi componenti. Non passi mai contenuti del CMS a dangerouslySetInnerHTML.

I Suoi percorsi scritti nel codice continuano a funzionare accanto a questo percorso catch-all. È Lei a decidere quali percorsi gestisce Atlas.

4. Aggiungere l’anteprima delle bozze

Preview on website di Studio apre https://<your site>/api/atlas/preview?token=…. Il link è valido per 15 minuti. Aggiunga quel percorso:

// app/api/atlas/preview/route.ts — outline
// 1. Read ?token= and call GET /preview/pages?token=<token> with your delivery token.
// 2. 403 PREVIEW_INVALID or 410 PREVIEW_EXPIRED → show a plain error.
// 3. Render the draft with <meta name="robots" content="noindex"> and never cache it.

L’anteprima funziona solo per gli ambienti di Sviluppo.

Per consentire ai redattori di vedere le bozze nell’editor di pagina di Studio, autorizzi Studio nella Sua Content-Security-Policy: frame-ancestors 'self' https://<studio origin>. La modifica opzionale con clic è descritta in Anteprima, pubblicazione e ripristino.

5. Aggiornare le pagine nel momento in cui i contenuti vengono pubblicati

Crei un webhook in Studio (Integrations → Webhooks) che punti a un percorso del Suo sito e conservi il suo segreto di firma in una variabile d’ambiente del server. Verifichi ogni richiesta prima di agire; per il controllo esatto vedere Webhook. Poi chiami revalidatePath per i percorsi interessati (oppure revalidateTag('atlas')).

6. Segnalare la Sua build

All’avvio del server, invii POST /deployments con il digest del bundle del contratto che questa build rende e gli id e le versioni dei componenti che supporta. Studio mostra quindi in Integrations → Website se il sito web è allineato (in sync) con il contratto attivo. Un rilascio non può andare in Produzione mentre il sito non è allineato. Dettagli: API di consegna.

7. Verificare

• Una pagina pubblicata in Studio compare sul Suo sito web di Sviluppo e appare identica a prima.
• Con ATLAS_CMS_ORIGIN puntato a un indirizzo errato, il sito web serve comunque i propri contenuti integrati.
• Un webhook con una firma errata viene rifiutato.
• Il token di consegna non compare in nessun bundle del browser (cerchi nell’output di .next/static).
• Studio mostra la distribuzione come In sync.

Passo successivo: la checklist di migrazione per il resto del sito.