Início rápido — Node.js

Publique uma aplicação Node.js funcional na Zenifra usando a origem Repositório Git com o provedor GitHub.

Pré-requisitos

Node.js 20+ instalado localmente
uma conta no GitHub, com o GitHub App da Zenifra instalado e conectado à organização (veja Como conectar o GitHub)
acesso ao console da Zenifra

Nota: Este quickstart usa o GitHub. O mesmo fluxo vale para um repositório Forgejo; veja Implantação via Forgejo.

Passo 1 — Crie sua aplicação

mkdir hello-zenifra
cd hello-zenifra
npm init -y
npm install express

Crie index.js:

const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.json({ message: 'Hello from Zenifra!', time: new Date().toISOString() });
});

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Server running on port ${PORT}`);
});

Atualize o package.json com um comando de start:

{
  "scripts": {
    "start": "node index.js"
  }
}

Confirme que package-lock.json foi gerado e está sincronizado com package.json antes de publicar o projeto. Os dois arquivos devem ser enviados ao Git no diretório raiz da aplicação.

Valide a instalação com a mesma versão do Node.js que será selecionada na Zenifra:

npm ci
npm start

Passo 2 — Publique no GitHub

Crie um repositório no GitHub e envie o código:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/your-username/hello-zenifra.git
git push -u origin main

Passo 3 — Crie o projeto na Zenifra

No console, escolha Origem do Projeto como Repositório Git e, em Provedor Git, selecione GitHub.
Selecione o repositório e a branch main.
Em Runtime, selecione Node.js e escolha a Versão.
No campo Porta, informe 3000.
Em Comando Build, use npm run build se o package.json tiver um script build; caso contrário, deixe o campo vazio.
Em Comando Start, use npm start.
Se desejar atualização automática por push, selecione Automático por branch em Modo de deploy.
Clique em Criar Projeto.

Passo 4 — Valide o deploy

Abra a URL em *.clients.zenifra.com. Você verá:

{ "message": "Hello from Zenifra!", "time": "2026-04-30T14:00:00.000Z" }

Também teste /health para confirmar que a aplicação está pronta.

Com Automático por branch selecionado, a Zenifra publica uma nova versão a cada push para main.

Solução de problemas

Problema	Solução
A aplicação não inicia	Verifique se o valor configurado no campo Porta corresponde à porta em que sua aplicação realmente escuta
URL não responde	Confirme se a aplicação escuta em `0.0.0.0`
`package-lock.json` ausente ou inválido	Gere o arquivo com npm, confirme que ele está no Git ao lado do `package.json` e valide com `npm ci`
Lockfile fora de sincronia	Execute `npm install`, confirme o `package-lock.json` atualizado no Git e repita `npm ci`
Projeto usa pnpm ou Yarn	Consulte os requisitos atuais de dependências Node.js antes de adaptar o projeto; o `pre-build` só roda depois da instalação inicial com npm
Build falhou em outro comando	Revise os Logs de Build e confirme localmente `npm run build`, quando houver, e `npm start`