Vercel

Se il tuo sito è distribuito su Vercel, puoi pubblicare la documentazione Jamdesk in /docs sul tuo dominio. Puoi configurarlo in due modi, entrambi con lo stesso risultato:

• Opzione A: rewrite in vercel.json — nessun codice, funziona con qualsiasi framework. La maggior parte dei progetti dovrebbe iniziare da qui.
• Opzione B: Edge Middleware — per i siti che eseguono già Edge Middleware e vogliono inserire Jamdesk nello stesso file.

Prerequisiti

• Un progetto distribuito su Vercel
• Il tuo sottodominio Jamdesk (disponibile nelle impostazioni del dashboard), con Host at a subpath abilitato
• Il tuo dominio personalizzato registrato e verificato nel dashboard

Opzione A: rewrite in vercel.json

Una rewrite può modificare la destinazione di una richiesta, ma non può aggiungere un'intestazione alla richiesta; per questo ogni destinazione include un indicatore pubblico, ?jd_proxy=1, che informa Jamdesk che la richiesta è passata attraverso il tuo proxy. Jamdesk lo rimuove prima del rendering; i visitatori non lo vedono mai.

Crea o modifica vercel.json nella radice del progetto, sostituendo YOUR_SLUG con il tuo sottodominio Jamdesk:

{
  "rewrites": [
    { "source": "/docs", "destination": "https://YOUR_SLUG.jamdesk.app/docs?jd_proxy=1" },
    { "source": "/docs/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/docs/:path*?jd_proxy=1" },
    { "source": "/_next/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/_next/:path*" },
    { "source": "/_jd/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/_jd/:path*?jd_proxy=1" }
  ]
}

/_next/:path* non richiede alcun indicatore: è un percorso per risorse statiche che Jamdesk non limita mai. Se il tuo sito non è un'app Next.js, non contiene file /_next/ propri, quindi la rewrite è comunque corretta: ogni richiesta a quel percorso passa semplicemente a Jamdesk.

Le stesse quattro regole funzionano in next.config.js per i progetti Next.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  async rewrites() {
    return [
      { source: "/docs", destination: "https://YOUR_SLUG.jamdesk.app/docs?jd_proxy=1" },
      { source: "/docs/:path*", destination: "https://YOUR_SLUG.jamdesk.app/docs/:path*?jd_proxy=1" },
      { source: "/_next/:path*", destination: "https://YOUR_SLUG.jamdesk.app/_next/:path*" },
      { source: "/_jd/:path*", destination: "https://YOUR_SLUG.jamdesk.app/_jd/:path*?jd_proxy=1" },
    ];
  },
};

export default nextConfig;

Inoltra anche i file nella radice

robots.txt, sitemap.xml, llms.txt e llms-full.txt si trovano nella radice del dominio, al di fuori di /docs: senza di essi, i motori di ricerca e gli agenti AI non possono scoprire la tua documentazione. Se Jamdesk gestisce la radice del dominio, aggiungi altre quattro regole:

{
  "rewrites": [
    { "source": "/robots.txt", "destination": "https://YOUR_SLUG.jamdesk.app/robots.txt?jd_proxy=1" },
    { "source": "/sitemap.xml", "destination": "https://YOUR_SLUG.jamdesk.app/sitemap.xml?jd_proxy=1" },
    { "source": "/llms.txt", "destination": "https://YOUR_SLUG.jamdesk.app/llms.txt?jd_proxy=1" },
    { "source": "/llms-full.txt", "destination": "https://YOUR_SLUG.jamdesk.app/llms-full.txt?jd_proxy=1" }
  ]
}

Esegui il deploy e verifica

Esegui il deploy con vercel --prod (oppure esegui il push nel repository Git connesso), quindi apri https://yoursite.com/docs e visualizza il codice sorgente della pagina. Verifica due elementi:

1. <link rel="canonical"> punta al tuo dominio, non a YOUR_SLUG.jamdesk.app
2. Non è presente <meta name="robots" content="noindex">

Se uno dei due elementi non è corretto, in una rewrite manca l'indicatore ?jd_proxy=1: consulta Perché il marker è importante.

Opzione B: Edge Middleware

