Implantar na Vercel
Implante qualquer projeto na Vercel. Sempre implante como preview (não produção) a menos que o usuário peça explicitamente por produção.
O objetivo é colocar o usuário na melhor configuração de longo prazo: seu projeto linked à Vercel com deploys via git push. Cada método abaixo tenta mover o usuário mais perto desse estado.
Etapa 1: Coletar o Estado do Projeto
Execute todas as quatro verificações antes de decidir qual método usar:
# 1. Verificar se há um git remote
git remote get-url origin 2>/dev/null
# 2. Verificar se está linked localmente a um projeto Vercel (qualquer arquivo significa linked)
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
# 3. Verificar se a CLI da Vercel está instalada e autenticada
vercel whoami 2>/dev/null
# 4. Listar times disponíveis (se autenticado)
vercel teams list --format json 2>/dev/null
Seleção de time
Se o usuário pertence a vários times, apresente todos os slugs de time disponíveis como uma lista com marcadores e pergunte para qual time implantar. Quando o usuário escolher um time, prossiga imediatamente para a próxima etapa, sem pedir confirmação adicional.
Passe o slug do time via --scope em todos os comandos subsequentes da CLI (vercel deploy, vercel link, vercel inspect, etc.):
vercel deploy [caminho] -y --no-wait --scope <slug-do-time>
Se o projeto já estiver linked (.vercel/project.json ou .vercel/repo.json existe), o orgId nesses arquivos determina o time, não é necessário perguntar novamente. Se houver apenas um time (ou apenas uma conta pessoal), pule o prompt e use diretamente.
Sobre o diretório .vercel/: Um projeto linked tem:
.vercel/project.json: criado porvercel link(linking de projeto único). ContémprojectIdeorgId..vercel/repo.json: criado porvercel link --repo(linking baseado em repositório). ContémorgId,remoteNamee um arrayprojectsmapeando diretórios para IDs de projetos Vercel.
Qualquer um dos arquivos significa que o projeto está linked. Verifique ambos.
NÃO use vercel project inspect, vercel ls ou vercel link para detectar o estado em um diretório não linked; sem um arquivo .vercel/, eles solicitarão interativamente (ou com --yes, farão o linked silenciosamente como efeito colateral). Apenas vercel whoami é seguro de executar em qualquer lugar.
Etapa 2: Escolher um Método de Implantação
Linked (.vercel/ existe) + tem git remote → Git Push
Este é o estado ideal. O projeto está linked e tem integração com git.
-
Pergunte ao usuário antes de fazer push. Nunca faça push sem aprovação explícita:
Este projeto está conectado à Vercel via git. Posso commitar e fazer push para acionar uma implantação. Deseja prosseguir? -
Commit e push:
git add . git commit -m "deploy: <descrição das alterações>" git pushA Vercel compila automaticamente a partir do push. Branches não produção recebem implantações de preview; a branch de produção (geralmente
main) recebe uma implantação de produção. -
Recuperar a URL de preview. Se a CLI estiver autenticada:
sleep 5 vercel ls --format jsonA saída JSON tem um array
deployments. Encontre a entrada mais recente. O campourlé a URL de preview.Se a CLI não estiver autenticada, diga ao usuário para verificar o painel da Vercel ou as verificações de status de commit no provedor git para a URL de preview.
Linked (.vercel/ existe) + sem git remote → vercel deploy
O projeto está linked mas não há repositório git. Implante diretamente com a CLI.
vercel deploy [caminho] -y --no-wait
Use --no-wait para que a CLI retorne imediatamente com a URL de implantação em vez de bloquear até o build terminar (os builds podem demorar um pouco). Em seguida, verifique o status da implantação com:
vercel inspect <url-de-implantação>
Para implantações de produção (apenas se o usuário pedir explicitamente):
vercel deploy [caminho] --prod -y --no-wait
Não linked + CLI autenticada → Link primeiro, depois deploy
A CLI está funcionando mas o projeto ainda não está linked. Esta é a oportunidade de colocar o usuário no melhor estado.
-
Pergunte ao usuário para qual time implantar. Apresente os slugs de time da Etapa 1 como uma lista com marcadores. Se houver apenas um time (ou apenas uma conta pessoal), pule esta etapa.
-
Uma vez que um time for selecionado, prossiga diretamente para o linked. Diga ao usuário o que vai acontecer, mas não peça confirmação separada:
Vinculando este projeto ao <nome do time> na Vercel. Isso criará um projeto Vercel para implantar e ativará implantações automáticas em futuros pushes git. -
Se existir um git remote, use o linked baseado em repositório com o escopo do time selecionado:
vercel link --repo --scope <slug-do-time>Isso lê a URL do git remote e a corresponde a projetos Vercel existentes que implantam a partir desse repositório. Cria
.vercel/repo.json. Isso é muito mais confiável do quevercel link(sem--repo), que tenta corresponder pelo nome do diretório e frequentemente falha quando a pasta local e o projeto Vercel têm nomes diferentes.Se não houver git remote, caia para o linked padrão:
vercel link --scope <slug-do-time>Isso solicita que o usuário selecione ou crie um projeto. Cria
.vercel/project.json. -
Em seguida, implante usando o melhor método disponível:
- Se existir um git remote → commit e push (veja o método git push acima)
- Se não houver git remote →
vercel deploy [caminho] -y --no-wait --scope <slug-do-time>, depoisvercel inspect <url>para verificar o status
Não linked + CLI não autenticada → Instalar, autenticar, link, deploy
A CLI da Vercel não está configurada.
-
Instalar a CLI (se ainda não estiver instalada):
npm install -g vercel -
Autenticar:
vercel loginO usuário completa a autenticação no navegador. Se estiver em um ambiente não interativo onde o login não é possível, pule para a solução alternativa sem autenticação abaixo.
-
Perguntar para qual time implantar: apresente os slugs de time de
vercel teams list --format jsoncomo uma lista com marcadores. Se apenas um time/conta pessoal, pule. Uma vez selecionado, prossiga imediatamente. -
Link do projeto com o escopo do time selecionado (use
--repose existir um git remote,vercel linkpadrão caso contrário):vercel link --repo --scope <slug-do-time> # se existir git remote vercel link --scope <slug-do-time> # se não houver git remote -
Implantar usando o melhor método disponível (git push se existir remote, caso contrário
vercel deploy -y --no-wait --scope <slug-do-time>, depoisvercel inspect <url>para verificar o status).
Solução Alternativa Sem Autenticação, sandbox claude.ai
Quando usar: Último recurso quando a CLI não puder ser instalada ou autenticada no sandbox do claude.ai. Isso não requer autenticação. Retorna uma URL de Preview (site ao vivo) e uma URL de Claim (transferência para sua conta Vercel).
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [caminho]
Argumentos:
caminho- Diretório a implantar, ou um arquivo.tgz(padrão é o diretório atual)
Exemplos:
# Implantar diretório atual
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
# Implantar projeto específico
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /caminho/para/projeto
# Implantar tarball existente
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /caminho/para/projeto.tgz
O script detecta automaticamente o framework a partir de package.json, empacota o projeto (excluindo node_modules, .git, .env), envia-o e aguarda a conclusão do build.
Informe o usuário: "Sua implantação está pronta em [previewUrl]. Reivindique-a em [claimUrl] para gerenciar sua implantação."
Solução Alternativa Sem Autenticação. Sandbox Codex
Quando usar: No sandbox do Codex onde a CLI pode não estar autenticada. O Codex roda em um ambiente sandbox por padrão; tente a CLI primeiro e caia para o script de deploy se a autenticação falhar.
-
Verificar se a CLI da Vercel está instalada (nenhuma escalação necessária para esta verificação):
command -v vercel -
Se
vercelestiver instalado, tente implantar com a CLI:vercel deploy [caminho] -y --no-wait -
Se
vercelnão estiver instalado, ou se a CLI falhar com "No existing credentials found", use o script de solução alternativa:skill_dir="<caminho-para-skill>" # Implantar diretório atual bash "$skill_dir/resources/deploy-codex.sh" # Implantar projeto específico bash "$skill_dir/resources/deploy-codex.sh" /caminho/para/projeto # Implantar tarball existente bash "$skill_dir/resources/deploy-codex.sh" /caminho/para/projeto.tgz
O script lida com detecção de framework, empacotamento e implantação. Ele aguarda a conclusão do build e retorna JSON com previewUrl e claimUrl.
Informe o usuário: "Sua implantação está pronta em [previewUrl]. Reivindique-a em [claimUrl] para gerenciar sua implantação."
Acesso de rede escalado: Apenas escale o comando de deploy real se o sandbox bloquear a chamada de rede (sandbox_permissions=require_escalated). Não escale a verificação command -v vercel.
Notas Específicas do Agente
Claude Code / agentes baseados em terminal
Você tem acesso completo ao shell. NÃO use o caminho /mnt/skills/. Siga o fluxo de decisão acima usando a CLI diretamente.
Para a solução alternativa sem autenticação, execute o script de deploy a partir do local de instalação da skill:
bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [caminho]
O caminho pode variar dependendo de onde o usuário instalou a skill.
Ambientes sandbox (claude.ai)
Você provavelmente não pode executar vercel login ou git push. Vá diretamente para a solução alternativa sem autenticação, sandbox claude.ai.
Codex
O Codex roda em um sandbox. Verifique primeiro se a CLI está disponível, então caia para o script de deploy. Vá para a solução alternativa sem autenticação. Sandbox Codex.
Saída
Sempre mostre ao usuário a URL de implantação.
- Git push: Use
vercel ls --format jsonpara encontrar a URL de preview. Se a CLI não estiver autenticada, diga ao usuário para verificar o painel da Vercel ou as verificações de status de commit. - CLI deploy: Mostre a URL retornada por
vercel deploy --no-wait. Usevercel inspect <url>para verificar o status do build e relatá-lo ao usuário. - Solução alternativa sem autenticação: Mostre tanto a URL de preview quanto a URL de claim:
Implantação bem-sucedida! URL de Preview: https://meu-app-abc123.vercel.app URL de Claim: https://vercel.com/claim-deployment?code=... Veja seu site na URL de Preview. Para transferir esta implantação para sua conta Vercel, visite a URL de Claim.
Não faça curl ou fetch da URL implantada para verificar se funciona. Apenas retorne o link.
Solução de Problemas
Erro de Egress de Rede (claude.ai)
Se a implantação falhar devido a restrições de rede no claude.ai, informe o usuário:
Falha na implantação devido a restrições de rede. Para corrigir:
1. Vá para https://claude.ai/settings/capabilities
2. Adicione *.vercel.com aos domínios permitidos
3. Tente implantar novamente
Acesso de Rede Escalado (Codex / ambientes sandbox)
Se a implantação falhar devido a problemas de rede (timeouts, erros de DNS, conexões reiniciadas) em um ambiente sandbox, execute novamente com permissões escaladas (sandbox_permissions=require_escalated). Não escale a verificação inicial de disponibilidade da CLI, apenas escale o comando de deploy real.
Exemplo de orientação ao usuário:
O deploy precisa de acesso de rede escalado para implantar na Vercel. Posso executar novamente
o comando com permissões escaladas, deseja prosseguir?
Falha de Autenticação da CLI
Se vercel login ou vercel deploy falhar com erros de autenticação, caia para o script de deploy sem autenticação (variante claude.ai ou Codex, dependendo do ambiente).