Vercel

If your site is already deployed on Vercel, two rewrite rules in vercel.json (or next.config.js) are enough to serve Jamdesk docs at /docs -- no separate proxy or DNS changes needed. For custom domain verification, an Edge Middleware approach is also covered below.

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*"
    },
    {
      "source": "/_next/:path*",
      "destination": "https://YOUR_SLUG.jamdesk.app/_next/:path*"
    },
    {
      "source": "/_jd/:path*",
      "destination": "https://YOUR_SLUG.jamdesk.app/_jd/:path*"
    }
  ]
}

The /_next/ and /_jd/ rewrites are required for Next.js assets (JS, CSS) and Jamdesk resources (fonts, images, branding) to load correctly.

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 rewrite rules handle:

1. The base /docs path (e.g., yoursite.com/docs)
2. All nested paths (e.g., yoursite.com/docs/getting-started)
3. Next.js static assets (/_next/) and Jamdesk resources (/_jd/)

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*" },
    { "source": "/_next/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/_next/:path*" },
    { "source": "/_jd/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/_jd/: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*",
      },
      {
        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;

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.

How It Works

The middleware forwards requests to your Jamdesk subdomain while passing along the original domain in the X-Jamdesk-Forwarded-Host header. Jamdesk uses this header to:

1. Verify your domain - Ensures only authorized domains can serve your docs
2. Apply correct configuration - Uses your domain's settings from the dashboard

This means the middleware is a one-time setup. If you later change your custom domain or configuration in the Jamdesk dashboard, the middleware doesn't need to be updated - all routing decisions are made server-side.

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

When to Use Middleware vs Rewrites

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

What's Next?