CodFlow Storefront — Implantação no Vercel

Vitrine CodFlow — Runbook de Implantação no Vercel

cod-astro/theme01 é o tema de vitrine voltado ao cliente para CodFlow (Astro 7). Enquanto o backend do CodFlow (cod-server) e o painel do comerciante (cod-client-astro) rodam em Cloudflare Workers (usando D1, R2 e KV), a vitrine oferece suporte a alvos de implantação dinâmicos (DEPLOY_TARGET=vercel ou DEPLOY_TARGET=cloudflare).

Implantar a vitrine no Vercel é frequentemente preferido porque:

1. Resolve o Erro 1042 do Cloudflare (bloqueio Worker-to-Worker): Quando o cod-server é implantado em um subdomínio gratuito *.workers.dev sem um domínio personalizado, o Cloudflare bloqueia outro Worker do Cloudflare em *.workers.dev de acessá-lo. O Vercel roda fora da rede interna do Cloudflare, permitindo que a vitrine acesse o cod-server em *.workers.dev sem precisar de um domínio personalizado.
2. Largura de Banda Global Generosa: O Vercel inclui largura de banda generosa e cache CDN Edge para o tráfego da vitrine.
3. Implantações de Pré-visualização Automáticas: Cada branch/PR do Git pode ter sua própria URL de pré-visualização para testar alterações no tema.

---

Variáveis de Ambiente Obrigatórias

Antes de implantar, colete estes valores:

Variável	Descrição	Exemplo
DEPLOY_TARGET	Obrigatória. Informa ao astro.config.mjs para usar @astrojs/vercel	vercel
COD_SERVER_URL	Obrigatória. URL base da API do cod-server implantado	https://api.seudominio.com ou https://codflow-server.<account>.workers.dev
STORE_API_KEY	Obrigatória. Chave bruta da API da loja que corresponde à chave semeada no D1	Gerada no codflow-setup Passo 4
MEDIA_DOMAIN	Opcional. Domínio personalizado para o CDN de imagens R2	media.seudominio.com

[!IMPORTANTE] STORE_API_KEY é secreta. Ela é usada no lado do servidor em rotas SSR e proxies de API. Nunca a exponha em bundles do lado do cliente.

---

Métodos de Implantação

Escolha o Método 1 (CLI do Vercel) para implantações automatizadas/por terminal, ou o Método 2 (Painel Vercel / Git) para implantação contínua a partir do GitHub.

---

Método 1: Implantar via CLI do Vercel (Recomendado para Agentes AI)

1. Pré-requisitos

• Garanta que o CLI do Vercel esteja acessível via npx vercel (ou instalado globalmente).
• Verifique a autenticação:

  npx vercel whoami
  

  Se não estiver logado:
  • Se um navegador estiver disponível: npx vercel login
  • Se for headless/CI: Defina VERCEL_TOKEN no ambiente (export VERCEL_TOKEN="<token>").

2. Configurar e Vincular o Projeto

Navegue até o diretório da vitrine:

cd cod-astro/theme01

Execute a configuração inicial:

npx vercel link

Siga os prompts interativos (ou forneça flags em sessões não interativas):

• Vincular a um projeto existente? Não (ou Sim se estiver vinculando um existente)
• Nome do projeto: <projeto>-storefront (ex.: meuloja-storefront)
• Em qual diretório está seu código? ./

3. Definir Variáveis de Ambiente

Adicione as variáveis de ambiente de produção obrigatórias usando o CLI:

# 1. Alvo de Implantação
printf "vercel" | npx vercel env add DEPLOY_TARGET production

# 2. URL da API do Backend (deve começar com https://)
printf "https://<seu-dominio-cod-server>" | npx vercel env add COD_SERVER_URL production

# 3. Chave da API da Loja
printf "<sua-chave-bruta-da-api-da-loja>" | npx vercel env add STORE_API_KEY production

# 4. Opcional: Domínio de Mídia (se o domínio personalizado R2 estiver configurado)
printf "<media.seudominio.com>" | npx vercel env add MEDIA_DOMAIN production

(Opcional: adicione-os também aos ambientes preview e development se você planeja usar branches de pré-visualização).

4. Construir e Implantar para Produção

Execute a implantação de produção com o adaptador Vercel:

cd cod-astro/theme01
npx vercel --prod

