Vercel

Servi la tua documentazione Jamdesk su /docs nel tuo dominio distribuito su Vercel. Scegli una delle due configurazioni. Producono lo stesso risultato.

• Opzione A: riscritture in vercel.json: nessun codice, qualsiasi framework. Inizia da qui.
• Opzione B: Edge Middleware: per i siti che già usano Edge Middleware e vogliono Jamdesk nello stesso file.

Prerequisiti

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

Opzione A: rewrite in vercel.json

Una riscrittura può cambiare la destinazione di una richiesta, ma non può aggiungere un header di richiesta. Per questo ogni destinazione include un marcatore pubblico, ?jd_proxy=1. Il marcatore indica a Jamdesk che la richiesta è passata dal tuo proxy. Jamdesk lo rimuove prima del rendering, quindi i tuoi 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 il marcatore. È un percorso di asset statici che Jamdesk non filtra mai. Un sito che non è un'app Next.js non ha file propri in /_next/: ogni richiesta sotto quel percorso ricade su 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. Motori di ricerca e agenti AI ne hanno bisogno per trovare la tua documentazione. Se Jamdesk gestisce la radice del tuo 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 (o fai push sul repository Git collegato). Apri https://yoursite.com/docs e visualizza il sorgente della pagina. Controlla due cose:

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

Se una delle due è sbagliata, a una riscrittura manca il marcatore ?jd_proxy=1. Vedi Perché il marcatore è importante.

Opzione B: Edge Middleware

Imposta l'header di richiesta X-Jamdesk-Forwarded-Host nel tuo Edge Middleware, invece di usare il marcatore. I due segnali sono equivalenti. Scegli questa opzione se vuoi mantenere la logica di routing nel codice che già gestisci.

Crea un file middleware.ts nella radice del progetto. Sostituisci 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*'],
};

Chiama il file middleware.ts ed esporta una funzione chiamata middleware. Next.js 16 suggerisce di rinominarlo in proxy.ts. In produzione Vercel non invoca ancora proxy.ts: rinominarlo disabiliterebbe il middleware senza avvisi.

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

Le pagine di Jamdesk caricano i propri bundle da /_next/. File della radice come robots.txt si trovano fuori dal matcher sopra. Instradali entrambi con delle riscritture. Le riscritture vengono eseguite dopo il controllo del filesystem: vincono gli output di build del tuo sito, e solo le richieste che il tuo sito non può servire ricadono su 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 della radice includono ?jd_proxy=1. Il middleware non viene eseguito su di essi e una riscrittura non può impostare l'header. Aggiungili solo se Jamdesk gestisce la radice del tuo dominio. Se il tuo sito serve un proprio robots.txt o sitemap.xml, uniscili invece di sostituirli.

Esegui il deploy e verifica

Esegui il deploy con vercel --prod (o fai push sul repository Git collegato). Apri https://yoursite.com/docs e visualizza il sorgente della pagina. Controlla due cose:

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

Se una delle due è sbagliata, l'header X-Jamdesk-Forwarded-Host non sta raggiungendo Jamdesk. Verifica che /docs sia nel matcher.

Perché il marker è importante

Jamdesk ha bisogno di un segnale che indichi che una richiesta è arrivata tramite il tuo proxy, e non come accesso diretto al tuo sottodominio *.jamdesk.app. Il marcatore ?jd_proxy=1 e l'header X-Jamdesk-Forwarded-Host trasportano questo segnale. Jamdesk li tratta come equivalenti. Entrambi fanno tre cose:

• Confermano il tuo dominio registrato
• Fanno puntare canonical, Open Graph e link della sitemap a quel dominio
• Permettono a Solo dominio personalizzato di distinguere il traffico proxy dagli accessi diretti

Se manca il segnale, il problema passa inosservato. Le pagine vengono comunque renderizzate. Senza un dominio personalizzato registrato, portano noindex e canonical del sottodominio. Con un dominio personalizzato registrato, il controllo di Solo dominio personalizzato fallisce. Un 403 significa che il segnale è presente ma indica un dominio non registrato e attivo per questo progetto.

Risoluzione dei problemi

Qual è il prossimo passo?