Cloudflare Workers

Use Cloudflare Workers to proxy documentation requests from your domain to Jamdesk. Workers run at the edge, providing fast response times globally.

Prerequisites

• A Cloudflare account with your domain configured
• Wrangler CLI v3.0+ installed
• Your Jamdesk subdomain (found in dashboard settings)

Quick Setup with CLI

The fastest way to set up your Cloudflare Worker:

npx jamdesk deploy cloudflare

This interactive command will:

1. Check that wrangler 3.0+ is installed
2. Verify your Cloudflare account and show available domains
3. Auto-detect your project slug from docs.json
4. Let you select your target domain from your Cloudflare zones
5. Generate all required files
6. Optionally deploy to Cloudflare

Account Selection

The CLI verifies you're logged into the correct Cloudflare account before proceeding. If you have access to multiple Cloudflare accounts (common for agencies or teams), you'll be prompted to choose:

Step 2: Verifying Cloudflare account...
✓ Logged in as: you@example.com
? Select the Cloudflare account to use:
❯ Your Personal Account
  Company Team Account
  [ Switch to different login ]

After selecting an account, only domains from that account will be available for zone selection:

✓ Using account: Company Team Account
✓ Domains: 3 available for Workers routing

CI/Scripted Deployment

For CI/scripting, use flags to skip prompts:

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

If you prefer manual setup, continue with the steps below.

Manual Setup

Step 1: Create a Worker

Create a new directory for your Worker and initialize it:

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

Step 2: Add the Worker Code

Create index.js with the following code:

const JAMDESK_HOST = "YOUR_SLUG.jamdesk.app";

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

    // Only proxy /docs paths
    if (!url.pathname.startsWith("/docs")) {
      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");
    // Required for domain verification
    headers.set("X-Jamdesk-Forwarded-Host", url.hostname);

    const proxyRequest = new Request(proxyUrl, {
      method: request.method,
      headers: headers,
      body: request.body,
    });

    return fetch(proxyRequest);
  },
};

Step 3: Configure wrangler.toml

Create wrangler.toml to configure your Worker:

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

# Route configuration - replace with your domain
routes = [
  { pattern = "yoursite.com/docs*", zone_name = "yoursite.com" }
]

Step 4: Deploy

Deploy your Worker to Cloudflare:

npx wrangler deploy

Step 5: Verify

Visit https://yoursite.com/docs to confirm your documentation is being served correctly.

Alternative: Service Worker Syntax

If you prefer the older Service Worker syntax (compatible with older Workers):

const JAMDESK_HOST = "YOUR_SLUG.jamdesk.app";

addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
  const url = new URL(request.url);

  if (!url.pathname.startsWith("/docs")) {
    return fetch(request);
  }

  const proxyUrl = new URL(request.url);
  proxyUrl.hostname = JAMDESK_HOST;

  const headers = new Headers(request.headers);
  headers.set("Host", JAMDESK_HOST);
  headers.set("X-Forwarded-Host", url.hostname);
  headers.set("X-Forwarded-Proto", "https");
  // Required for domain verification
  headers.set("X-Jamdesk-Forwarded-Host", url.hostname);

  return fetch(new Request(proxyUrl, {
    method: request.method,
    headers: headers,
    body: request.body,
  }));
}

Troubleshooting

npm install -g wrangler@latest