ربط موقع Next.js

يربط هذا الدليل موقع Next.js (App Router) حاليًا ببيئة التطوير في Atlas. لا يتغير شيء في موقعك العام إلى أن تنشر الشيفرة بنفسك.

ملاحظة

يوفر Studio الخطوات نفسها مع قيمك الفعلية (Guides → Connect the website)، بما في ذلك موجّهات جاهزة لوكيل ذكاء اصطناعي للبرمجة.

قبل أن تبدأ

• موقع في 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

أبقِ الرمز على الخادم

لا تضف إليه البادئة NEXT_PUBLIC_ أبدًا، ولا ترسله إلى المتصفح، ولا ترفعه إلى المستودع. أي شخص يملك الرمز يستطيع قراءة المحتوى المنشور لتلك البيئة.

2. أضف عميلًا صغيرًا للخادم فقط

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

يعيد العميل القيمة null عندما يتعذّر الوصول إلى Atlas. وهذا ما يجعل المحتوى الاحتياطي يعمل.

3. اعرض صفحة من أقسامها

تعيد نقطة النهاية pages الصفحة المنشورة لمسار ما. تحمل document.regions الأقسام بالترتيب؛ ويسمّي كل قسم أحد مكوّنات عقدك ويحمل قيم حقوله.

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 كل component.id (مثل acme.home.hero) في عقدك بمكوّن React الحالي لديك. اعرض قيم الحقول كنص أو عبر مكوّناتك. لا تمرّر محتوى النظام إلى dangerouslySetInnerHTML أبدًا.

تستمر مساراتك المكتوبة يدويًا في العمل بجانب هذا المسار الشامل. وأنت من يقرر أي المسارات يديرها Atlas.

4. أضف معاينة المسودات

يفتح الزر Preview on website في Studio الرابط 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، اسمح لـ Studio في Content-Security-Policy لديك: frame-ancestors 'self' https://<studio origin>. يُشرح التحرير بالنقر الاختياري في المعاينة والنشر والتراجع.

5. حدّث الصفحات لحظة نشر المحتوى

أنشئ webhook في Studio (Integrations → Webhooks) يشير إلى مسار في موقعك، وخزّن سرّ توقيعه في متغير بيئة على الخادم. تحقق من كل طلب قبل التصرف بناءً عليه؛ انظر Webhooks للاطلاع على الفحص الدقيق. ثم استدعِ revalidatePath للمسارات المتأثرة (أو revalidateTag('atlas')).

6. أبلغ عن بنائك

عند بدء تشغيل خادمك، أرسل POST /deployments مع بصمة حزمة العقد التي يعرضها هذا البناء ومعرّفات المكوّنات وإصداراتها التي يدعمها. يعرض Studio عندئذٍ تحت Integrations → Website ما إذا كان الموقع متزامنًا مع العقد الفعّال. لا يمكن لإصدار أن ينتقل إلى الإنتاج بينما الموقع غير متزامن. التفاصيل: Delivery API.

7. تحقق منه

• تظهر الصفحة المنشورة في Studio على موقع التطوير وتبدو كما كانت من قبل.
• عند توجيه ATLAS_CMS_ORIGIN إلى عنوان خاطئ، يواصل الموقع تقديم محتواه المضمّن.
• يُرفض webhook ذو توقيع خاطئ.
• لا يظهر رمز التسليم في أي حزمة متصفح (ابحث في مخرجات .next/static).
• يعرض Studio عملية النشر على أنها In sync.

التالي: قائمة فحص الانتقال لبقية الموقع.