Vercel

Use Vercel rewrites to proxy documentation requests to Jamdesk. Rewrites happen at the edge and don't change the URL in the browser.

Prerequisites

• A project deployed on Vercel
• Your Jamdesk subdomain (found in dashboard settings)

Step 1: Update vercel.json

Add a rewrites configuration to your vercel.json file. If the file doesn't exist, create it in your project root:

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

Step 2: Deploy

Deploy your changes to Vercel:

vercel --prod

Or push to your connected Git repository to trigger an automatic deployment.

Step 3: Verify

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

Understanding the Configuration

The two rewrite rules handle:

1. The base /docs path (e.g., yoursite.com/docs)
2. All nested paths (e.g., yoursite.com/docs/getting-started)

Adding to Existing Rewrites

If you already have rewrites configured, add the Jamdesk rules to your existing array:

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

Using next.config.js (Next.js Projects)

For Next.js projects, you can alternatively configure rewrites in 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*",
      },
    ];
  },
};

export default nextConfig;

Troubleshooting

Custom Domain Verification

Vercel rewrites work by proxying requests to your Jamdesk subdomain (YOUR_SLUG.jamdesk.app). This basic setup doesn't require domain verification.

If you've configured a custom domain in the Jamdesk dashboard with the "Host at /docs" option, you'll need to use Edge Middleware instead of simple rewrites to set the required verification header.

Using Edge Middleware

Create a middleware.ts file in your project root:

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 paths
  if (!url.pathname.startsWith('/docs')) {
    return NextResponse.next();
  }

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

  const response = NextResponse.rewrite(destination);

  // Required for domain verification
  response.headers.set('X-Jamdesk-Forwarded-Host', url.hostname);

  return response;
}

export const config = {
  matcher: '/docs/:path*',
};

When to Use Middleware vs Rewrites

If you don't need custom domain verification, the simpler rewrites approach is sufficient.