Documentação: Deploy de aplicação Next.js com GitHub + Hostinger

O objetivo desta configuração é que toda alteração no código seja publicada no site automaticamente, sem upload manual de arquivos. O fluxo é este:

Seu computador (código) ──git push──> GitHub (guarda o código) ──deploy automático──> Hostinger (roda o site)

1. Você edita o código no seu computador (VS Code).
2. Envia as mudanças para o GitHub com o comando git push.
3. A Hostinger detecta o push sozinha, recompila o projeto e atualiza o site no ar (2 a 5 minutos).

Você nunca precisa tocar no painel da Hostinger para atualizar o site.

Onde cada coisa acontece

• Git instalado no computador. Verificar com git --version no terminal. Se não estiver instalado, baixar em https://git-scm.com/downloads.
• Conta no GitHub (github.com).
• Plano Hostinger com suporte a Web Apps / Node.js. No nosso caso, o plano Cloud Startup, que inclui 10 Web Apps e suporta Next.js com Node.js 18.x, 20.x, 22.x e 24.x. Os planos compartilhados mais básicos não têm esse recurso.
• Projeto Next.js funcionando localmente (roda com npm run dev).

Feitas uma única vez, antes de tudo.

3.1 Verificar se o Git está instalado

git --version

• Resposta esperada: algo como git version 2.43.0.
• Se aparecer "git não é reconhecido": instalar o Git e reabrir o VS Code.

3.2 Verificar se o projeto já tem Git inicializado

git status

• Apareceu uma lista de arquivos (ou "nothing to commit") → o Git já existe na pasta. Não rodar git init.
• Apareceu fatal: not a git repository → rodar git init na Etapa 5.

Como saber se o projeto foi criado com create-next-app: abrir o package.json e verificar se existe "next" dentro de "dependencies". Outro sinal: o .gitignore padrão do create-next-app (com seções # next.js, # vercel etc.).

3.3 Identificar-se para o Git (feito 1 vez por computador)

O Git carimba cada alteração com nome e e-mail:

git config --global user.name "Seu Nome"
git config --global user.email "seuemail@exemplo.com"

Usar o mesmo e-mail da conta do GitHub. Nenhuma mensagem de confirmação aparece; se não deu erro, funcionou.

4.1 O arquivo .gitignore

O .gitignore é uma lista de arquivos que NÃO devem ir para o GitHub. Ele existe por dois motivos:

1. Segurança: arquivos .env guardam senhas e chaves secretas. Não podem ficar expostos no repositório.
2. Tamanho/necessidade: pastas como node_modules (bibliotecas) e .next (resultado do build) são geradas automaticamente. A Hostinger recria as duas sozinha no servidor.

O create-next-app já gera o arquivo pronto. Conteúdo mínimo necessário:

# dependencies
/node_modules

# next.js
/.next/
/out/

# production
/build

# env files
.env*

# debug
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# misc
.DS_Store
*.pem
.vercel
*.tsbuildinfo
next-env.d.ts

Observação: a linha .env* bloqueia qualquer arquivo que comece com .env, inclusive um eventual .env.example. Se um dia o time quiser versionar um arquivo modelo (sem senhas reais), basta adicionar !.env.example ao .gitignore (o ! significa "exceto este").

4.2 Conferir o package.json

A Hostinger usa os scripts do package.json para instalar, compilar e ligar o site. Confirmar que existem:

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start"
}

Também garantir que next, react e react-dom estão em dependencies (não em devDependencies).

4.3 Testar o build de produção localmente

npm run build

Este comando compila o projeto do mesmo jeito que a Hostinger vai compilar. Se falhar localmente, vai falhar no deploy. O modo npm run dev tolera erros (tipos, ESLint, páginas dinâmicas) que o build de produção não perdoa. Corrigir qualquer erro antes de prosseguir.

Um repositório é a "pasta do projeto na nuvem", com histórico de todas as mudanças.

1. Acessar https://github.com e fazer login.
2. Clicar no + no canto superior direito → New repository.
3. Preencher: - Repository name: nome sem espaços e sem acentos (no nosso caso, zumkai). - Visibilidade: Private 🔒 (só você vê o código; a Hostinger acessa mesmo assim, porque será autorizada depois). - NÃO marcar nada em "Initialize this repository with" (nem README, nem .gitignore, nem license). Motivo: o projeto já existe no computador; se o GitHub criar arquivos por conta própria, o primeiro push dá conflito de "histórias diferentes".
4. Clicar em Create repository.
5. Na página "Quick setup" que abre, copiar a URL do repositório (deixar a opção HTTPS selecionada):