O Vercel fará upload do projeto, executará npm run build:vercel (ou astro build com DEPLOY_TARGET=vercel), compilará as funções serverless/edge SSR e fornecerá a URL de produção ativa (ex.: https://<projeto>-storefront.vercel.app).

---

Método 2: Implantar via Painel Vercel (Integração Git)

Use este método ao conectar um repositório GitHub / GitLab / Bitbucket:

1. Importar Repositório no Vercel:

   • No Painel Vercel, clique em Adicionar Novo... → Projeto.
   • Selecione o repositório codflow-os.

2. Configurar Definições do Projeto:

   • Nome do Projeto: ex.: codflow-storefront
   • Preset de Framework: Astro
   • Diretório Raiz: Clique em Editar e escolha cod-astro/theme01. Marque a opção "Incluir arquivos fonte fora do Diretório Raiz na Etapa de Build" (necessário porque as dependências do workspace resolvem para node_modules raiz).
   • Comando de Build: Ative Sobrescrever e defina:

     npm run build:vercel
     

     (Ou deixe o padrão astro build se DEPLOY_TARGET=vercel estiver definido nas Variáveis de Ambiente).
   • Diretório de Saída: Deixe o padrão (.vercel/output).
   • Comando de Instalação: Deixe o padrão (npm install / instalação do workspace raiz).

3. Configurar Variáveis de Ambiente: Em Variáveis de Ambiente, adicione:

   • DEPLOY_TARGET = vercel
   • COD_SERVER_URL = https://<seu-dominio-cod-server>
   • STORE_API_KEY = <sua-chave-bruta-da-api-da-loja>
   • MEDIA_DOMAIN = <media.seudominio.com> (opcional)

4. Implantar:

   • Clique em Implantar. O Vercel construirá o workspace, empacotará o site Astro com @astrojs/vercel e atribuirá uma URL de produção.

---

Verificação e Testes de Fumaça

Assim que a implantação for concluída, execute estas verificações na URL ativa do Vercel:

Alvo	Comando de Teste / Ação	Resultado Esperado
Página Inicial	curl -s -o /dev/null -w "%{http_code}" https://<url-da-vitrine>	200 (resposta HTML)
Catálogo SSR	Abra https://<url-da-vitrine>/ no navegador	Produtos carregados com imagens, preços e título
Detalhes do Produto	Abra https://<url-da-vitrine>/product/<slug>	Página do produto renderizada com formulário de checkout / pedido
Carrinho / Fluxo de Pedido	Envie um pedido de teste (ou modal de teste)	Pedido registrado e página de agradecimento exibida

Teste via Terminal:

# Verificar se a página inicial retorna 200 OK
curl -s -I "https://<sua-vitrine>.vercel.app" | head -n 5

# Verificar conectividade da API através do proxy da vitrine
curl -s "https://<sua-vitrine>.vercel.app/api/cart/validate" \
  -H "Content-Type: application/json" \
  -d '{"items":[]}'
# Espera-se uma resposta JSON válida

---

Configuração de Domínio Personalizado

Para anexar um domínio personalizado à vitrine no Vercel:

1. No Painel Vercel: Projeto → Configurações → Domínios.
2. Insira seu domínio (ex.: store.seudominio.com ou seudominio.com).
3. Configure os registros DNS:
   • Para subdomínios (store.seudominio.com): Adicione CNAME apontando para cname.vercel-dns.com.
   • Para domínio apex (seudominio.com): Adicione registro A apontando para 76.76.21.21.
4. Aguarde a emissão do certificado SSL (automática via Let's Encrypt).

---

Solução de Problemas

Problema	Causa	Solução
Falha no build: Cannot find module '@astrojs/vercel'	Dependência ausente em cod-astro/theme01	Execute npm install @astrojs/vercel --workspace=cod-astro-theme01 na raiz do repositório.
Build produz saída Cloudflare em vez de saída Vercel	DEPLOY_TARGET não definido como vercel	Certifique-se de que DEPLOY_TARGET=vercel está presente nas variáveis de ambiente do Vercel, ou execute npm run build:vercel.
Vitrine carrega mas mostra produtos vazios / banner de erro	COD_SERVER_URL incorreto ou inacessível	Confirme que COD_SERVER_URL tem o prefixo https:// e corresponde ao worker da API ativo. Verifique se curl https://<url-da-api>/api/docs retorna 200.
Pedidos falham com 401 Não Autorizado	Incompatibilidade de STORE_API_KEY	O valor em STORE_API_KEY no Vercel deve corresponder à chave semeada no banco de dados D1 no codflow-setup Passo 5. Refaça ou atualize o segredo no Vercel.
Build do monorepo falha ao resolver pacotes compartilhados	Configuração do diretório raiz do Vercel	Se estiver usando integração Git, certifique-se de que "Incluir arquivos fonte fora do Diretório Raiz" está ativado nas definições do projeto Vercel, ou implante via npx vercel dentro de cod-astro/theme01.
Aviso de versão do Node.js: Node.js 26 não é suportado	Funções serverless do Vercel suportam até Node 24	Aviso normal em máquinas de desenvolvimento com Node 26; o Vercel automaticamente executa Node 24 em suas funções cloud.
Imagens não carregam do R2	MEDIA_DOMAIN mal configurado ou CORS ausente	Verifique se MEDIA_DOMAIN está definido (apenas hostname, sem https://). Certifique-se de que a política CORS do bucket R2 permite requisições do domínio Vercel.