Jamdesk Documentation logo

Vercel

Saiba duas formas de servir sua documentação Jamdesk em /docs no seu domínio implantado na Vercel: reescritas no vercel.json ou Edge Middleware.

Sirva sua documentação Jamdesk em /docs no seu domínio implantado na Vercel. Escolha uma de duas configurações. Ambas produzem o mesmo resultado.

Pré-requisitos

  • Um projeto implantado na Vercel
  • Seu subdomínio Jamdesk (encontrado nas configurações do painel), com Host at a subpath habilitado
  • Seu domínio personalizado registrado e verificado no painel

Opção A: Rewrites do vercel.json

Usando um subcaminho personalizado em vez do padrão /docs? Substitua cada /docs nos trechos abaixo pelo seu subcaminho, no source e no destination de cada regra. Reimplante depois de renomear o subcaminho no painel. Nada regenera este arquivo para você.

Uma reescrita pode mudar para onde uma requisição vai. Ela não pode adicionar um cabeçalho de requisição. Em vez disso, cada destino carrega um marcador público, ?jd_proxy=1. O marcador informa ao Jamdesk que a requisição passou pelo seu proxy. O Jamdesk o remove antes de renderizar. Seus visitantes nunca o veem.

Crie ou edite o vercel.json na raiz do projeto, substituindo YOUR_SLUG pelo seu subdomínio Jamdesk:

vercel.json
{
  "rewrites": [
    { "source": "/docs", "destination": "https://YOUR_SLUG.jamdesk.app/docs?jd_proxy=1" },
    { "source": "/docs/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/docs/:path*?jd_proxy=1" },
    { "source": "/_next/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/_next/:path*" },
    { "source": "/_jd/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/_jd/:path*?jd_proxy=1" }
  ]
}

/_next/:path* não precisa de marcador. É um caminho de ativos estáticos que o Jamdesk nunca restringe. Um site que não é um app Next.js não tem arquivos /_next/ próprios. Toda requisição sob esse caminho cai no Jamdesk.

As mesmas quatro regras funcionam no next.config.js para projetos Next.js:

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  async rewrites() {
    return [
      { source: "/docs", destination: "https://YOUR_SLUG.jamdesk.app/docs?jd_proxy=1" },
      { source: "/docs/:path*", destination: "https://YOUR_SLUG.jamdesk.app/docs/:path*?jd_proxy=1" },
      { source: "/_next/:path*", destination: "https://YOUR_SLUG.jamdesk.app/_next/:path*" },
      { source: "/_jd/:path*", destination: "https://YOUR_SLUG.jamdesk.app/_jd/:path*?jd_proxy=1" },
    ];
  },
};

export default nextConfig;

Encaminhe também os arquivos da raiz

robots.txt, sitemap.xml, llms.txt e llms-full.txt ficam na raiz do domínio, fora de /docs. Mecanismos de busca e agentes de IA precisam deles para descobrir sua documentação. Se o Jamdesk controla a raiz do seu domínio, adicione quatro regras:

vercel.json
{
  "rewrites": [
    { "source": "/robots.txt", "destination": "https://YOUR_SLUG.jamdesk.app/robots.txt?jd_proxy=1" },
    { "source": "/sitemap.xml", "destination": "https://YOUR_SLUG.jamdesk.app/sitemap.xml?jd_proxy=1" },
    { "source": "/llms.txt", "destination": "https://YOUR_SLUG.jamdesk.app/llms.txt?jd_proxy=1" },
    { "source": "/llms-full.txt", "destination": "https://YOUR_SLUG.jamdesk.app/llms-full.txt?jd_proxy=1" }
  ]
}

Se seu site de marketing já serve seu próprio robots.txt ou sitemap.xml na raiz, combine os dois em vez de sobrescrever um com o outro.

Implante e verifique

Implante com vercel --prod (ou envie um push para o repositório Git conectado). Abra https://yoursite.com/docs e visualize o código-fonte da página. Verifique duas coisas:

  1. <link rel="canonical"> aponta para o seu domínio, não para YOUR_SLUG.jamdesk.app
  2. Não há <meta name="robots" content="noindex">

Se qualquer uma estiver errada, falta o marcador ?jd_proxy=1 em uma reescrita. Veja Por que o marcador importa.

Opção B: Edge Middleware

Defina o cabeçalho de requisição X-Jamdesk-Forwarded-Host no seu Edge Middleware em vez de usar o marcador. Os dois sinais são equivalentes. Escolha esta opção para manter a lógica de roteamento no código que você já mantém.

Crie um arquivo middleware.ts na raiz do projeto. Substitua YOUR_SLUG pelo seu subdomínio Jamdesk:

middleware.ts
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;
  const destination = new URL(url.pathname + url.search, `https://${JAMDESK_HOST}`);

  // Clone headers and tell Jamdesk which domain the visitor actually used.
  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*', '/_jd/:path*'],
};

Em um subcaminho personalizado, substitua /docs e /docs/:path* no matcher acima pelo seu subcaminho configurado.

Não adicione /_next/:path* ao matcher. O middleware roda antes da verificação do sistema de arquivos da Vercel. Corresponder /_next/ envia o JavaScript e o CSS do seu próprio site para o Jamdesk e quebra seus estilos. O próximo passo roteia /_next/ de forma segura.

Nomeie o arquivo middleware.ts e exporte uma função chamada middleware. O Next.js 16 sugere renomeá-lo para proxy.ts. A produção da Vercel ainda não invoca proxy.ts. Renomear desativa o recurso silenciosamente.

