Eine Next.js-Website anbinden

Diese Anleitung bindet eine bestehende Next.js-Website (App Router) an eine Atlas-Development-Umgebung an. Auf Ihrer öffentlichen Site ändert sich nichts, bis Sie den Code selbst deployen.

Hinweis

Studio enthält dieselben Schritte mit Ihren echten Werten (Guides → Connect the website), einschließlich fertiger Briefings für einen KI-Coding-Agenten.

Bevor Sie beginnen

• Eine Site in Atlas Studio und ein aktiver Site-Contract dafür. Siehe Site-Contract.
• Ihre Website kann Servercode ausführen: Server Components, Route Handler, Node oder Cloudflare Workers.
• Der HTTPS-Origin, auf dem Ihre Development-Website läuft (oder http://localhost, solange Sie lokal arbeiten).

1. Ein Delivery-Token erstellen

Öffnen Sie in Studio Integrations → Website → New delivery token. Wählen Sie eine Gültigkeitsdauer (1 bis 365 Tage). Das Token wird einmalig angezeigt; Atlas speichert nur einen Fingerabdruck davon.

Legen Sie die Werte in der Server-Umgebung Ihrer Website ab, zum Beispiel in .env.local oder in den Umgebungseinstellungen Ihres Hosts:

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

Das Token auf dem Server halten

Versehen Sie es nie mit dem Präfix NEXT_PUBLIC_, senden Sie es nie an den Browser und committen Sie es nie. Jeder mit dem Token kann die veröffentlichten Inhalte dieser Umgebung lesen.

2. Einen kleinen serverseitigen Client hinzufügen

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
  }
}

Der Client gibt null zurück, wenn Atlas nicht erreichbar ist. Genau das lässt den Fallback funktionieren.

3. Eine Seite aus ihren Abschnitten rendern

Der Endpunkt pages liefert die veröffentlichte Seite zu einer Route. Seine document.regions enthalten Abschnitte in der richtigen Reihenfolge; jeder Abschnitt benennt eine Komponente Ihres Contracts und trägt deren Feldwerte.

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 ordnet jede component.id (zum Beispiel acme.home.hero) Ihres Contracts Ihrer vorhandenen React-Komponente zu. Rendern Sie Feldwerte als Text oder über Ihre Komponenten. Übergeben Sie CMS-Inhalte nie an dangerouslySetInnerHTML.

Ihre fest codierten Routen funktionieren weiter neben dieser Catch-all-Route. Sie entscheiden, welche Routen Atlas verwaltet.

4. Entwurfsvorschau hinzufügen

Die Studio-Funktion Preview on website öffnet https://<your site>/api/atlas/preview?token=…. Der Link ist 15 Minuten gültig. Fügen Sie diese Route hinzu:

// 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.

Die Vorschau funktioniert nur für Development-Umgebungen.

Damit Redakteure Entwürfe im Seiteneditor von Studio sehen können, erlauben Sie Studio in Ihrer Content-Security-Policy: frame-ancestors 'self' https://<studio origin>. Optionales Click-to-edit ist beschrieben unter Vorschau, Veröffentlichung und Rollback.

5. Seiten im Moment der Veröffentlichung aktualisieren

Erstellen Sie in Studio einen Webhook (Integrations → Webhooks), der auf eine Route Ihrer Site zeigt, und legen Sie sein Signaturgeheimnis in einer Server-Umgebungsvariable ab. Verifizieren Sie jede Anfrage, bevor Sie darauf reagieren; die genaue Prüfung steht unter Webhooks. Rufen Sie dann revalidatePath für die betroffenen Routen auf (oder revalidateTag('atlas')).

6. Ihren Build melden

Wenn Ihr Server startet, senden Sie POST /deployments mit dem Digest des Contract-Bundles, das dieser Build rendert, sowie den Komponenten-IDs und -Versionen, die er unterstützt. Studio zeigt dann unter Integrations → Website an, ob die Website mit dem aktiven Contract synchron ist. Ein Release kann nicht nach Production gehen, solange die Site nicht synchron ist. Details: Delivery API.

7. Prüfen

• Eine in Studio veröffentlichte Seite erscheint auf Ihrer Development-Website und sieht aus wie zuvor.
• Wenn ATLAS_CMS_ORIGIN auf eine falsche Adresse zeigt, liefert die Website weiterhin ihre integrierten Inhalte aus.
• Ein Webhook mit falscher Signatur wird abgelehnt.
• Das Delivery-Token taucht in keinem Browser-Bundle auf (durchsuchen Sie Ihre .next/static-Ausgabe).
• Studio zeigt das Deployment als In sync an.

Weiter: Migrations-Checkliste für den Rest der Site.