← todos os posts
Tutorial 9 min de leitura

"Localhost, terminal e \"onde está meu app\": as 15 etapas que o tutorial pula, uma por uma"

Do app que só existe na plataforma até ele rodando no seu computador, etapa por etapa, com o nome traduzido e o que aparece na tela.

"Você precisa rodar comandos no terminal. Precisa de Node.js instalado. Precisa entender o que é localhost. Pra quem não é programador, é uma parede."

"Pulam 15 etapas que consideram óbvias."

As duas são do mesmo programador brasileiro, num fórum, em fevereiro de 2026, descrevendo o que acontece com quem não é da área quando tenta tirar o app da plataforma. Eu já reclamei disso e já ensinei a publicar sem terminal. Este é o tutorial que faltava: do app que só existe no Lovable (ou no Bolt, ou no Replit) até ele rodando no seu computador, quinze etapas, cada uma com o nome traduzido e o que aparece na tela.

Por que fazer isso, se o app já funciona na plataforma? Porque é o primeiro item do portão da fase Construa: o código roda onde você manda. Enquanto só roda lá, cada mudança custa crédito e cada travamento é deles. Não é pra você programar. É pra você ter a chave. Uso o Lovable como exemplo; nas outras o caminho muda pouco.

Antes: o que é o terminal, e por que ele assusta

O terminal é uma janela onde, em vez de clicar, você digita uma instrução e aperta Enter. Só isso. Parece hostil porque não tem botão nem menu, e quando dá certo muitas vezes não diz nada. Silêncio, no terminal, quase sempre é sucesso. Ninguém avisa, e é a causa de metade das desistências.

Duas regras pra toda etapa: leia a última linha do que apareceu, é ali que mora a resposta; e texto amarelo é aviso, não erro. Erro de verdade vem em vermelho, com Error ou ERR.

As quinze etapas

1. Ligar o projeto ao GitHub

Nome traduzido: GitHub é o site onde se guarda cópia de código; repositório é a pasta do seu projeto lá dentro.

No Lovable: configurações do projeto → Git → GitHub → Add connection, autorize e escolha em qual conta o repositório nasce. A documentação diz que a sincronização é nos dois sentidos: "mudanças feitas no Lovable sincronizam com o GitHub" e "mudanças enviadas ao GitHub sincronizam de volta". O que você fizer na sua máquina volta pra plataforma.

O que aparece: no GitHub, um repositório novo com o nome do projeto, marcado como Private.

2. Instalar o Node

Nome traduzido: Node.js é o programa que faz o código do seu app rodar fora do navegador. Sem ele, os comandos das etapas 9 e 10 não existem.

Baixe em nodejs.org a versão marcada LTS (suporte longo; em setembro de 2026 é a 24). Não a Current. Instalador comum: Avançar, Avançar, Concluir.

O que aparece: nada. Node não abre janela. Você confere na etapa 5.

3. Instalar o Git

Nome traduzido: Git é o programa que copia o repositório pra sua máquina e marca os pontos de retorno. No Mac costuma já existir. No Windows, baixe em git-scm.com e aceite o padrão.

Se o terminal te apavora, o GitHub Desktop faz as etapas 7 e 15 com botão. Prefiro que você aprenda as linhas, mas o botão é saída honesta.

4. Abrir o terminal

No Mac: Aplicativos → Utilitários → Terminal. No Windows: menu Iniciar, digite PowerShell ou Terminal.

O que aparece: uma janela quase vazia com uma linha terminando em $, % ou >, e o cursor piscando. Esse é o prompt: ele está dizendo "pode digitar".

5. Conferir que o Node entrou

Digite node -v e Enter.

O que aparece: v24. e mais números. Se aparecer command not found ou não é reconhecido, feche o terminal e abra de novo: ele foi aberto antes da instalação e ainda não sabe que o Node existe.

6. Ir pra pasta certa

O terminal está sempre "em algum lugar" do seu computador, como o Explorador de arquivos. cd significa change directory, mudar de pasta. Digite cd Documents (ou cd Documentos).

O que aparece: nada. Silêncio é sucesso. Se vier No such file or directory, o nome está errado; ls (Mac) ou dir (Windows) mostra o que existe onde você está.

7. Trazer o código

No GitHub, no seu repositório, botão verde Code → aba HTTPS → copie o endereço. No terminal:

git clone <cole o endereço aqui>

O que aparece: Cloning into 'nome-do-projeto'..., uns percentuais, e o prompt de volta. Agora existe uma pasta com o nome do projeto dentro de Documentos. O README que o Lovable coloca em todo projeto exportado lista este comando e os três seguintes.

8. Entrar na pasta

cd nome-do-projeto

Com o nome da etapa 7. Silêncio de novo. Tudo daqui pra frente é feito de dentro dessa pasta; fechou o terminal e abriu outro, repete o cd.

9. Instalar as peças

npm i

Nome traduzido: o seu app usa centenas de pedaços de código de outras pessoas. npm i (de install) baixa todos. Demora de um a cinco minutos.

