veloz.json

O veloz.json é o arquivo de configuração do seu projeto na Veloz. Ele é gerado automaticamente no primeiro veloz deploy e fica na raiz do repositório.

Exemplo básico

Para um projeto simples (um único app):

{
  "version": "1.0",
  "project": {
    "id": "proj_abc123",
    "name": "meu-app"
  },
  "services": {
    ".": {
      "id": "svc_xyz789",
      "name": "meu-app",
      "type": "web",
      "root": ".",
      "branch": "main",
      "build": {
        "command": "next build"
      },
      "runtime": {
        "command": "next start",
        "port": 3000
      }
    }
  }
}

Exemplo monorepo

Para projetos com múltiplos apps:

{
  "version": "1.0",
  "project": {
    "id": "proj_abc123",
    "name": "meu-projeto"
  },
  "defaults": {
    "build": {
      "nodeVersion": "22",
      "packageManager": "pnpm"
    },
    "resources": {
      "cpu": "500m",
      "memory": "512Mi"
    }
  },
  "services": {
    "apps/web": {
      "id": "svc_web123",
      "name": "web",
      "type": "web",
      "root": "apps/web",
      "build": {
        "command": "next build"
      },
      "runtime": {
        "command": "next start",
        "port": 3000
      }
    },
    "apps/api": {
      "id": "svc_api456",
      "name": "api",
      "type": "web",
      "root": "apps/api",
      "build": {
        "command": "tsc"
      },
      "runtime": {
        "command": "node dist/index.js",
        "port": 8080
      }
    }
  }
}

Referência de campos

version

Versão do schema. Sempre "1.0".

"version": "1.0"

project

Informações do projeto na Veloz.

services

Mapa de serviços. A chave é o caminho relativo do serviço (. para raiz, apps/web para monorepo).

defaults

Configurações padrão aplicadas a todos os serviços. Valores definidos no serviço individual sobrescrevem os defaults.

"defaults": {
  "type": "web",
  "branch": "main",
  "build": { ... },
  "runtime": { ... },
  "resources": { ... }
}

Configuração de serviço

Cada serviço aceita os seguintes campos:

Campos básicos

Tipos de Serviço

Workers são ideais para:

• Filas de jobs (BullMQ, Agenda)
• Cron jobs (node-cron)
• Consumidores de mensagens (Kafka, RabbitMQ)
• Pipelines de dados

{
  "services": {
    "workers/email": {
      "name": "email-worker",
      "type": "worker",
      "runtime": {
        "command": "npx tsx worker.ts"
      }
    }
  }
}

build

Configuração de build.

"build": {
  "command": "npm run build",
  "nodeVersion": "22",
  "packageManager": "pnpm",
  "outputDir": ".next",
  "aptPackages": ["ffmpeg", "libvips-dev"]
}

Pacotes do sistema (aptPackages)

Use aptPackages para instalar pacotes do sistema operacional que seu app precisa durante o build ou em runtime. Os nomes seguem a convenção de pacotes Ubuntu/Debian.

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

Regras de nomenclatura:

• Apenas letras minúsculas, números, ., + e -
• Mínimo 2 caracteres
• Deve começar com letra ou número
• Exemplos válidos: ffmpeg, libvips-dev, g++, python3.11
• Exemplos inválidos: FFmpeg, my package, pkg=1.0

Para a lista completa de pacotes e exemplos por caso de uso, veja o guia Pacotes do Sistema.

runtime

Configuração de execução.

"runtime": {
  "command": "node server.js",
  "port": 8080,
  "healthCheck": {
    "path": "/health",
    "interval": 15,
    "timeout": 5
  }
}

env

Declaração de variáveis de ambiente. Apenas as chaves e metadados ficam no veloz.json — os valores são definidos via CLI ou dashboard e nunca aparecem no arquivo.

"env": {
  "DATABASE_URL": {
    "description": "URL de conexão com o banco PostgreSQL",
    "required": true,
    "example": "postgres://user:pass@host:5432/db"
  },
  "REDIS_URL": {
    "description": "URL do Redis para cache",
    "required": false
  }
}

Isso serve como documentação viva das variáveis que o app precisa.

resources

Limites de CPU, memória e scaling.

"resources": {
  "instances": 2,
  "cpu": "1",
  "memory": "1Gi",
  "autoscale": {
    "enabled": true,
    "minInstances": 1,
    "maxInstances": 5,
    "targetCPU": 70
  }
}

Autoscale

Validação

O veloz.json é validado automaticamente em cada deploy. Para validar manualmente, use o JSON Schema:

{
  "$schema": "https://onveloz.com/schemas/veloz-config.schema.json"
}

Adicione o campo $schema no topo do arquivo para ter autocomplete e validação no VS Code e Cursor.

Dicas

• Não edite ids manualmente — eles são gerados pela Veloz e vinculam seu projeto/serviço ao servidor
• Commite o veloz.json — ele deve ser versionado no Git para que toda a equipe use a mesma config
• Use defaults em monorepos para evitar repetição entre serviços
• null = auto-detectar — use null em build.command ou runtime.command para deixar a Veloz detectar automaticamente

Próximos passos

• Pacotes do Sistema — Instalar ffmpeg, Puppeteer, sharp, etc.
• Monorepo — Deploy de múltiplos apps
• Configuração — Editar config via CLI
• Variáveis de Ambiente — Gerenciar secrets