Conectar um site Next.js

Leia o conteúdo publicado do Atlas no seu site Next.js App Router existente, com pré-visualização, fallback e atualização instantânea ao publicar.

Esta página foi traduzida do inglês. Se houver qualquer diferença, vale a versão em inglês. Ler em inglês

Este guia conecta um site Next.js (App Router) existente a um ambiente Development do Atlas. Nada muda no seu site público até que você mesmo faça o deploy do código.

Antes de começar

Um site no Atlas Studio e um contrato do site ativo para ele. Veja Contrato do site.
Seu site consegue executar código de servidor: server components, route handlers, Node ou Cloudflare Workers.
A origem HTTPS em que o seu site de Development roda (ou http://localhost enquanto você trabalha localmente).

1. Crie um token de entrega

No Studio, abra Integrations → Website → New delivery token. Escolha uma validade (de 1 a 365 dias). O token é exibido uma única vez; o Atlas armazena apenas uma impressão digital dele.

Coloque os valores no ambiente de servidor do seu site, por exemplo .env.local ou as configurações de ambiente da sua hospedagem:

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

2. Adicione um pequeno cliente exclusivo do servidor

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

O cliente retorna null quando o Atlas está inacessível. É isso que faz o fallback funcionar.

3. Renderize uma página a partir das suas seções

O endpoint pages retorna a página publicada de uma rota. Os document.regions dela guardam as seções em ordem; cada seção indica um dos componentes do seu contrato e traz os valores dos campos.

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

O renderSection associa cada component.id (por exemplo acme.home.hero) do seu contrato ao seu componente React existente. Renderize os valores dos campos como texto ou por meio dos seus componentes. Nunca passe conteúdo do CMS para dangerouslySetInnerHTML.

Suas rotas fixas no código continuam funcionando ao lado desta rota catch-all. Você decide quais rotas o Atlas gerencia.

4. Adicione a pré-visualização de rascunhos

O botão Preview on website do Studio abre https://<your site>/api/atlas/preview?token=…. O link é válido por 15 minutos. Adicione essa rota:

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

A pré-visualização funciona apenas em ambientes Development.

Para que os editores vejam os rascunhos dentro do editor de páginas do Studio, permita o Studio no seu Content-Security-Policy: frame-ancestors 'self' https://<studio origin>. O clique para editar, opcional, é descrito em Pré-visualizar, publicar e reverter.

5. Atualize as páginas no instante em que o conteúdo é publicado

Crie um webhook no Studio (Integrations → Webhooks) apontando para uma rota do seu site e guarde o segredo de assinatura dele em uma variável de ambiente do servidor. Verifique cada requisição antes de agir sobre ela; veja Webhooks para a verificação exata. Depois chame revalidatePath para as rotas afetadas (ou revalidateTag('atlas')).

6. Informe o seu build

Quando o servidor iniciar, envie POST /deployments com o digest do bundle do contrato que este build renderiza e os ids e versões dos componentes que ele suporta. O Studio então mostra em Integrations → Website se o site está in sync com o contrato ativo. Um release não pode ir para Production enquanto o site estiver dessincronizado. Detalhes: Delivery API.

7. Confira

Uma página publicada no Studio aparece no seu site de Development e fica igual ao que era antes.
Com ATLAS_CMS_ORIGIN apontando para um endereço errado, o site continua servindo o conteúdo embutido nele.
Um webhook com assinatura errada é rejeitado.
O token de entrega não aparece em nenhum bundle do navegador (pesquise na saída de .next/static).
O Studio mostra o deployment como In sync.

Próximo passo: o checklist de migração para o restante do site.