Connecter un site Next.js

Ce guide connecte un site web Next.js (App Router) existant à un environnement Development d’Atlas. Rien ne change sur votre site public tant que vous n’avez pas déployé le code vous-même.

Note

Studio propose les mêmes étapes avec vos valeurs réelles déjà renseignées (Guides → Connect the website), y compris des briefs prêts à l’emploi pour un agent de code IA.

Avant de commencer

• Un site dans Atlas Studio, et un contrat de site actif pour celui-ci. Voir Contrat de site.
• Votre site web peut exécuter du code serveur : composants serveur, route handlers, Node ou Cloudflare Workers.
• L’origine HTTPS sur laquelle tourne votre site Development (ou http://localhost pendant que vous travaillez en local).

1. Créer un jeton de diffusion

Dans Studio, ouvrez Integrations → Website → New delivery token. Choisissez une durée de vie (de 1 à 365 jours). Le jeton n’est affiché qu’une seule fois ; Atlas n’en conserve qu’une empreinte.

Placez les valeurs dans l’environnement serveur de votre site web, par exemple .env.local ou les paramètres d’environnement de votre hébergeur :

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

Gardez le jeton côté serveur

Ne le préfixez jamais par NEXT_PUBLIC_, ne l’envoyez jamais au navigateur et ne le commitez jamais. Quiconque possède le jeton peut lire le contenu publié de cet environnement.

2. Ajouter un petit client réservé au serveur

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

Le client renvoie null lorsqu’Atlas est injoignable. C’est ce qui fait fonctionner le contenu de repli.

3. Afficher une page à partir de ses sections

Le point d’accès pages renvoie la page publiée pour une route. Son document.regions contient les sections dans l’ordre ; chaque section désigne l’un des composants de votre contrat et porte les valeurs de ses champs.

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 associe chaque component.id (par exemple acme.home.hero) de votre contrat à votre composant React existant. Affichez les valeurs des champs sous forme de texte ou via vos composants. Ne transmettez jamais de contenu CMS à dangerouslySetInnerHTML.

Vos routes codées en dur continuent de fonctionner à côté de cette route fourre-tout. Vous décidez quelles routes Atlas gère.

4. Ajouter l’aperçu des brouillons

La commande Preview on website de Studio ouvre https://<your site>/api/atlas/preview?token=…. Le lien est valable 15 minutes. Ajoutez cette route :

// 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’aperçu ne fonctionne que pour les environnements Development.

Pour que les éditeurs voient les brouillons dans l’éditeur de pages de Studio, autorisez Studio dans votre Content-Security-Policy : frame-ancestors 'self' https://<studio origin>. Le click-to-edit optionnel est décrit dans Prévisualiser, publier et revenir en arrière.

5. Rafraîchir les pages dès que le contenu est publié

Créez un webhook dans Studio (Integrations → Webhooks) pointant vers une route de votre site, et stockez son secret de signature dans une variable d’environnement serveur. Vérifiez chaque requête avant d’agir ; voir Webhooks pour la vérification exacte. Appelez ensuite revalidatePath pour les routes concernées (ou revalidateTag('atlas')).

6. Signaler votre build

Au démarrage de votre serveur, envoyez POST /deployments avec l’empreinte du bundle de contrat que ce build utilise, ainsi que les identifiants et versions des composants qu’il prend en charge. Studio indique alors sous Integrations → Website si le site web est synchronisé avec le contrat actif. Une release ne peut pas passer en Production tant que le site n’est pas synchronisé. Détails : API Delivery.

7. Vérifier

• Une page publiée dans Studio apparaît sur votre site Development et a le même aspect qu’avant.
• Avec ATLAS_CMS_ORIGIN pointant vers une mauvaise adresse, le site web sert toujours son contenu intégré.
• Un webhook avec une signature incorrecte est rejeté.
• Le jeton de diffusion n’apparaît dans aucun bundle navigateur (recherchez dans votre sortie .next/static).
• Studio affiche le déploiement comme In sync.

Suite : la liste de contrôle de migration pour le reste du site.