Conectar un sitio web Next.js

Esta guía conecta un sitio web Next.js (App Router) existente a un entorno de Desarrollo de Atlas. No cambia nada en su sitio público hasta que usted despliegue el código.

Nota

Studio contiene los mismos pasos con sus valores reales ya rellenados (Guides → Connect the website), incluidas instrucciones listas para un agente de programación con IA.

Antes de empezar

• Un sitio en Atlas Studio y un contrato del sitio activo para él. Consulte Contrato del sitio.
• Su sitio web puede ejecutar código de servidor: componentes de servidor, controladores de ruta, Node o Cloudflare Workers.
• El origen HTTPS en el que se ejecuta su sitio web de Desarrollo (o http://localhost mientras trabaja en local).

1. Crear un token de entrega

En Studio abra Integrations → Website → New delivery token. Elija una vigencia (de 1 a 365 días). El token se muestra una sola vez; Atlas almacena únicamente una huella de él.

Coloque los valores en el entorno de servidor de su sitio web, por ejemplo .env.local o los ajustes de entorno de su proveedor de alojamiento:

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

Mantenga el token en el servidor

Nunca le anteponga NEXT_PUBLIC_, nunca lo envíe al navegador y nunca lo incluya en el repositorio. Cualquier persona que tenga el token puede leer el contenido publicado de ese entorno.

2. Añadir un pequeño cliente solo de servidor

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

El cliente devuelve null cuando Atlas no está disponible. Eso es lo que hace funcionar el respaldo.

3. Renderizar una página a partir de sus secciones

El endpoint pages devuelve la página publicada para una ruta. Su document.regions contiene las secciones en orden; cada sección nombra uno de los componentes de su contrato y trae los valores de sus campos.

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 asigna cada component.id (por ejemplo acme.home.hero) de su contrato a su componente React existente. Renderice los valores de los campos como texto o a través de sus componentes. Nunca pase contenido del CMS a dangerouslySetInnerHTML.

Sus rutas escritas directamente en el código siguen funcionando junto a esta ruta comodín. Usted decide qué rutas gestiona Atlas.

4. Añadir la previsualización de borradores

Preview on website de Studio abre https://<your site>/api/atlas/preview?token=…. El enlace es válido durante 15 minutos. Añada esa ruta:

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

La previsualización funciona solo en entornos de Desarrollo.

Para que los editores vean los borradores dentro del editor de páginas de Studio, permita a Studio en su Content-Security-Policy: frame-ancestors 'self' https://<studio origin>. La edición opcional con clic se describe en Previsualizar, publicar y revertir.

5. Actualizar las páginas en el momento en que se publica el contenido

Cree un webhook en Studio (Integrations → Webhooks) que apunte a una ruta de su sitio y guarde su secreto de firma en una variable de entorno de servidor. Verifique cada solicitud antes de actuar sobre ella; consulte Webhooks para la comprobación exacta. Después llame a revalidatePath para las rutas afectadas (o a revalidateTag('atlas')).

6. Informar de su compilación

Cuando su servidor arranque, envíe POST /deployments con el resumen (digest) del paquete de contrato que esta compilación renderiza y los ids y versiones de los componentes que admite. Studio mostrará entonces en Integrations → Website si el sitio web está in sync con el contrato activo. Un lanzamiento no puede pasar a Producción mientras el sitio esté desincronizado. Detalles: API de entrega.

7. Comprobarlo

• Una página publicada en Studio aparece en su sitio web de Desarrollo y se ve igual que antes.
• Con ATLAS_CMS_ORIGIN apuntando a una dirección incorrecta, el sitio web sigue sirviendo su contenido integrado.
• Un webhook con una firma incorrecta es rechazado.
• El token de entrega no aparece en ningún paquete del navegador (busque en la salida de .next/static).
• Studio muestra el despliegue como In sync.

Siguiente: la lista de comprobación de migración para el resto del sitio.