웹사이트에 어드민 패널을 연결하는 것은 간단한 단계입니다

이것이 필요한 이유

이렇게 하면 편집 환경이 원활해집니다. 프록시를 통해 어드민 패널을 웹사이트에 연결하면 동일한 URL에서 웹사이트를 편집하고 변경 사항을 실시간으로 시각적으로 미리 볼 수 있습니다. 또한 웹페이지를 더 편리하게 편집할 수 있는 오버레이 편집 기능도 사용할 수 있습니다.

필수 단계

프록시 설정 (몇 가지 주의사항이 있습니다)

프록시는 프로젝트에 있는 proxy.ts 파일입니다(Next.js 16에서는 사용하며, 이전 버전의 Next.js에서는 middleware.ts입니다). URL 재작성처럼 작동하여 웹사이트의 /admin, /api, /auth 엔드포인트를 CMS로 연결합니다.

• localhost의 경우: 터널을 사용해야 합니다(CMS가 localhost에 직접 액세스할 수 없기 때문입니다)
• 배포된 웹사이트에서는 원활하게 작동합니다

프록시 설정

// proxy.ts  (Next.js 16 — 이전 버전의 Next.js에서는 middleware.ts 사용)
import { createCmsProxy, cmsProxyMatcher } from 'cms-renderer/lib/proxy';
import type { NextRequest } from 'next/server';

const cmsProxy = createCmsProxy({
  // 프록시 대상 CMS 어드민 오리진입니다.
  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는 수신 요청과 함께 호출하는 핸들러를 반환합니다. cmsProxyMatcher는 /admin, /api, /auth와 어드민에서 시작된 /_next 및 정적 에셋 요청을 포함하는 즉시 사용 가능한 매처이므로, 매처 배열을 직접 작성할 필요가 없습니다.

이전 버전의 Next.js에서는 파일 이름을 middleware.ts로 지정하고 기본 내보내기 대신 핸들러를 middleware로 내보내세요:

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

추가 경로를 프록시해야 하나요? createCmsProxy에 additionalPaths: ['/my-path']를 전달하세요.

이제 사이트에서 /admin으로 이동하여 어드민 패널에 액세스할 수 있습니다. 이를 통해 라이브 미리보기가 활성화됩니다.

오버레이 편집 및 미리보기 라우트

오버레이와 편집 모드는 정적 프로덕션 라우트가 아니라 미리보기 라우트에서 렌더링됩니다. 어드민은 사이트를 편집 모드(?edit_mode=true)로 로드하며, 이 요청은 force-dynamic 라우트의 ParametricRoutePreviewPage에서 처리되고 searchParams를 자동으로 전달합니다.

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

// 동적 렌더링 — edit_mode에 searchParams를 사용할 수 있도록 합니다
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}
    />
  );
}

오버레이를 수동으로 연결할 필요는 없습니다. 미리보기 렌더러에 searchParams를 전달하는 것만으로 충분합니다. 프로덕션 라우트(`app/[...slug]/page.tsx)는 ParametricRoutePage를 사용하여 정적으로 유지되며 searchParams`가 필요하지 않습니다. 전체 2개 라우트 설정은 하이브리드 CMS 프로젝트 설정을 참조하세요.

확인 방법

1. 웹사이트에서 /admin으로 이동합니다
2. 로그인하라는 메시지가 표시되고 즉시 CMS 어드민 패널이 열려야 합니다
3. 어드민에서 사이트를 열고 오버레이/라이브 미리보기가 자동으로 작동하는지 확인합니다

오버레이와 라이브 미리보기는 자동으로 작동해야 합니다.

다음 단계

하이브리드 CMS 프로젝트 설정에서 전체 프로덕션 및 미리보기 라우트를 설정하세요.