Việc gắn bảng điều khiển quản trị vào trang web của bạn là một bước đơn giản

Tại sao cần thực hiện việc này

Điều này đảm bảo trải nghiệm chỉnh sửa của bạn diễn ra liền mạch. Khi bảng điều khiển quản trị được gắn vào trang web thông qua proxy, bạn có thể chỉnh sửa trang web bằng cùng một URL và xem bản xem trước trực quan của các thay đổi theo thời gian thực. Tính năng này cũng cho phép chỉnh sửa lớp phủ, mang lại trải nghiệm người dùng tốt hơn khi chỉnh sửa trang web.

Các bước bắt buộc

Thiết lập proxy (có một số lưu ý)

Proxy là tệp proxy.ts trong dự án của bạn (trong Next.js 16; với các phiên bản Next.js cũ hơn, đây là middleware.ts). Proxy hoạt động giống như việc viết lại URL, chuyển các endpoint /admin, /api và /auth trên trang web của bạn đến CMS.

• Đối với localhost: bạn phải sử dụng tunnel (vì CMS không thể truy cập trực tiếp vào localhost)
• Hoạt động liền mạch trên các trang web đã triển khai

Thiết lập Proxy

// proxy.ts  (Next.js 16 — sử dụng middleware.ts trên các phiên bản Next.js cũ hơn)
import { createCmsProxy, cmsProxyMatcher } from 'cms-renderer/lib/proxy';
import type { NextRequest } from 'next/server';

const cmsProxy = createCmsProxy({
  // Origin của CMS admin mà proxy sẽ chuyển tiếp đến.
  upstream: process.env.ADMIN_UPSTREAM_ORIGIN ?? 'https://cms.dev.tryprofound.com',
});

export default async function proxy(request: NextRequest) {
  return cmsProxy(request);
}

export const config = {
  matcher: cmsProxyMatcher,
};

createCmsProxy trả về một trình xử lý mà bạn gọi với request đến. cmsProxyMatcher là matcher được tạo sẵn, bao phủ /admin, /api, /auth cùng các request /_next và tài nguyên tĩnh bắt nguồn từ admin — vì vậy bạn không cần tự viết mảng matcher.

Trên các phiên bản Next.js cũ hơn, hãy đặt tên tệp là middleware.ts và export trình xử lý với tên middleware thay vì export mặc định:

export async function middleware(request: NextRequest) { return cmsProxy(request); } export const config = { matcher: cmsProxyMatcher };

Cần proxy thêm các đường dẫn khác? Truyền additionalPaths: ['/my-path'] vào createCmsProxy.

Bây giờ bạn có thể truy cập /admin trên trang web để mở bảng điều khiển quản trị. Tính năng này cho phép xem trước trực tiếp.

Chỉnh sửa lớp phủ & Route xem trước

Lớp phủ và chế độ chỉnh sửa được render bởi route xem trước của bạn, không phải route production tĩnh. Admin tải trang web của bạn ở chế độ chỉnh sửa (?edit_mode=true) và request đó được phục vụ bởi ParametricRoutePreviewPage trên một route force-dynamic, route này tự chuyển tiếp searchParams cho bạn:

// app/cms-preview_/[...slug]/page.tsx
import { ParametricRoutePreviewPage } from 'cms-renderer/lib/renderer';
import { registry } from '@/lib/registry';
import { cmsConfig } from '@/lib/cms-config';

// Render động — cho phép sử dụng searchParams cho edit_mode
export const dynamic = 'force-dynamic';

interface PageProps {
  params: Promise<{ slug: string[] }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
}

export default async function PreviewPage({ params, searchParams }: PageProps) {
  const { slug } = await params;

  return (
    <ParametricRoutePreviewPage
      registry={registry}
      apiKey={cmsConfig.apiKey}
      websiteId={cmsConfig.websiteId}
      cmsUrl={cmsConfig.cmsUrl}
      params={Promise.resolve({ slug })}
      searchParams={searchParams}
    />
  );
}

Bạn không cần kết nối lớp phủ theo cách thủ công — chỉ cần truyền searchParams vào trình render bản xem trước là đủ. Route production của bạn (`app/[...slug]/page.tsx) vẫn giữ trạng thái tĩnh với ParametricRoutePage và không cần searchParams`. Xem Thiết lập dự án CMS Hybrid để biết cách thiết lập đầy đủ hai route.

Cách xác minh

1. Truy cập /admin trên trang web của bạn
2. Hệ thống sẽ yêu cầu bạn đăng nhập và ngay lập tức mở bảng điều khiển quản trị CMS
3. Mở trang web của bạn từ admin và xác nhận rằng lớp phủ/bản xem trước trực tiếp hoạt động tự động

Lớp phủ và bản xem trước trực tiếp sẽ tự động hoạt động.

Các bước tiếp theo

Thiết lập đầy đủ các route production + xem trước trong Thiết lập dự án CMS Hybrid.