Roteie recursos e arquivos da raiz em vercel.json

Os páginas do Jamdesk carregam seus pacotes a partir de /_next/. Arquivos da raiz como robots.txt ficam fora do matcher acima. Roteie ambos com reescritas. As reescritas rodam depois da verificação do sistema de arquivos. A saída de build do seu próprio site tem precedência, e somente requisições que seu site não consegue atender passam para o Jamdesk:

vercel.json
{
  "rewrites": [
    { "source": "/_next/:path*", "destination": "https://YOUR_SLUG.jamdesk.app/_next/:path*" },
    { "source": "/robots.txt", "destination": "https://YOUR_SLUG.jamdesk.app/robots.txt?jd_proxy=1" },
    { "source": "/sitemap.xml", "destination": "https://YOUR_SLUG.jamdesk.app/sitemap.xml?jd_proxy=1" },
    { "source": "/llms.txt", "destination": "https://YOUR_SLUG.jamdesk.app/llms.txt?jd_proxy=1" },
    { "source": "/llms-full.txt", "destination": "https://YOUR_SLUG.jamdesk.app/llms-full.txt?jd_proxy=1" }
  ]
}

Os arquivos da raiz carregam ?jd_proxy=1. O middleware não roda neles, e uma reescrita não pode definir o cabeçalho. Adicione-os apenas se o Jamdesk controla a raiz do seu domínio. Se seu site serve seu próprio robots.txt ou sitemap.xml, combine.

Implante e verifique

Implante com vercel --prod (ou envie um push para o repositório Git conectado). Abra https://yoursite.com/docs e visualize o código-fonte da página. Verifique duas coisas:

  1. <link rel="canonical"> aponta para o seu domínio, não para YOUR_SLUG.jamdesk.app
  2. Não há <meta name="robots" content="noindex">

Se qualquer uma estiver errada, o cabeçalho X-Jamdesk-Forwarded-Host não está chegando ao Jamdesk. Confirme que /docs está no matcher.

Por que o marcador é importante

O Jamdesk precisa de um sinal de que a requisição chegou pelo seu proxy, e não como um acesso direto ao seu subdomínio *.jamdesk.app. O marcador ?jd_proxy=1 e o cabeçalho X-Jamdesk-Forwarded-Host carregam esse sinal. O Jamdesk os trata como equivalentes. Qualquer um dos dois faz três coisas:

  • Confirma seu domínio registrado
  • Aponta os links canônicos, Open Graph e do sitemap para ele
  • Permite que Somente domínio personalizado distinga o tráfego do proxy dos acessos diretos

Um sinal ausente falha silenciosamente. As páginas ainda renderizam. Sem um domínio personalizado registrado, elas carregam noindex e canônicos de subdomínio. Com um domínio personalizado registrado, a verificação de Somente domínio personalizado falha. Um 403 significa que o sinal está presente, mas aponta para um domínio que não está registrado e ativo para este projeto.

Solução de problemas

Seu matcher provavelmente inclui /_next/:path*. O middleware roda antes da verificação do sistema de arquivos. Ele roteia os ativos da sua própria aplicação para o Jamdesk. Remova /_next/ do matcher e roteie-o pelo vercel.json. Veja a Opção B.

Visualize o código-fonte em https://yoursite.com/docs. Uma tag <meta name="robots" content="noindex"> significa que nem o marcador nem o cabeçalho estão chegando ao Jamdesk. Na Opção A, confirme que todo destino de reescrita termina em ?jd_proxy=1 (exceto /_next/:path*). Na Opção B, confirme que /docs está no matcher do middleware. Uma reescrita do vercel.json sozinha não pode definir o cabeçalho.

O marcador ou cabeçalho chega ao Jamdesk, mas aponta para um domínio que o Jamdesk não serve para este projeto:

  1. Verifique se seu domínio está registrado no painel do Jamdesk
  2. Conclua a verificação de DNS (registro TXT)
  3. Confirme que o domínio está associado ao projeto correto e marcado como ativo
  4. Na Opção B, confirme que o middleware define o cabeçalho com o domínio visto pelo visitante, não uma URL de preview

Verifique se suas reescritas (ou o matcher) cobrem /docs e /docs/:path*. Sem o curinga, as páginas aninhadas falham.

Roteie /_jd/:path* e /_next/:path*. /_jd/ serve fontes, imagens e a identidade visual do Jamdesk. /_next/ serve os pacotes da documentação. A falta de qualquer um quebra o layout.

Confirme que o arquivo se chama middleware.ts (e não proxy.ts) na raiz do projeto. Ele precisa exportar uma função chamada middleware. O aviso de descontinuação do Next.js 16 recomenda proxy.ts. A produção da Vercel não o invoca.

Verifique se a URL de destino usa https:// e aponta para jamdesk.app, e não de volta para o seu próprio domínio.

A verificação busca /_jd/preflight no seu domínio ativo e inspeciona o que chegou ao Jamdesk. "Não se identifica" significa que uma reescrita chegou ao Jamdesk sem o marcador ou o cabeçalho. Revise cada destino de reescrita (Opção A) ou os cabeçalhos do seu middleware (Opção B). Veja Somente domínio personalizado.

Próximos passos?

Somente domínio personalizado

Impeça que seu subdomínio responda diretamente

Domínios personalizados

Verifique o DNS e solucione problemas

Hospedagem em subcaminho

Sirva a documentação em /docs