Collegare il pannello amministrativo al tuo sito web è un'operazione semplice

Perché è necessario

Questo garantisce un'esperienza di modifica fluida. Con il pannello amministrativo collegato al tuo sito web tramite un proxy, puoi modificare il sito allo stesso URL e visualizzare in tempo reale un'anteprima visiva delle modifiche. Inoltre, abilita la modifica tramite overlay, che offre una migliore esperienza utente durante la modifica della pagina web.

Passaggi richiesti

Configurazione del proxy (ci sono alcune limitazioni)

Il proxy è un file proxy.ts nel tuo progetto (in Next.js 16; nelle versioni precedenti di Next.js è middleware.ts). Si comporta come una riscrittura dell'URL, indirizzando gli endpoint /admin, /api e /auth del tuo sito web al CMS.

• Per localhost: devi utilizzare un tunnel (poiché il CMS non può accedere direttamente a localhost)
• Funziona senza problemi sui siti web distribuiti

Configurazione del proxy

// proxy.ts  (Next.js 16 — usa middleware.ts nelle versioni precedenti di Next.js)
import { createCmsProxy, cmsProxyMatcher } from 'cms-renderer/lib/proxy';
import type { NextRequest } from 'next/server';

const cmsProxy = createCmsProxy({
  // L'origine dell'amministrazione CMS a cui effettuare il proxy.
  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 restituisce un gestore che richiami con la richiesta in arrivo. cmsProxyMatcher è il matcher già pronto che copre /admin, /api, /auth e le richieste /_next e delle risorse statiche originate dall'amministrazione, così non devi scrivere manualmente l'array del matcher.

Nelle versioni precedenti di Next.js, assegna al file il nome middleware.ts ed esporta il gestore come middleware invece di utilizzare l'esportazione predefinita:

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

Devi effettuare il proxy di percorsi aggiuntivi? Passa additionalPaths: ['/my-path'] a createCmsProxy.

Ora puoi visitare /admin sul tuo sito per accedere al pannello amministrativo. Questo abilita l'anteprima in tempo reale.

Modifica tramite overlay e route di anteprima

Gli overlay e la modalità di modifica vengono renderizzati dalla route di anteprima, non dalla route statica di produzione. L'amministrazione carica il tuo sito in modalità di modifica (?edit_mode=true) e questa richiesta viene gestita da ParametricRoutePreviewPage su una route force-dynamic, che inoltra automaticamente 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';

// Rendering dinamico — consente l'utilizzo di searchParams per 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}
    />
  );
}

Non devi configurare manualmente gli overlay: è sufficiente passare searchParams al renderer di anteprima. La tua route di produzione (app/[...slug]/page.tsx) rimane statica con ParametricRoutePage e non richiede searchParams. Consulta Configurazione di un progetto CMS ibrido per la configurazione completa delle due route.

Come verificare

1. Vai su /admin nel tuo sito web
2. Dovrebbe chiederti di effettuare l'accesso e aprire immediatamente il pannello amministrativo del CMS
3. Apri il tuo sito dall'amministrazione e verifica che gli overlay e l'anteprima in tempo reale funzionino automaticamente

Gli overlay e le anteprime in tempo reale dovrebbero funzionare automaticamente.

Passaggi successivi

Configura le route complete di produzione e anteprima in Configurazione di un progetto CMS ibrido.