Hubungkan situs web Next.js

Panduan ini menghubungkan situs web Next.js (App Router) yang sudah ada ke lingkungan Development Atlas. Tidak ada yang berubah di situs publik Anda sampai Anda sendiri men-deploy kodenya.

Catatan

Studio memiliki langkah yang sama dengan nilai asli Anda sudah terisi (Panduan → Hubungkan situs web), termasuk brief siap pakai untuk agen pengodean AI.

Sebelum memulai

• Sebuah situs di Atlas Studio, dan kontrak situs aktif untuknya. Lihat Kontrak situs.
• Situs web Anda dapat menjalankan kode server: komponen server, route handler, Node, atau Cloudflare Workers.
• Origin HTTPS tempat situs web Development Anda berjalan (atau http://localhost saat Anda bekerja secara lokal).

1. Buat token pengiriman

Di Studio buka Integrations → Website → New delivery token. Pilih masa berlaku (1 hingga 365 hari). Token ditampilkan satu kali; Atlas hanya menyimpan sidik jarinya.

Letakkan nilai-nilai tersebut di lingkungan server situs web Anda, misalnya .env.local atau pengaturan lingkungan host Anda:

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

Simpan token hanya di server

Jangan pernah memberinya awalan NEXT_PUBLIC_, jangan pernah mengirimkannya ke browser, dan jangan pernah meng-commit-nya. Siapa pun yang memegang token dapat membaca konten terbit lingkungan tersebut.

2. Tambahkan klien kecil khusus server

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

Klien mengembalikan null saat Atlas tidak dapat dijangkau. Itulah yang membuat fallback bekerja.

3. Render halaman dari seksinya

Endpoint pages mengembalikan halaman terbit untuk suatu rute. document.regions berisi seksi secara berurutan; setiap seksi menyebut salah satu komponen dalam kontrak Anda dan membawa nilai bidangnya.

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 memetakan setiap component.id (misalnya acme.home.hero) dalam kontrak Anda ke komponen React Anda yang sudah ada. Render nilai bidang sebagai teks atau melalui komponen Anda. Jangan pernah meneruskan konten CMS ke dangerouslySetInnerHTML.

Rute Anda yang ditulis langsung dalam kode tetap berfungsi berdampingan dengan rute catch-all ini. Anda yang menentukan rute mana yang dikelola Atlas.

4. Tambahkan pratinjau draf

Preview on website di Studio membuka https://<your site>/api/atlas/preview?token=…. Tautan berlaku selama 15 menit. Tambahkan rute tersebut:

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

Pratinjau hanya berfungsi untuk lingkungan Development.

Agar editor dapat melihat draf di dalam editor halaman Studio, izinkan Studio dalam Content-Security-Policy Anda: frame-ancestors 'self' https://<studio origin>. Klik-untuk-sunting opsional dijelaskan di Pratinjau, terbitkan, dan kembalikan.

5. Segarkan halaman begitu konten diterbitkan

Buat webhook di Studio (Integrations → Webhooks) yang mengarah ke sebuah rute di situs Anda, dan simpan rahasia penandatanganannya dalam variabel lingkungan server. Verifikasi setiap permintaan sebelum bertindak atasnya; lihat Webhook untuk pemeriksaan persisnya. Lalu panggil revalidatePath untuk rute yang terdampak (atau revalidateTag('atlas')).

6. Laporkan build Anda

Saat server Anda mulai, kirim POST /deployments berisi digest bundel kontrak yang dirender build ini serta id dan versi komponen yang didukungnya. Studio kemudian menampilkan di Integrations → Website apakah situs web sinkron dengan kontrak aktif. Rilis tidak dapat masuk ke Production selama situs tidak sinkron. Detail: Delivery API.

7. Periksa hasilnya

• Halaman yang diterbitkan di Studio muncul di situs web Development Anda dan tampilannya sama seperti sebelumnya.
• Dengan ATLAS_CMS_ORIGIN diarahkan ke alamat yang salah, situs web tetap menyajikan konten bawaannya.
• Webhook dengan tanda tangan yang salah ditolak.
• Token pengiriman tidak muncul di bundel browser mana pun (cari di output .next/static Anda).
• Studio menampilkan deployment sebagai In sync.

Berikutnya: daftar periksa migrasi untuk sisa situs.