Next.js 웹사이트 연결

기존 Next.js App Router 사이트에서 게시된 Atlas 콘텐츠를 읽고, 미리보기, 폴백, 게시 즉시 새로 고침을 구성합니다.

이 페이지는 영어에서 번역되었습니다. 내용이 다를 경우 영어 버전이 우선합니다. 영어로 읽기

이 가이드는 기존 Next.js(App Router) 웹사이트를 Atlas 개발 환경에 연결합니다. 코드를 직접 배포하기 전에는 공개 사이트에 아무것도 바뀌지 않습니다.

시작하기 전에

Atlas Studio의 사이트와 그 사이트의 활성 사이트 계약. 사이트 계약을 참고하세요.
웹사이트가 서버 코드를 실행할 수 있어야 합니다: 서버 컴포넌트, 라우트 핸들러, Node 또는 Cloudflare Workers.
개발 웹사이트가 실행되는 HTTPS 출처(로컬에서 작업하는 동안은 http://localhost).

1. 전달 토큰 만들기

Studio에서 Integrations → Website → New delivery token을 엽니다. 유효 기간(1일에서 365일)을 선택합니다. 토큰은 한 번만 표시되며, Atlas는 토큰의 지문만 저장합니다.

값을 웹사이트의 서버 환경 변수에 넣습니다. 예를 들어 .env.local 또는 호스트의 환경 설정입니다.

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

2. 서버 전용 클라이언트 추가

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

Atlas에 연결할 수 없으면 클라이언트는 null을 반환합니다. 이것이 폴백이 동작하는 방식입니다.

3. 섹션으로 페이지 렌더링

pages 엔드포인트는 경로에 해당하는 게시된 페이지를 반환합니다. document.regions에 섹션이 순서대로 들어 있으며, 각 섹션은 계약의 컴포넌트 하나를 가리키고 그 필드 값을 담고 있습니다.

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은 계약의 각 component.id(예: acme.home.hero)를 기존 React 컴포넌트에 매핑합니다. 필드 값은 텍스트로 또는 여러분의 컴포넌트를 통해 렌더링하세요. CMS 콘텐츠를 dangerouslySetInnerHTML에 절대 전달하지 마세요.

직접 작성한 고정 경로는 이 포괄 경로와 나란히 계속 동작합니다. 어떤 경로를 Atlas가 관리할지는 여러분이 결정합니다.

4. 초안 미리보기 추가

Studio의 Preview on website는 https://<your site>/api/atlas/preview?token=…을 엽니다. 링크는 15분 동안 유효합니다. 해당 경로를 추가하세요.

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

미리보기는 개발 환경에서만 동작합니다.

편집자가 Studio의 페이지 편집기 안에서 초안을 볼 수 있게 하려면 Content-Security-Policy에서 Studio를 허용하세요: frame-ancestors 'self' https://<studio origin>. 선택 사항인 클릭 편집은 미리보기, 게시, 롤백에서 설명합니다.

5. 콘텐츠가 게시되는 즉시 페이지 새로 고침

Studio(Integrations → Webhooks)에서 사이트의 경로를 가리키는 웹훅을 만들고, 서명 비밀 값을 서버 환경 변수에 저장합니다. 요청을 처리하기 전에 매번 검증하세요. 정확한 검증 방법은 웹훅을 참고하세요. 그런 다음 영향받은 경로에 대해 revalidatePath(또는 revalidateTag('atlas'))를 호출합니다.

6. 빌드 보고

서버가 시작될 때, 이 빌드가 렌더링하는 계약 번들의 다이제스트와 지원하는 컴포넌트 ID 및 버전을 담아 POST /deployments를 보냅니다. 그러면 Studio의 Integrations → Website에서 웹사이트가 활성 계약과 In sync 상태인지 확인할 수 있습니다. 사이트가 동기화되지 않은 동안에는 릴리스를 프로덕션으로 보낼 수 없습니다. 자세한 내용: Delivery API.

7. 확인

Studio에서 게시한 페이지가 개발 웹사이트에 나타나고 이전과 동일하게 보입니다.
ATLAS_CMS_ORIGIN을 잘못된 주소로 지정해도 웹사이트가 내장 콘텐츠를 계속 제공합니다.
서명이 잘못된 웹훅은 거부됩니다.
전달 토큰이 어떤 브라우저 번들에도 나타나지 않습니다(.next/static 출력에서 검색하세요).
Studio가 배포를 In sync로 표시합니다.

다음: 나머지 사이트는 마이그레이션 체크리스트를 참고하세요.