Biz Deploy Vercel

Biz Deploy Vercel — Implante site na Vercel com segurança, em um comando

Este skill transforma 1 diretório de projeto local (React / Next.js / Vite / HTML estático) em 1 URL ao vivo na Vercel com SSL, CDN e implantação de pré-visualização. Objetivo: solopreneur / PME não precisa saber DevOps para implantar uma landing page apenas via conversa com Claude.

Espírito: Não pergunte ao usuário coisas que Claude pode verificar sozinho. Detecte o framework automaticamente, gere vercel.json quando necessário, e só pare quando encontrar uma barreira manual real (login no navegador, DNS de domínio personalizado).

Quando usar

Usuário quer:

• Enviar 1 landing page / site para uma URL ao vivo para compartilhar / testar / rodar anúncios
• Reimplantar projeto após alterações de código
• Configurar Vercel pela primeira vez para um novo repositório
• Configurar domínio personalizado apontando para Vercel

Quando NÃO usar

• Apenas compilar localmente, sem querer publicar ainda → pule, use npm run build / next dev.
• Precisa implantar no Netlify / Cloudflare Pages / AWS → este skill é especializado em Vercel.
• Precisa de CI/CD complexo com GitHub Actions customizado → ainda use este skill para inicializar o projeto, mas o workflow customizado o usuário configura por conta própria.
• Precisa de backend Node.js com estado completo (websocket, long polling) → Vercel serverless não é adequado, use Railway / Fly.io.

Saída que o usuário receberá

1. URL ao vivo no formato https://<projeto>.vercel.app (produção) ou URL de pré-visualização.
2. URL de inspeção no formato https://vercel.com/<conta>/<projeto>/<id-deploy> para ver logs.
3. Projeto vinculado em .vercel/project.json (gitignored) — na próxima implantação, basta vercel --prod.
4. Se o usuário solicitar domínio personalizado → instruções DNS específicas (registro A / CNAME).

---

Fluxo de trabalho em 6 etapas

Etapa 1 — Pré-verificação: Verificar CLI / MCP da Vercel

Execute scripts/check_vercel.sh (ou comandos inline equivalentes) para determinar o status de 3 itens:

Item a verificar	Comando	Resultado esperado
Node.js	node --version	v18+ ou v20+
Vercel CLI	vercel --version	Versão retornada (v32+)
Autenticação Vercel	vercel whoami	Nome de usuário retornado

Se Node.js estiver faltando:

• macOS: sugira brew install node ou baixe https://nodejs.org
• Windows: oriente a baixar o instalador .msi de https://nodejs.org/en/download/
• Linux: nvm install --lts ou gerenciador de pacotes.
• Pare o skill, aguarde o usuário instalar e avisar.

Se Vercel CLI estiver faltando:

• Detecte o gerenciador de pacotes em uso (verifique pnpm, yarn, npm por ordem de prioridade ou leia o lockfile do projeto).
• Instale globalmente:
  • pnpm add -g vercel (se o usuário usa pnpm)
  • npm install -g vercel (padrão)
• Verifique novamente com vercel --version.

Se Vercel CLI existe, mas não autenticado (vercel whoami retorna erro):

• Execute vercel login — este comando abre o navegador, o usuário deve clicar em confirmar. Esta é uma barreira manual, não pode ser pulada.
• Avise o usuário: "Executei vercel login. Abra o navegador, clique em confirmar para autenticar. Quando terminar, digite 'ok' para eu continuar."
• Pare, aguarde a resposta do usuário.

Se o usuário disser que tem Vercel MCP:

• Verifique o servidor MCP listando as ferramentas MCP disponíveis (ferramentas com prefixo mcp__vercel__*).
• Se MCP existir, ainda prefira CLI para o deploy real (CLI é mais estável para upload de arquivos), use MCP para consultar projeto / domínio / variáveis de ambiente após o deploy, se necessário.
• Se o usuário exigir usar MCP: siga a documentação https://vercel.com/docs/mcp para autenticar, depois use as ferramentas MCP correspondentes.

Etapa 2 — Detectar framework + estrutura do projeto

Leia os arquivos na raiz do projeto para identificar o framework:

Arquivo	Framework
next.config.js / next.config.mjs / next.config.ts	Next.js
vite.config.js / vite.config.ts	Vite (React/Vue/Svelte)
package.json com "react-scripts"	Create React App
package.json com "astro"	Astro
package.json com "@remix-run/dev"	Remix
Apenas index.html + assets, sem package.json	HTML Estático
Tem package.json mas não corresponde aos padrões acima	Pergunte ao usuário qual framework, ou deixe a Vercel detectar automaticamente

Registre também:

• Comando de build do package.json (scripts.build)
• Diretório de saída (Next: .next, Vite: dist, CRA: build, estático: .)
• Versão do Node exigida (de engines.node ou .nvmrc)

→ Leia a referência correspondente:

• React/Vite → references/react-vite.md
• Next.js → references/nextjs.md
• HTML Estático → references/static-html.md

Etapa 3 — Gerar vercel.json (se necessário)