O que aparece: uma barra andando, no fim added 400 packages (o número varia) e, quase sempre, 5 vulnerabilities (2 moderate, 3 high). Isso é normal: aviso de que alguma peça tem versão mais nova. Não rode o npm audit fix --force que ele sugere; troca versões sem perguntar e é a forma mais rápida de quebrar o que funcionava. Se a última linha é o prompt, deu certo.

10. Ligar o app

npm run dev

O que aparece: algumas linhas e, destacada, uma assim:

➜  Local:   http://localhost:8080/

Projeto do Lovable usa a porta 8080; o padrão da ferramenta por baixo (o Vite) é 5173, outras plataformas usam 3000. Não importa o número, importa a linha Local:. Se a porta estiver ocupada, a documentação do Vite diz que ele "tenta automaticamente a próxima disponível": leia o número que apareceu, não o que esperava.

11. Abrir o endereço

Cole http://localhost:8080 no navegador.

Nome traduzido: localhost é o seu próprio computador. O endereço quer dizer "abra o que está rodando aqui mesmo, na porta 8080". Porta é o número da sala: o computador pode ter vários programas atendendo, cada um numa. Ninguém mais na internet enxerga isso. Não está publicado. É o seu app, rodando na sua máquina, pra você.

O que aparece: o seu app. Igual ao da plataforma.

12. Se ficou branco ou deu erro

Duas causas, na ordem. A primeira: falta uma chave. As variáveis de ambiente (valores guardados fora do código, já traduzi aqui) nem sempre vêm no clone. No Lovable, as públicas (prefixo VITE_) vêm num arquivo chamado .env na pasta do projeto; de outra plataforma, pode faltar. Se o arquivo não existir, o post de publicar mostra como listar quais chaves o projeto lê.

A segunda: leia o terminal. O erro está lá, em vermelho. Copie a linha inteira e cole pra IA com "me explique em português o que esta linha diz, e não mude nada ainda".

13. O aviso que ninguém dá: localhost não é ambiente de teste

É o mais importante do post. O app na sua máquina fala com o mesmo banco que o app publicado, porque a chave no .env é a mesma. Cadastrou um cliente de teste em localhost? Apareceu na produção. Apagou? Apagou de verdade.

Rodar na máquina resolve "onde está meu app". Não resolve "onde eu experimento sem tocar no dado do cliente": isso é o terceiro item do portão da fase Construa, teste e produção separados, e é assunto de outro post. Por hoje: não apague nada em localhost achando que é brincadeira.

14. Desligar, e ligar de novo

Feche o terminal e o app some do navegador. Não é bug: npm run dev é um programa que fica rodando enquanto a janela existe. Pra parar de propósito, Ctrl+C. Pra voltar: abrir o terminal, cd até a pasta, npm run dev. Três linhas, pra sempre.

15. Fazer uma mudança e guardar o ponto de retorno

Instale um editor de código (VS Code é gratuito; o Cursor é o mesmo programa com IA dentro) e abra a pasta do projeto nele. Vai parecer "o Word projetado para alienígenas", como disse o mesmo programador do começo, e tudo bem: você só precisa da pasta src, e de saber que salvar um arquivo com o app ligado atualiza o navegador sozinho.

Mude um texto qualquer numa tela, salve, veja mudar em localhost. Depois, no terminal, três linhas:

git add -A
git commit -m "muda o texto do botão"
git push

Nome traduzido: commit é tirar a foto deste momento; a mensagem entre aspas é o nome da foto. push manda a foto pro GitHub, e o Lovable puxa de lá sozinho. Você acabou de fazer, com as próprias mãos, o ponto de retorno que a plataforma cobrava crédito pra fingir que tinha.

As cinco mensagens que mais travam gente

  • command not found / não é reconhecido — programa não instalado, ou terminal aberto antes da instalação. Feche e abra.
  • No such file or directory — você não está na pasta que pensa. ls ou dir pra ver onde está.
  • Cannot find module — pulou a etapa 9, ou fechou o terminal no meio dela. npm i de novo.
  • EACCES / permission denied — o sistema não deixou escrever numa pasta protegida. A etapa 6 foi pra um lugar errado; volte pra Documentos.
  • port 8080 is already in use — um npm run dev antigo ainda está aberto em outra janela. Feche ele, ou use o número que o novo escolheu.

Nenhuma dessas cinco é "você não tem perfil". São as frases que todo programador levou uma semana pra aprender e nunca mais escreveu.

O que você tem agora

O código na sua máquina, rodando, com ponto de retorno. Passou o primeiro item do portão. Faltam três na mesma fase: o banco no seu nome, teste separado de produção, e o retorno que inclua os dados, não só o código. Depois vem o que a plataforma ainda segura e, só então, publicar no seu domínio.

Quinze etapas que ninguém escreveu, agora escritas. O que não cabe aqui é o que muda de projeto pra projeto: a chave que faltou no seu, o erro em vermelho que é só seu. Isso se resolve com alguém olhando a sua tela, e é o que a mentoria faz. Mas a parede desta semana você derruba sozinho, hoje.

Fontes