Frameworks e Linguagens

A Veloz usa Nixpacks para detectar seu framework e linguagem automaticamente. Não precisa configurar nada — basta rodar veloz deploy.

Se o seu projeto tem requisitos complexos de build, você pode usar um nixpacks.toml para personalizar ou até um Dockerfile próprio — veja Nixpacks vs Dockerfile.

Linguagens suportadas

A Veloz suporta 25+ linguagens via Nixpacks. Cada uma é detectada automaticamente pelo arquivo de projeto (package.json, go.mod, Cargo.toml, etc).

Tier 1 — Detecção automática completa

Tier 2 — Suportado via Nixpacks

Tier 3 — Via nixpacks.toml

Qualquer linguagem pode ser configurada manualmente com um nixpacks.toml na raiz do projeto:

[phases.setup]
nixPkgs = ["lua5_4", "nodejs_22"]
 
[phases.build]
cmds = ["make build"]
 
[start]
cmd = "lua main.lua"

Frameworks Node.js

Aplicações Web (SSR)

Frameworks que rodam um servidor em produção.

Sites Estáticos (SPA / SSG)

Frameworks que geram arquivos estáticos no build. Servidos automaticamente via Caddy.

Node.js genérico

Se nenhum framework específico for detectado mas existirem scripts build ou start no package.json, a Veloz trata como um projeto Node.js genérico:

• Com script start → Serviço Web (porta 3000)
• Sem script start → Site Estático (output dist)

Frameworks Python

Frameworks PHP

Frameworks Ruby

Frameworks Elixir

Como funciona a detecção

1. Nixpacks analisa os arquivos do projeto (package.json, go.mod, Cargo.toml, etc)
2. Identifica a linguagem e framework automaticamente
3. Gera um Dockerfile otimizado com as dependências corretas
4. Build e start commands são configurados automaticamente

Ordem de prioridade (Node.js)

Se seu projeto tem múltiplas dependências (ex: next + express), a Veloz usa o primeiro match na lista. Next.js tem prioridade sobre Express.

Package managers

A Veloz detecta o package manager pelo lockfile:

Os comandos de build e start são adaptados automaticamente:

# npm
npm run build && npm start
 
# pnpm
pnpm run build && pnpm start
 
# yarn
yarn build && yarn start
 
# bun
bun run build && bun run start

Customizando

Se a detecção automática não funcionar para o seu caso, você pode definir os comandos manualmente:

Via CLI

veloz config set --build-command "npm run build:custom" --start-command "node server.js" --port 8080

Via veloz.json

{
  "services": {
    ".": {
      "build": {
        "command": "npm run build:custom"
      },
      "runtime": {
        "command": "node server.js",
        "port": 8080
      }
    }
  }
}

Via nixpacks.toml

Para linguagens que não são Node.js, ou configurações avançadas:

[phases.setup]
nixPkgs = ["python311", "poetry"]
 
[phases.build]
cmds = ["poetry install", "python manage.py collectstatic"]
 
[start]
cmd = "gunicorn myapp.wsgi:application --bind 0.0.0.0:3000"

No primeiro deploy

Se você recusar a confirmação automática, a CLI permite editar todos os campos:

? Confirmar e fazer deploy? (Y/n) n

  Build command: (npm run build) npm run build:custom
  Start command: (npm start) node server.js
  Port: (3000) 8080

Variáveis de ambiente

A Veloz detecta variáveis de ambiente automaticamente a partir de:

• .env.example
• .env.sample
• .env.local.example
• .env

No primeiro deploy, a CLI lista as variáveis encontradas e pergunta se você quer preenchê-las. As variáveis também são injetadas automaticamente no Dockerfile durante o build.

Dependências do sistema

Alguns frameworks e bibliotecas precisam de pacotes do sistema para funcionar. Use aptPackages no veloz.json:

"build": {
  "aptPackages": ["ffmpeg", "libvips-dev"]
}

Ou via nixpacks.toml:

[phases.setup]
nixPkgs = ["ffmpeg", "imagemagick"]
aptPkgs = ["libvips-dev"]

Casos comuns:

Para a lista completa e exemplos detalhados, veja Pacotes do Sistema.

Próximos passos

• Primeiro Deploy — Faça seu primeiro deploy
• veloz.json — Referência de configuração
• Pacotes do Sistema — Instalar dependências nativas
• Monorepo — Deploy de múltiplos apps