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 にはセクションが順番に格納され、各セクションはコントラクトのコンポーネントの 1 つを指し、そのフィールド値を持っています。

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 で Webhook を作成し（Integrations → Webhooks）、サイト上のルートを宛先に指定して、署名シークレットをサーバーの環境変数に保存します。受信したリクエストは、処理する前に必ず検証してください。正確な検証方法は Webhook をご覧ください。その後、影響を受けるルートに対して revalidatePath（または revalidateTag('atlas')）を呼び出します。

6. ビルドを報告する

サーバーの起動時に、このビルドが表示するコントラクトバンドルのダイジェストと、サポートするコンポーネントの ID とバージョンを添えて POST /deployments を送信します。すると Studio の Integrations → Website に、ウェブサイトが有効なコントラクトと同期しているかが表示されます。サイトが同期していない間は、リリースを本番環境へ進められません。詳細: Delivery API。

7. 確認する

Studio で公開したページが開発環境のウェブサイトに表示され、以前と同じ見た目である。
ATLAS_CMS_ORIGIN を誤ったアドレスに向けても、ウェブサイトが組み込みのコンテンツを提供し続ける。
署名が誤っている Webhook が拒否される。
配信トークンがどのブラウザバンドルにも含まれていない（.next/static の出力を検索してください）。
Studio にデプロイが In sync と表示される。

次へ: サイトの残りの部分については移行チェックリストをご覧ください。