Jamdesk Documentation logo

Cloudflare Workers

Redirige las solicitudes de /docs a través de un Cloudflare Worker a tu sitio de documentación Jamdesk. Configuración del Worker, rutas y caché.

Un Cloudflare Worker intercepta las solicitudes en /docs de tu dominio, las reescribe hacia tu subdominio de Jamdesk y devuelve la respuesta, todo en el edge sin necesidad de un servidor de origen. Puedes generar el Worker automáticamente con npx jamdesk deploy-proxy cloudflare o configurarlo manualmente a continuación.

Cómo funciona

El Worker reenvía las solicitudes a tu subdominio de Jamdesk y envía tu dominio en el encabezado X-Jamdesk-Forwarded-Host, que Jamdesk usa para verificar el dominio y aplicar su configuración. Es una configuración única: si más adelante cambias tu dominio o la configuración en el dashboard, no es necesario actualizar el Worker.

Requisitos previos

  • Una cuenta de Cloudflare con tu dominio configurado
  • Wrangler CLI v3.0+ instalado
  • Tu subdominio de Jamdesk (lo encuentras en la configuración del dashboard)
  • Tu dominio personalizado añadido a tu proyecto en el dashboard de Jamdesk (el Worker devuelve un 403 hasta que el dominio esté registrado y verificado)

Configuración rápida con la CLI

La forma más rápida de configurar tu Cloudflare Worker:

npx jamdesk deploy-proxy cloudflare

Este comando interactivo hará lo siguiente:

  1. Comprobar que wrangler 3.0+ esté instalado
  2. Verificar tu cuenta de Cloudflare y mostrar los dominios disponibles
  3. Resolver tu subdominio de Jamdesk a partir del proyecto vinculado en docs.json
  4. Permitirte seleccionar tu dominio de destino entre tus zonas de Cloudflare
  5. Generar todos los archivos necesarios
  6. Desplegar a Cloudflare de forma opcional

Si tienes acceso a varias cuentas de Cloudflare (algo común en agencias o equipos), la CLI te pedirá elegir una antes de seleccionar la zona. Elige la cuenta propietaria del dominio al que vas a desplegar: las rutas de Workers solo se pueden crear para dominios de la cuenta seleccionada.

Despliegue con CI o scripts

Para CI o scripts, usa flags para omitir las preguntas:

jamdesk deploy-proxy cloudflare --slug myproject --domain example.com --skip-deploy --yes

Con --yes la CLI no puede preguntar, así que necesita conocer tu subdominio. Lo obtiene del proyecto vinculado en docs.json; si falta ese vínculo (ejecuta jamdesk deploy una vez para añadirlo), pasa --slug explícitamente, o el comando se detiene en lugar de adivinar.

OptionDescription
--slugTu subdominio de Jamdesk, la X en X.jamdesk.app (omite la detección automática)
--domainDominio de destino (p. ej., yoursite.com)
--pathPrefijo de ruta (por defecto: /docs)
--output-dirDirectorio de salida (por defecto: cloudflare-worker/)
--skip-deployGenera solo los archivos, sin desplegar
--forceSobrescribe el directorio existente
--yesOmite todas las preguntas (modo CI)

Si prefieres la configuración manual, continúa con los siguientes pasos.

Configuración manual

Paso 1: Crear un Worker

Crea un nuevo directorio para tu Worker e inicialízalo:

mkdir docs-proxy && cd docs-proxy
npm init -y

Paso 2: Añadir el código del Worker

Crea index.js con el siguiente código:

index.js
const JAMDESK_HOST = "YOUR_SLUG.jamdesk.app";

// Paths that should be proxied to Jamdesk
const PROXY_PATHS = [
  "/docs",    // Documentation pages
  "/_next/",  // Next.js static assets (JS, CSS)
  "/_jd/",    // All Jamdesk assets (images, fonts, branding, analytics)
];

function shouldProxy(pathname) {
  return PROXY_PATHS.some(prefix => {
    // For the docs path, require exact match or prefix with slash (not /docs.json)
    if (prefix === "/docs") {
      return pathname === "/docs" || pathname.startsWith("/docs/");
    }
    return pathname.startsWith(prefix);
  });
}

export default {
  async fetch(request) {
    const url = new URL(request.url);

    // Only proxy docs-related paths
    if (!shouldProxy(url.pathname)) {
      return fetch(request);
    }

    // Rewrite the request to Jamdesk
    const proxyUrl = new URL(request.url);
    proxyUrl.hostname = JAMDESK_HOST;

    // Clone headers and add proxy headers
    const headers = new Headers(request.headers);
    headers.set("Host", JAMDESK_HOST);
    headers.set("X-Forwarded-Host", url.hostname);
    headers.set("X-Forwarded-Proto", "https");
    // Custom header for domain verification (Vercel strips standard forwarding headers)
    headers.set("X-Jamdesk-Forwarded-Host", url.hostname);

    // Don't follow redirects; let the browser handle them so the URL updates.
    // Without this, redirects happen internally and the browser URL doesn't change,
    // which causes the sidebar to mis-highlight the active page.
    const proxyRequest = new Request(proxyUrl, {
      method: request.method,
      headers,
      body: request.body,
      redirect: "manual",
    });

    // Cache all content types at Cloudflare edge (CF doesn't cache HTML by default).
    // Cache duration is controlled by upstream Cache-Control headers.
    // Never cache redirects or errors; they must always hit origin.
    return fetch(proxyRequest, {
      cf: {
        cacheEverything: true,
        cacheTtlByStatus: { "300-399": 0, "500-599": 0 },
      },
    });
  },
};

Reemplaza YOUR_SLUG por tu subdominio real de Jamdesk (por ejemplo, acme si tu documentación está en acme.jamdesk.app).