https://github.com/sergioarantes/zumkai.git

Comandos executados um por vez, com Enter após cada um.

6.1 git init (somente se necessário)

git init

Transforma a pasta em um projeto Git. Pular se o git status da Etapa 0 já funcionava (nosso caso).

6.2 Preparar todos os arquivos

git add .

Tradução: "Git, prepare TODOS os arquivos da pasta para serem salvos" (o ponto significa "tudo"). Os arquivos listados no .gitignore são ignorados automaticamente. Este comando não mostra resposta — silêncio é sucesso.

6.3 Salvar uma "foto" do projeto

git commit -m "Primeira versao do projeto"

Salva o estado atual do projeto com a descrição entre aspas. Cada commit é um ponto na história ao qual se pode voltar. A resposta mostra um resumo, tipo 5 files changed, 28 insertions(+).

6.4 Renomear a branch principal para main

git branch -M main

O padrão atual do GitHub é main; projetos antigos usam master. Rodar mesmo que já se chame main (não faz mal).

6.5 Conectar a pasta ao repositório do GitHub

Primeiro, verificar se já existe conexão:

git remote -v

• Nada aparece → conectar com a URL copiada na Etapa 2:

git remote add origin https://github.com/sergioarantes/zumkai.git

• Já aparece uma URL errada → corrigir com:

git remote set-url origin https://github.com/sergioarantes/zumkai.git

Tradução: "o endereço remoto deste projeto, apelidado de origin, é este".

6.6 Enviar de verdade (primeiro push)

git push -u origin main

• Na primeira vez, abre uma janela/navegador pedindo login no GitHub → clicar em Sign in with your browser e autorizar. Nas próximas vezes não pede mais.
• O -u origin main só é necessário no primeiro push; depois, basta git push.

Saída de sucesso (exemplo real do nosso deploy):

Writing objects: 100% (845/845), 4.52 MiB | 3.01 MiB/s, done.
To https://github.com/sergioarantes/zumkai.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

6.7 Conferir no site do GitHub

Abrir a página do repositório e apertar F5. Verificar:

• ✅ Os arquivos do projeto aparecem
• ✅ node_modules/ NÃO está lá
• ✅ .next/ NÃO está lá
• ✅ Nenhum arquivo .env está lá
• ✅ .claude/settings.local.json NÃO está lá

Configuração feita uma única vez.

7.1 Iniciar o deploy

1. Acessar https://hpanel.hostinger.com e fazer login.
2. Menu lateral → Websites → botão + Add Website.
3. Escolher Deploy Web App ("Deploy your app from GitHub or upload files").

7.2 Conectar o GitHub

1. Escolher a opção de importar via GitHub (não "upload files").
2. O GitHub abre pedindo autorização → clicar em Authorize. - Se perguntar entre "All repositories" e "Only select repositories", escolher Only select repositories e marcar apenas o repositório do projeto (mais seguro).
3. De volta à Hostinger, selecionar o repositório (zumkai) e a branch (main).

7.3 Revisar as configurações de build

A Hostinger detecta o framework automaticamente. Configuração usada no nosso deploy:

7.4 Variáveis de ambiente

• Se o projeto NÃO tem arquivo .env (nosso caso) → não preencher nada nesta seção.
• Se o projeto TEM .env com conteúdo → cadastrar cada linha na seção Environment variables (Add): o que vem antes do = é o Name, o que vem depois é o Value. Necessário porque o .gitignore impede (de propósito) que o .env vá para o GitHub, então a Hostinger não conhece esses valores.
• Atenção: variáveis NEXT_PUBLIC_* são embutidas no momento do build. Se alterar alguma no painel, é preciso disparar um novo deploy para valer.

7.5 Executar o deploy

1. Clicar no botão Deploy →.
2. Acompanhar o log (instalação → build → start). Leva de 2 a 5 minutos. Não fechar a página.
3. Ao final, aparece "Deployment completed!" com um preview do site no ar.
4. O domínio (zumkai.com) já fica apontado para a aplicação.

A partir daqui, todo push na branch main atualiza o site automaticamente. A Hostinger detecta, recompila e publica sozinha.

8.1 Os 3 comandos para toda atualização

git add .
git commit -m "descreva aqui o que mudou"
git push

