Node.js

A Guara Cloud suporta totalmente aplicacoes Node.js, incluindo frameworks como Express, Fastify, Next.js, NestJS e qualquer outro projeto baseado em Node.js.

Versoes suportadas

As seguintes versoes do Node.js sao detectadas automaticamente:

• Node.js 18 (LTS)
• Node.js 20 (LTS)
• Node.js 22 (Current)

A versao e detectada automaticamente pelo campo engines no seu package.json. Se nenhuma versao for especificada, a versao LTS mais recente sera utilizada.

{
  "engines": {
    "node": "20.x"
  }
}

Deploy com Dockerfile

Para ter controle total sobre o build, inclua um Dockerfile na raiz do seu repositorio.

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --production

COPY . .

EXPOSE 3000

CMD ["node", "server.js"]

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

const PORT = process.env.PORT || 3000;

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

app.listen(PORT, () => {
  console.log('Server running on port ' + PORT);
});

Deploy com Buildpack

Se o seu repositorio nao contiver um Dockerfile, a Guara Cloud detecta automaticamente seu projeto Node.js pela presenca de um arquivo package.json.

A deteccao automatica vai:

1. Detectar a versao do Node.js pelo campo engines no package.json
2. Detectar seu gerenciador de pacotes pelos arquivos de lock (package-lock.json, yarn.lock, pnpm-lock.yaml ou bun.lockb)
3. Instalar dependencias com o gerenciador de pacotes detectado
4. Executar o script build se estiver definido
5. Para apps servidor: iniciar usando o script start
6. Para sites estaticos (Astro, Vite, React, Angular): servir com Caddy automaticamente

Frameworks como Next.js, Nuxt, Astro, Vite, Angular, Remix e SvelteKit sao detectados e configurados automaticamente. Corepack e suportado para fixar a versao do gerenciador de pacotes.

Certifique-se de que seu package.json inclua um script start para aplicacoes servidor:

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

Configuracao de porta

Sua aplicacao deve escutar na porta configurada nas configuracoes do servico. O padrao e 3000, mas voce pode altera-lo a qualquer momento para corresponder a sua aplicacao.

const PORT = process.env.PORT || 3000;
app.listen(PORT);

Estrutura de projeto exemplo

my-node-app/
  package.json
  package-lock.json
  server.js
  src/
    routes/
    middleware/
  Dockerfile          # opcional — omita para usar Buildpack

Variaveis de ambiente

Estas variaveis de ambiente sao comumente usadas em deploys Node.js:

Erros comuns