Jamdesk Documentation logo

Cloudflare Workers

Acheminez les requêtes /docs vers votre site de documentation Jamdesk via un Cloudflare Worker. Configuration, routes et cache.

Un Cloudflare Worker intercepte les requêtes sur /docs de votre domaine, les réécrit vers votre sous-domaine Jamdesk, puis renvoie la réponse, le tout en périphérie (edge), sans serveur d'origine requis. Vous pouvez générer automatiquement le Worker avec npx jamdesk deploy-proxy cloudflare ou le configurer manuellement ci-dessous.

Fonctionnement

Le Worker transmet les requêtes vers votre sous-domaine Jamdesk et inclut votre domaine dans l'en-tête X-Jamdesk-Forwarded-Host, que Jamdesk utilise pour vérifier le domaine et appliquer ses paramètres. Il s'agit d'une configuration unique — si vous modifiez ultérieurement votre domaine ou votre configuration dans le dashboard, le Worker n'a pas besoin d'être mis à jour.

Prérequis

  • Un compte Cloudflare avec votre domaine configuré
  • Wrangler CLI v3.0+ installé
  • Votre sous-domaine Jamdesk (disponible dans les paramètres du dashboard)
  • Votre domaine personnalisé ajouté à votre projet dans le dashboard Jamdesk (le Worker renvoie une erreur 403 tant que le domaine n'est pas enregistré et vérifié)

Configuration rapide avec la CLI

Le moyen le plus rapide de configurer votre Cloudflare Worker :

npx jamdesk deploy-proxy cloudflare

Cette commande interactive va :

  1. Vérifier que wrangler 3.0+ est installé
  2. Vérifier votre compte Cloudflare et afficher les domaines disponibles
  3. Résoudre votre sous-domaine Jamdesk à partir du projet lié dans docs.json
  4. Vous permettre de sélectionner votre domaine cible parmi vos zones Cloudflare
  5. Générer tous les fichiers requis
  6. Déployer sur Cloudflare (facultatif)

Si vous avez accès à plusieurs comptes Cloudflare (cas fréquent pour les agences ou les équipes), la CLI vous invite à en choisir un avant la sélection de la zone. Choisissez le compte propriétaire du domaine sur lequel vous déployez — les routes Workers ne peuvent être créées que pour des domaines appartenant au compte sélectionné.

Déploiement CI/scripté

Pour un déploiement CI/scripté, utilisez des options pour ignorer les invites :

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

Avec --yes, la CLI ne peut pas afficher d'invites, elle doit donc connaître votre sous-domaine à l'avance. Elle le lit à partir du projet lié dans docs.json ; si ce lien est absent (exécutez jamdesk deploy une fois pour l'ajouter), passez --slug explicitement, sinon la commande s'arrête plutôt que de deviner.

OptionDescription
--slugVotre sous-domaine Jamdesk, le X dans X.jamdesk.app (ignore la détection automatique)
--domainDomaine cible (ex. : yoursite.com)
--pathPréfixe de chemin (par défaut : /docs)
--output-dirRépertoire de sortie (par défaut : cloudflare-worker/)
--skip-deployGénère uniquement les fichiers, sans déployer
--forceÉcrase le répertoire existant
--yesIgnore toutes les invites (mode CI)

Si vous préférez une configuration manuelle, poursuivez avec les étapes ci-dessous.

Configuration manuelle

Étape 1 : créer un Worker

Créez un nouveau répertoire pour votre Worker et initialisez-le :

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

Étape 2 : ajouter le code du Worker

Créez index.js avec le code suivant :

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 },
      },
    });
  },
};

Remplacez YOUR_SLUG par votre sous-domaine Jamdesk réel (par exemple, acme si votre documentation se trouve à acme.jamdesk.app).

L'en-tête X-Jamdesk-Forwarded-Host est obligatoire ; s'il est manquant, l'échec est silencieux — les requêtes réussissent toujours, mais les pages sont servies avec noindex et des liens canoniques pointant vers YOUR_SLUG.jamdesk.app au lieu de votre domaine, si bien que les moteurs de recherche n'indexent jamais votre documentation. Une erreur 403 est le problème inverse : l'en-tête est présent, mais désigne un domaine qui n'est ni enregistré ni actif pour ce projet.

Étape 3 : configurer wrangler.toml

Créez wrangler.toml pour configurer votre 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 votre site sert également du trafic sur www.yoursite.com, ajoutez une seconde route pour que le Worker gère les deux :

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

Étape 4 : déployer

Déployez votre Worker sur Cloudflare :

npx wrangler deploy

Étape 5 : vérifier

Visitez https://yoursite.com/docs pour vérifier que votre documentation est correctement servie.