Versão em uma linha só (o && só executa o próximo se o anterior deu certo):

git add . && git commit -m "descreva aqui o que mudou" && git push

8.2 Rotina recomendada antes de cada push

1. npm run dev → testar a mudança no navegador local.
2. npm run build → confirmar que compila sem erro (o que falha aqui, falha no deploy).
3. git status → conferir o que vai ser enviado. O git add . leva tudo que estiver alterado na pasta, não só o último arquivo mexido.
4. git add . → git commit -m "..." → git push.

8.3 Como acompanhar um deploy

No hPanel → dashboard do Web App → área Deployments: mostra cada deploy com status (In progress / Completed / Failed), branch, commit e data. Clicar em um deploy abre o log completo.

8.4 Como conferir se o site atualizou

Abrir o site e recarregar ignorando o cache: Ctrl + Shift + R. Para um teste 100% limpo, usar uma janela anônima (Ctrl + Shift + N).

Deploy falhou na Hostinger (status "Failed")

Abrir o log do deploy na área Deployments. Causas mais comuns:

1. Erro de build → reproduzir localmente com npm run build e corrigir. É a causa nº 1.
2. Variável de ambiente faltando → cadastrar no painel e redeployar.
3. Dependência em devDependencies que deveria estar em dependencies no package.json (o build de produção não instala devDependencies).

Site não atualizou depois do push

1. Conferir no GitHub se o commit chegou (a página do repositório mostra "X minutes ago").
2. Conferir a área Deployments no hPanel (o deploy pode estar em andamento ou ter falhado).
3. Recarregar com Ctrl + Shift + R (cache do navegador é causa frequente de "não mudou nada").
4. Se o site atualizou mas ficou sem estilo/quebrado, ver o caso da CDN logo abaixo.

Site aparece "quebrado" / sem estilo após um deploy (⚠️ caso real que aconteceu neste projeto)

Sintoma: logo após um push/deploy, o site carrega só o conteúdo "pelado" — textos e links aparecem, mas sem cores, fontes ou layout. O Ctrl + Shift + R não resolve.

Causa: descasamento de versões causado pelo cache da CDN da Hostinger. Funciona assim: a cada build, o Next.js gera os arquivos de CSS e JS com nomes únicos (ex.: 3z2vuf_k-6jbb.css) que mudam a cada compilação. A CDN (rede que guarda cópias do site para entregá-lo mais rápido) pode continuar servindo o HTML da versão antiga, que pede arquivos com nomes antigos — e esses arquivos já não existem no servidor. Resultado: erros 404 e site sem estilo. O Ctrl + Shift + R não resolve porque ele limpa o cache do navegador, não o cache do servidor/CDN.

Como confirmar o diagnóstico (2 minutos):

1. Abrir o site no Chrome e apertar F12 (ferramentas de desenvolvedor).
2. Ir na aba Console (ou Network/Rede e recarregar com Ctrl + R).
3. Se aparecerem erros como este, é exatamente esse problema:

GET https://seusite.com/_next/static/chunks/xxxxx.css  404 (Not Found)
GET https://seusite.com/_next/static/chunks/xxxxx.js   404 (Not Found)

Vale conferir também o log do deploy em Deployments: neste cenário ele aparece Completed, com Compiled successfully — ou seja, o código está saudável; o problema é só de cache.

Solução (na ordem):

1. Redeploy: no painel do Web App, clicar no botão Redeploy e aguardar concluir. Isso republica HTML e arquivos estáticos da mesma versão.
2. Limpar o cache da CDN: no hPanel, ir em Websites → [seu site] → Performance → CDN e clicar em Flush cache.
3. Aguardar 1 a 2 minutos e testar em janela anônima (Ctrl + Shift + N), que garante zero interferência do cache do navegador.

Observações sobre a tela da CDN: o botão Development mode desliga temporariamente o cache da CDN por algumas horas (útil em períodos de muitos testes seguidos); Disable desativa a CDN de vez (não recomendado, pois ela acelera o site). O aviso amarelo no Console sobre "resource was preloaded using link preload" é inofensivo e desaparece junto quando os 404 são resolvidos.

Vulnerabilidades detectadas pela Hostinger (⚠️ caso real que aconteceu neste projeto)

Sintoma: o painel Websites → [site] → Security → Vulnerabilities mostra vulnerabilidades com aviso "Requires manual patching", listando pacotes (ex.: postcss, sharp), severidade e a versão corrigida.

