Vercel

Si tu sitio ya está desplegado en Vercel, dos reglas de reescritura en vercel.json (o next.config.js) son suficientes para servir la documentación de Jamdesk en /docs -- sin necesidad de un proxy separado ni cambios de DNS. Para la verificación de dominio personalizado, también se cubre a continuación un enfoque con Edge Middleware.

Prerrequisitos

• Un proyecto desplegado en Vercel
• Tu subdominio de Jamdesk (que se encuentra en la configuración del dashboard)

Paso 1: Actualizar vercel.json

Agrega una configuración de rewrites a tu archivo vercel.json. Si el archivo no existe, créalo en la raíz de tu proyecto:

{
  "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*"
    }
  ]
}

Las reescrituras de /_next/ y /_jd/ son necesarias para que los assets de Next.js (JS, CSS) y los recursos de Jamdesk (fuentes, imágenes, branding) se carguen correctamente.

Paso 2: Desplegar

Despliega tus cambios en Vercel:

vercel --prod

O haz push a tu repositorio Git conectado para activar un despliegue automático.

Paso 3: Verificar

Visita https://yoursite.com/docs para confirmar que tu documentación se está sirviendo correctamente.

Entendiendo la configuración

Las reglas de reescritura manejan:

1. La ruta base /docs (p. ej., yoursite.com/docs)
2. Todas las rutas anidadas (p. ej., yoursite.com/docs/getting-started)
3. Los assets estáticos de Next.js (/_next/) y los recursos de Jamdesk (/_jd/)

Agregar a reescrituras existentes

Si ya tienes reescrituras configuradas, agrega las reglas de Jamdesk a tu array existente:

{
  "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*" }
  ]
}

Usar next.config.js (proyectos Next.js)

Para proyectos Next.js, también puedes configurar las reescrituras en 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;

Solución de problemas

Verificación de dominio personalizado

Las reescrituras de Vercel funcionan haciendo proxy de las solicitudes a tu subdominio de Jamdesk (YOUR_SLUG.jamdesk.app). Esta configuración básica no requiere verificación de dominio.

Si configuraste un dominio personalizado en el dashboard de Jamdesk con la opción "Host at /docs", necesitarás usar Edge Middleware en lugar de reescrituras simples para establecer el encabezado de verificación requerido.

Cómo funciona

El middleware reenvía las solicitudes a tu subdominio de Jamdesk mientras pasa el dominio original en el encabezado X-Jamdesk-Forwarded-Host. Jamdesk usa este encabezado para:

1. Verificar tu dominio — Asegura que solo los dominios autorizados puedan servir tu documentación
2. Aplicar la configuración correcta — Usa la configuración de tu dominio desde el dashboard

Esto significa que el middleware es una configuración única. Si luego cambias tu dominio personalizado o la configuración en el dashboard de Jamdesk, el middleware no necesita actualizarse — todas las decisiones de enrutamiento se toman en el servidor.

Usar Edge Middleware

Crea un archivo middleware.ts en la raíz de tu proyecto:

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*'],
};

Cuándo usar Middleware frente a reescrituras

Si no necesitas verificación de dominio personalizado, el enfoque más simple con reescrituras es suficiente.

¿Qué sigue?