El encabezado X-Jamdesk-Forwarded-Host es obligatorio, y si falta, el fallo es silencioso: las solicitudes siguen teniendo éxito, pero las páginas se sirven con noindex y enlaces canónicos que apuntan a YOUR_SLUG.jamdesk.app en lugar de tu dominio, por lo que los motores de búsqueda nunca indexan tu documentación. Un 403 es el problema opuesto: el encabezado sí está presente, pero indica un dominio que no está registrado ni activo para este proyecto.

Paso 3: Configurar wrangler.toml

Crea wrangler.toml para configurar tu Worker:

wrangler.toml
name = "docs-proxy"
main = "index.js"
compatibility_date = "2024-01-01"

# Single catch-all route; the worker handles path filtering internally
routes = [
  { pattern = "yoursite.com/*", zone_name = "yoursite.com" },
]

Si tu sitio también recibe tráfico en www.yoursite.com, añade una segunda ruta para que el Worker gestione ambas:

routes = [
  { pattern = "yoursite.com/*", zone_name = "yoursite.com" },
  { pattern = "www.yoursite.com/*", zone_name = "yoursite.com" },
]

Paso 4: Desplegar

Despliega tu Worker en Cloudflare:

npx wrangler deploy

Paso 5: Verificar

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

Solución de problemas

La CLI muestra tus dominios disponibles antes de seleccionar la zona. Si ves "No domains found":

  1. Verifica que iniciaste sesión en la cuenta de Cloudflare correcta
  2. Comprueba que tu dominio esté añadido y activo en el dashboard de Cloudflare
  3. Vuelve a ejecutar la CLI y selecciona "No" cuando te pregunte si deseas continuar con la cuenta actual, para cambiar de cuenta

Si tienes varias cuentas de Cloudflare:

  1. Ejecuta jamdesk deploy-proxy cloudflare
  2. Cuando se te pida seleccionar una cuenta, elige la que tiene tu dominio
  3. Si necesitas iniciar sesión con una cuenta completamente distinta, selecciona "Switch to different login"
  4. La CLI cerrará tu sesión y te pedirá iniciar sesión con las credenciales correctas

Este error significa que la zona seleccionada no coincide con tu cuenta de Cloudflare. Puede deberse a:

  • Seleccionaste una zona que pertenece a otra cuenta
  • La zona fue eliminada de Cloudflare

Solución: vuelve a ejecutar la CLI y selecciona la zona correcta de la lista, o cambia a la cuenta propietaria de la zona.

Asegúrate de que tu patrón de ruta use un catch-all: yoursite.com/* (no solo yoursite.com/docs*). La función interna shouldProxy() del Worker se encarga del filtrado de rutas.

Dos causas comunes:

  1. El Worker no se está ejecutando. Asegúrate de que tu registro DNS esté configurado como Proxied (nube naranja) en Cloudflare. Los Workers solo se ejecutan en registros proxied.
  2. Falta el encabezado X-Forwarded-Host. El Worker debe establecer este encabezado para que Jamdesk genere correctamente las URLs de los recursos.

Si ves "Domain is not authorized to serve this content":

  1. Verifica que tu dominio esté registrado en el dashboard de Jamdesk
  2. Completa la verificación DNS (registro TXT) de tu dominio
  3. Asegúrate de que el encabezado X-Jamdesk-Forwarded-Host esté configurado en el código de tu Worker
  4. Comprueba que tu dominio esté asignado al proyecto correcto

El dominio debe estar verificado antes de que el Worker pueda servir la documentación.

Los Workers solo se ejecutan en registros DNS proxied (nube naranja). Si tu registro A está configurado como "DNS only" (nube gris), las solicitudes van directamente al origen y omiten el Worker por completo.

Solución: cambia el registro A a proxied (nube naranja) en el DNS de Cloudflare. Lo mismo aplica a los subdominios: cualquier registro con una ruta de Worker debe estar en modo proxied.

Jamdesk verifica la propiedad leyendo directamente los valores de tus registros DNS. El proxy de Cloudflare (nube naranja) enmascara estos valores, por lo que la verificación no puede completarse.

Solución:

  1. Configura el registro DNS como DNS only (nube gris)
  2. Espera a que se complete la verificación (el estado cambia a active en el dashboard)
  3. Vuelve a Proxied (nube naranja) para que el Worker funcione

Resumen: nube gris para verificar → nube naranja para servir.

Jamdesk sirve el HTML de la documentación con Cache-Control: no-store, por lo que Cloudflare no almacena en caché las páginas en el edge (cf-cache-status: BYPASS). Cada solicitud renderiza la versión actual, y los cambios publicados aparecen de inmediato, sin demora de caché.

Los recursos estáticos bajo /_next/ y /_jd/ (JavaScript, CSS, fuentes, imágenes) se sirven con encabezados de caché immutable de larga duración, por lo que Cloudflare los almacena en caché en el edge. Sus nombres de archivo llevan un hash del contenido, así que cada build genera nuevas URLs y los recursos actualizados se recogen automáticamente. No es necesario purgar la caché.

cacheEverything: true permite que Cloudflare almacene en caché esos recursos estáticos en la ruta proxied; no anula el no-store del HTML. Para limpiar la caché del edge manualmente, usa Purge Cache de Cloudflare (Caching → Configuration → Purge Everything).

La CLI requiere wrangler 3.0+. Actualízala con:

npm install -g wrangler@latest

¿Qué sigue?

Solo dominio personalizado

Evita que tu subdominio responda directamente

Dominios personalizados

Verifica el DNS y soluciona problemas

Alojamiento en subruta

Sirve la documentación en /docs