Next.js: A Vercel detecta automaticamente, não precisa de vercel.json a menos que queira headers / redirecionamentos personalizados.

Vite / CRA (SPA routing): Precisa de vercel.json para reescrever todas as rotas para index.html e permitir roteamento no lado do cliente:

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

HTML Estático: Geralmente não precisa. Se o site tiver várias páginas (thank-you.html, privacy.html), não precisa de reescrita. Se tiver apenas index.html + roteador JS, precisa de reescrita como SPA.

Headers de segurança (recomendado para produção):

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
      ]
    }
  ]
}

Regra: Crie vercel.json apenas se o usuário realmente precisar. Criar arquivos desnecessários = ruído no repositório.

Etapa 4 — Lista de verificação pré-implantação

Antes de executar vercel, verifique:

• Existe .gitignore contendo .vercel/, node_modules/, .env* (NÃO commitar segredos)
• Caminhos de arquivos no código estão em minúsculo + relativos (Linux diferencia maiúsculas de minúsculas)
• Não há URLs localhost hardcoded
• Scripts/folhas de estilo externos estão em https://
• Se Next.js tem variáveis de ambiente → preparou lista de envs necessárias
• Se existe package.json → npm install (ou equivalente) roda localmente

Se detectar problemas óbvios (ex.: localhost hardcoded no HTML), corrija antes de implantar.

Etapa 5 — Implantar

Primeira implantação de um projeto (sem .vercel/project.json):

vercel --prod --yes

A flag --yes aceita todas as configurações padrão da detecção automática de framework. A Vercel irá:

• Perguntar o escopo (escolhe automaticamente a conta do usuário com --yes)
• Detectar o preset do framework
• Definir comando de build + diretório de saída
• Enviar código, compilar, implantar

Se precisar de nome de projeto personalizado ou o usuário quiser vincular a um projeto existente:

vercel link              # Vincular a projeto existente (interativo)
vercel --prod            # Implantar após vincular

Implantar pré-visualização (não produção):

vercel

→ Retorna URL de pré-visualização no formato https://<projeto>-<hash>.vercel.app, usada para testar antes de promover para produção.

Reimplantar (projeto já vinculado):

vercel --prod

Capturar saída — analise stdout para obter:

• Production: https://<projeto>.vercel.app
• Inspect: https://vercel.com/...

Avise o usuário imediatamente com essas 2 URLs.

Etapa 6 — Verificar + relatar

Após a implantação bem-sucedida:

1. Verifique HTTP na URL ao vivo com curl -I https://<projeto>.vercel.app — confirme status 200 + SSL ativo.
2. Relate ao usuário no formato:

## ✅ Implantação bem-sucedida

**URL ao vivo**: https://<projeto>.vercel.app
**Inspeção / Logs**: https://vercel.com/<conta>/<projeto>/<id-deploy>
**Framework**: <Next.js | Vite | CRA | HTML Estático>
**Tempo de build**: <Xs>

### Próxima implantação
Basta executar: `vercel --prod`

### Opções
- Configurar domínio personalizado → diga "configurar dominio <seudominio.com>"
- Configurar variáveis de ambiente → diga "adicionar env <CHAVE>"
- Ver logs → `vercel logs`

3. Se o usuário solicitar domínio personalizado → leia references/domains.md e oriente sobre DNS.

---

Casos extremos + recuperação

Build falha na Vercel, mas funciona localmente

Causas comuns:

• Diferenciação maiúsculas/minúsculas: import './Components/Header' funciona no Mac local, mas falha no Linux se a pasta real for components. Correção: renomeie conforme o caso correto.
• Dependência ausente: pacote está em devDependencies mas precisa estar em runtime → mova para dependencies.
• Versão do Node incompatível: adicione "engines": { "node": "20.x" } ao package.json ou .nvmrc.

→ Obtenha o log com vercel logs <url-deploy>, leia, corrija, reimplante.

Projeto vinculado à conta/projeto errada

rm -rf .vercel/ e execute novamente vercel --prod --yes. Ou use vercel link para selecionar o projeto correto.

Variáveis de ambiente em produção

vercel env add <CHAVE> production
# Cole o valor quando solicitado
vercel env pull .env.production.local   # Baixe para local se necessário

Evite commitar arquivos .env*. Adicione ao .gitignore se ainda não estiver.

Autenticação expirada

O token do CLI pode expirar. Se vercel whoami retornar não autorizado → execute vercel login novamente.

---

Referências detalhadas por framework

Leia a referência correspondente ao framework do projeto:

Framework	Referência
Next.js (App / Pages router)	references/nextjs.md
React (Vite / CRA)	references/react-vite.md
HTML Estático	references/static-html.md
Domínio personalizado + DNS	references/domains.md
Erros e solução de problemas	references/troubleshooting.md

Referências originais

• Documentação do Vercel CLI: https://vercel.com/docs/cli
• Configuração de build Vercel: https://vercel.com/docs/projects/project-configuration
• Limites da Vercel (plano gratuito): https://vercel.com/docs/limits
• Página de status: https://www.vercel-status.com