Vercel

Si votre site est déjà déployé sur Vercel, deux règles de rewrite dans vercel.json (ou next.config.js) suffisent pour servir la documentation Jamdesk à /docs -- aucun proxy séparé ni modification DNS n'est nécessaire. Pour la vérification de domaine personnalisé, une approche par Edge Middleware est également décrite ci-dessous.

Prérequis

• Un projet déployé sur Vercel
• Votre sous-domaine Jamdesk (trouvé dans les paramètres du dashboard)

Étape 1 : Mettre à jour vercel.json

Ajoutez une configuration rewrites à votre fichier vercel.json. Si le fichier n'existe pas, créez-le à la racine de votre projet :

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

Les rewrites /_next/ et /_jd/ sont nécessaires pour que les ressources Next.js (JS, CSS) et les ressources Jamdesk (polices, images, branding) se chargent correctement.

Étape 2 : Déployer

Pour déployer vos modifications sur Vercel :

vercel --prod

Ou poussez vers votre dépôt Git connecté pour déclencher un déploiement automatique.

Étape 3 : Vérifier

Visitez https://yoursite.com/docs pour confirmer que votre documentation est correctement servie.

Comprendre la configuration

Les règles de rewrite gèrent :

1. Le chemin de base /docs (par exemple, yoursite.com/docs)
2. Tous les chemins imbriqués (par exemple, yoursite.com/docs/getting-started)
3. Les ressources statiques Next.js (/_next/) et les ressources Jamdesk (/_jd/)

Ajouter à des rewrites existants

Si vous avez déjà des rewrites configurés, ajoutez les règles Jamdesk à votre tableau existant :

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

Utiliser next.config.js (projets Next.js)

Pour les projets Next.js, vous pouvez également configurer les rewrites dans next.config.js :

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

export default nextConfig;

Dépannage

Vérification de domaine personnalisé

Les rewrites Vercel fonctionnent en proxifiant les requêtes vers votre sous-domaine Jamdesk (YOUR_SLUG.jamdesk.app). Cette configuration de base ne nécessite pas de vérification de domaine.

Si vous avez configuré un domaine personnalisé dans le dashboard Jamdesk avec l'option "Host at /docs", vous devrez utiliser l'Edge Middleware plutôt que de simples rewrites pour définir l'en-tête de vérification requis.

Fonctionnement

Le middleware transfère les requêtes vers votre sous-domaine Jamdesk tout en transmettant le domaine d'origine dans l'en-tête X-Jamdesk-Forwarded-Host. Jamdesk utilise cet en-tête pour :

1. Vérifier votre domaine - S'assure que seuls les domaines autorisés peuvent servir votre documentation
2. Appliquer la configuration correcte - Utilise les paramètres de votre domaine depuis le dashboard

Cela signifie que le middleware est une configuration unique. Si vous modifiez ultérieurement votre domaine personnalisé ou votre configuration dans le dashboard Jamdesk, le middleware n'a pas besoin d'être mis à jour — toutes les décisions de routage sont prises côté serveur.

Utiliser l'Edge Middleware

Créez un fichier middleware.ts à la racine de votre projet :

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;

  // Only proxy /docs and asset paths
  if (!url.pathname.startsWith('/docs') &&
      !url.pathname.startsWith('/_next') &&
      !url.pathname.startsWith('/_jd')) {
    return NextResponse.next();
  }

  // Rewrite to Jamdesk with forwarded host header
  const destination = new URL(url.pathname + url.search, `https://${JAMDESK_HOST}`);

  // Clone headers and add the forwarded host
  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*', '/_next/:path*', '/_jd/:path*'],
};

Quand utiliser le Middleware plutôt que les Rewrites

Si vous n'avez pas besoin de la vérification de domaine personnalisé, l'approche plus simple avec les rewrites est suffisante.

Et ensuite ?