Se esegui già Edge Middleware, imposta lì l'intestazione della richiesta X-Jamdesk-Forwarded-Host invece di usare l'indicatore. I due segnali sono equivalenti: scegli questa opzione solo se preferisci mantenere la logica di routing nel codice che già gestisci.

Crea un file middleware.ts nella radice del progetto, sostituendo YOUR_SLUG con il tuo sottodominio Jamdesk:

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

const JAMDESK_HOST = 'YOUR_SLUG.jamdesk.app';

export function middleware(request: NextRequest) {
  const url = request.nextUrl;
  const destination = new URL(url.pathname + url.search, `https://${JAMDESK_HOST}`);

  // Clone headers and tell Jamdesk which domain the visitor actually used.
  const headers = new Headers(request.headers);
  headers.set('X-Jamdesk-Forwarded-Host', url.hostname);

  return NextResponse.rewrite(destination, {
    request: { headers },
  });
}

export const config = {
  matcher: ['/docs', '/docs/:path*', '/_jd/:path*'],
};

Il file deve chiamarsi middleware.ts e deve esportare una funzione denominata middleware. Next.js 16 suggerisce di rinominarlo in proxy.ts, ma la produzione Vercel non esegue ancora proxy.ts: rinominarlo lo disabilita senza alcun avviso evidente.

Instrada le risorse e i file nella radice in vercel.json

Le pagine Jamdesk caricano i propri bundle da /_next/, mentre i file nella radice, come robots.txt, si trovano al di fuori del matcher precedente. Instrada entrambi con le rewrite: le rewrite vengono eseguite dopo il controllo del file system, quindi l'output del tuo build ha sempre la precedenza e solo le richieste che il tuo sito non può gestire passano a Jamdesk:

{
  "rewrites": [
    { "source": "/_next/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/_next/:path*" },
    { "source": "/robots.txt", "destination": "https://YOUR_SLUG.jamdesk.app/robots.txt?jd_proxy=1" },
    { "source": "/sitemap.xml", "destination": "https://YOUR_SLUG.jamdesk.app/sitemap.xml?jd_proxy=1" },
    { "source": "/llms.txt", "destination": "https://YOUR_SLUG.jamdesk.app/llms.txt?jd_proxy=1" },
    { "source": "/llms-full.txt", "destination": "https://YOUR_SLUG.jamdesk.app/llms-full.txt?jd_proxy=1" }
  ]
}

I file nella radice includono ?jd_proxy=1 perché il middleware non viene eseguito su di essi e una rewrite non può impostare l'intestazione. Aggiungili solo se Jamdesk gestisce la radice del dominio; se il tuo sito pubblica il proprio robots.txt o sitemap.xml, uniscili.

Esegui il deploy e verifica

Esegui il deploy con vercel --prod (oppure esegui il push nel repository Git connesso), quindi apri https://yoursite.com/docs e visualizza il codice sorgente della pagina. Verifica due elementi:

1. <link rel="canonical"> punta al tuo dominio, non a YOUR_SLUG.jamdesk.app
2. Non è presente <meta name="robots" content="noindex">

Se uno dei due elementi non è corretto, l'intestazione X-Jamdesk-Forwarded-Host non raggiunge Jamdesk: verifica che /docs sia incluso nel matcher.

Perché il marker è importante

Jamdesk ha bisogno di un segnale che indichi che una richiesta è arrivata attraverso il tuo proxy, anziché direttamente dal tuo sottodominio *.jamdesk.app. L'indicatore ?jd_proxy=1 e l'intestazione X-Jamdesk-Forwarded-Host trasmettono entrambi questo segnale e Jamdesk li considera equivalenti. Ognuno dei due conferma il tuo dominio registrato, indirizza verso di esso i link canonical, Open Graph e sitemap e consente a Solo dominio personalizzato di distinguere il traffico del proxy dagli accessi diretti.

L'assenza del segnale non genera errori evidenti: le pagine continuano a essere visualizzate, ma con noindex e canonical del sottodominio se non è registrato alcun dominio personalizzato, oppure con un controllo Solo dominio personalizzato non riuscito se ne è registrato uno. Un errore 403 è il problema opposto: il segnale è presente, ma indica un dominio che non è registrato e attivo per questo progetto.

Risoluzione dei problemi

Qual è il prossimo passo?