Dépannage

La CLI affiche vos domaines disponibles avant la sélection de la zone. Si vous voyez « Aucun domaine trouvé » :

  1. Vérifiez que vous êtes connecté au bon compte Cloudflare
  2. Vérifiez que votre domaine est ajouté et actif dans le dashboard Cloudflare
  3. Relancez la CLI et sélectionnez « Non » lorsqu'on vous demande de continuer avec le compte actuel, pour changer de compte

Si vous avez plusieurs comptes Cloudflare :

  1. Exécutez jamdesk deploy-proxy cloudflare
  2. Lorsqu'on vous invite à sélectionner un compte, choisissez celui qui contient votre domaine
  3. Si vous avez besoin d'une connexion totalement différente, sélectionnez « Utiliser une autre connexion »
  4. La CLI vous déconnectera et vous invitera à vous reconnecter avec les identifiants corrects

Cette erreur signifie que la zone sélectionnée ne correspond pas à votre compte Cloudflare. Deux causes possibles :

  • Vous avez sélectionné une zone appartenant à un autre compte
  • La zone a été supprimée de Cloudflare

Solution : relancez la CLI et sélectionnez la bonne zone dans la liste, ou basculez vers le compte propriétaire de la zone.

Assurez-vous que votre modèle de route utilise un caractère générique global : yoursite.com/* (et non yoursite.com/docs*). La fonction interne shouldProxy() du Worker gère le filtrage des chemins.

Deux causes courantes :

  1. Le Worker ne s'exécute pas. Assurez-vous que votre enregistrement DNS est défini sur Proxied (nuage orange) dans Cloudflare. Les Workers ne s'exécutent que sur les enregistrements proxifiés.
  2. En-tête X-Forwarded-Host manquant. Le Worker doit définir cet en-tête pour que Jamdesk génère les bonnes URL de ressources.

Si vous voyez « Le domaine n'est pas autorisé à servir ce contenu » :

  1. Vérifiez que votre domaine est enregistré dans le dashboard Jamdesk
  2. Effectuez la vérification DNS (enregistrement TXT) pour votre domaine
  3. Assurez-vous que l'en-tête X-Jamdesk-Forwarded-Host est défini dans le code de votre Worker
  4. Vérifiez que votre domaine correspond au bon projet

Le domaine doit être vérifié avant que le Worker puisse servir la documentation.

Les Workers ne s'exécutent que sur les enregistrements DNS proxifiés (nuage orange). Si votre enregistrement A est défini sur « DNS only » (nuage gris), les requêtes vont directement à l'origine et contournent entièrement le Worker.

Solution : basculez l'enregistrement A sur proxifié (nuage orange) dans le DNS Cloudflare. Cela s'applique aussi aux sous-domaines : tout enregistrement associé à une route Worker doit être proxifié.

Jamdesk vérifie la propriété en lisant directement les valeurs de vos enregistrements DNS. Le proxy de Cloudflare (nuage orange) masque ces valeurs, ce qui empêche la vérification d'aboutir.

Solution :

  1. Définissez l'enregistrement DNS sur DNS only (nuage gris)
  2. Attendez que la vérification se termine (le statut passe à active dans le dashboard)
  3. Repassez sur Proxied (nuage orange) pour que le Worker fonctionne

En résumé : nuage gris pour vérifier → nuage orange pour servir.

Jamdesk sert le HTML de la documentation avec Cache-Control: no-store, donc Cloudflare ne met pas les pages en cache en périphérie (cf-cache-status: BYPASS). Chaque requête affiche la version actuelle, et les modifications publiées apparaissent immédiatement, sans délai de cache.

Les ressources statiques sous /_next/ et /_jd/ (JavaScript, CSS, polices, images) sont servies avec des en-têtes de cache immutable à longue durée de vie, donc Cloudflare les met en cache en périphérie. Leurs noms de fichiers sont hachés en fonction du contenu, si bien que chaque build produit de nouvelles URL et que les ressources mises à jour sont automatiquement prises en compte. Aucune purge n'est nécessaire.

cacheEverything: true permet à Cloudflare de mettre ces ressources statiques en cache sur la route proxifiée ; cela ne remplace pas le no-store sur le HTML. Pour vider manuellement le cache en périphérie, utilisez Purge Cache de Cloudflare (Caching → Configuration → Purge Everything).

La CLI nécessite wrangler 3.0+. Mettez à jour avec :

npm install -g wrangler@latest

Et ensuite ?

Domaine personnalisé uniquement

Empêchez votre sous-domaine de répondre directement

Domaines personnalisés

Vérifiez le DNS et dépannez

Hébergement en sous-chemin

Servez la documentation sur /docs