O que significa: não é invasão nem erro no seu código. São falhas descobertas em bibliotecas de terceiros que o projeto usa. As correções já existem em versões mais novas; "manual patching" significa apenas "atualize as versões no seu projeto". A correção é feita no terminal, e o deploy automático leva a correção ao servidor.

Passo a passo da correção:

1. Garantir que está tudo commitado (git status), para poder voltar atrás com facilidade se algo der errado.
2. Ver as vulnerabilidades localmente:

npm audit

É a mesma base de dados que a Hostinger usa. Anote os pacotes e as versões-alvo.

3. Tentar a correção automática segura:

npm audit fix

Se o npm audit zerar depois disso, pular para o passo 6.

4. Descobrir se o pacote vulnerável é dependência direta ou "de carona":

npm ls nome-do-pacote

O comando mostra a árvore. Caso real deste projeto: postcss@8.4.31 e sharp@0.34.5 apareciam dentro de next@16.2.11 — ou seja, não eram dependências diretas, vieram de carona com o Next.

5. Atualizar do jeito certo, conforme o caso:

• Dependência direta (aparece no package.json) → atualizar direto:

npm install nome-do-pacote@^versao-corrigida

• Dependência "de carona" (não aparece no package.json) → adicionar um bloco overrides no package.json, no mesmo nível de dependencies (nunca dentro), e rodar npm install. Exemplo real usado neste projeto:

"overrides": {
  "postcss": "^8.5.12",
  "sharp": "^0.35.0"
}

O overrides significa: "não importa quem pediu essas bibliotecas — nem mesmo o Next — use no mínimo essas versões".

6. Verificar se aplicou:

npm ls nome-do-pacote   # deve mostrar a versão nova (pode aparecer "overridden"/"deduped")
npm audit               # esperado: found 0 vulnerabilities

7. Testar antes de subir (não pular):

npm run build

Pacotes como postcss (CSS) e sharp (imagens) mexem com a parte visual — vale também rodar npm run dev e conferir o site localmente.

8. Subir a correção:

git add .
git commit -m "Corrige vulnerabilidades de dependencias"
git push

O commit deve mostrar 2 files changed (package.json + package-lock.json). Se mostrar "nothing to commit", a atualização não aconteceu de fato — voltar ao passo 5.

9. Conferir no painel: o scan de Security → Vulnerabilities não é instantâneo; pode levar algumas horas para zerar. A confirmação técnica imediata é o found 0 vulnerabilities do npm audit.

Rotina preventiva: rodar npm audit de tempos em tempos e acompanhar os alertas do painel da Hostinger ou do Dependabot no GitHub (mesma base). Vulnerabilidades novas em dependências são rotina em qualquer projeto, não sinal de erro de quem desenvolveu.

git push pede senha e recusa

O GitHub não aceita senha comum no terminal. Soluções:

• Usar o login pelo navegador quando a janela abrir (recomendado); ou
• Criar um token em GitHub → Settings → Developer settings → Personal access tokens e usá-lo no lugar da senha.

remote origin already exists ao rodar git remote add

Já existe uma conexão. Corrigir a URL com:

git remote set-url origin https://github.com/usuario/repositorio.git

Avisos "LF will be replaced by CRLF"

Não é erro. Normalização de fim de linha entre Windows e Linux/Mac. Ignorar.

Um arquivo que não deveria foi para o GitHub

1. Adicionar o caminho dele ao .gitignore.
2. Removê-lo do controle do Git (sem apagar do computador):

git rm --cached caminho/do/arquivo

3. Commitar e dar push.

Comandos usados uma única vez (configuração)

git --version                      # verificar instalação do Git
git config --global user.name "Seu Nome"
git config --global user.email "email@exemplo.com"
git init                           # só se git status der "not a git repository"
git branch -M main                 # renomear branch para main
git remote add origin URL          # conectar ao repositório do GitHub
git push -u origin main            # primeiro envio

Comandos do dia a dia (toda atualização)

git add .
git commit -m "descricao da mudanca"
git push

Comandos de consulta (não alteram nada)

git status       # o que está modificado / pendente
git remote -v    # a qual repositório a pasta está conectada
git log --oneline  # histórico de commits resumido
npm audit        # vulnerabilidades nas dependências do projeto
npm ls pacote    # onde/qual versão de um pacote está instalada

Documentação gerada a partir do processo real de configuração do projeto zumkai, em 23/07/2026.