Pacotes do Sistema

Alguns apps precisam de bibliotecas ou ferramentas do sistema operacional que não vêm instaladas por padrão. Use aptPackages no veloz.json para declará-las.

Como funciona

Adicione os pacotes no campo build.aptPackages do serviço (ou em defaults.build.aptPackages para aplicar a todos):

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

Os pacotes são instalados automaticamente durante o build, antes do npm install e do comando de build. Eles ficam disponíveis tanto no build quanto em runtime.

Guias por caso de uso

Puppeteer (headless Chrome)

O Puppeteer precisa do Chromium e de bibliotecas gráficas para renderizar páginas.

"build": {
  "aptPackages": [
    "chromium-browser",
    "fonts-noto",
    "fonts-noto-color-emoji",
    "libatk-bridge2.0-0",
    "libatk1.0-0",
    "libcups2",
    "libdrm2",
    "libgbm1",
    "libgtk-3-0",
    "libnss3",
    "libxcomposite1",
    "libxdamage1",
    "libxrandr2"
  ]
}

No seu código, aponte o Puppeteer para o Chromium do sistema:

const browser = await puppeteer.launch({
  executablePath: "/usr/bin/chromium-browser",
  args: ["--no-sandbox", "--disable-setuid-sandbox"],
});

E defina a variável de ambiente para pular o download do Chromium bundled:

veloz env set PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true

Playwright

O Playwright tem suas próprias dependências de sistema.

"build": {
  "aptPackages": [
    "libatk-bridge2.0-0",
    "libatk1.0-0",
    "libcups2",
    "libdrm2",
    "libgbm1",
    "libgtk-3-0",
    "libnss3",
    "libpango1.0-0",
    "libxcomposite1",
    "libxdamage1",
    "libxfixes3",
    "libxrandr2",
    "fonts-noto"
  ]
}

Configure o build para instalar os browsers do Playwright:

"build": {
  "command": "npx playwright install chromium --with-deps && npm run build",
  "aptPackages": [...]
}

FFmpeg (processamento de vídeo/áudio)

Para apps que processam mídia com fluent-ffmpeg, ffmpeg-static ou chamam ffmpeg diretamente:

"build": {
  "aptPackages": ["ffmpeg"]
}

No código:

import { execFile } from "node:child_process";
 
execFile("ffmpeg", ["-i", "input.mp4", "-vf", "scale=1280:720", "output.mp4"]);

Se também precisar de ffprobe para extrair metadados, ele já vem incluído no pacote ffmpeg.

Sharp (processamento de imagens)

O sharp usa libvips por baixo. Na maioria dos casos funciona sem pacotes extras, mas se o build falhar:

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

Canvas (node-canvas)

O pacote canvas precisa de bibliotecas gráficas nativas:

"build": {
  "aptPackages": [
    "libcairo2-dev",
    "libpango1.0-dev",
    "libjpeg-dev",
    "libgif-dev",
    "librsvg2-dev"
  ]
}

PDF (geração e manipulação)

Para gerar PDFs com pdf-lib, pdfkit ou puppeteer:

"build": {
  "aptPackages": ["fonts-noto"]
}

Para manipular PDFs existentes com poppler ou ghostscript:

"build": {
  "aptPackages": ["poppler-utils", "ghostscript"]
}

Para converter HTML em PDF com wkhtmltopdf:

"build": {
  "aptPackages": ["wkhtmltopdf", "fonts-noto"]
}

ImageMagick

Para manipulação de imagens com imagemagick ou gm:

"build": {
  "aptPackages": ["imagemagick", "ghostscript"]
}

O ghostscript é necessário se você precisa converter PDFs para imagens.

Banco de dados (drivers nativos)

Drivers nativos de banco de dados podem precisar de headers:

// PostgreSQL (pg-native)
"build": {
  "aptPackages": ["libpq-dev"]
}

// SQLite (better-sqlite3)
"build": {
  "aptPackages": ["libsqlite3-dev"]
}

LibreOffice (conversão de documentos)

Para converter documentos Office (.docx, .xlsx, .pptx) para PDF ou outros formatos:

"build": {
  "aptPackages": ["libreoffice", "fonts-noto"]
}

No código:

import { execFile } from "node:child_process";
 
execFile("libreoffice", [
  "--headless",
  "--convert-to",
  "pdf",
  "--outdir",
  "/tmp",
  "documento.docx",
]);

Referência de pacotes

Mídia

Browsers

Fontes

Gráficos e renderização

Banco de dados

Criptografia e rede

Utilitários

Usando em monorepos

Em monorepos, defina pacotes compartilhados em defaults e pacotes específicos em cada serviço:

{
  "defaults": {
    "build": {
      "aptPackages": ["fonts-noto"]
    }
  },
  "services": {
    "apps/web": {
      "build": {
        "aptPackages": ["chromium-browser", "libnss3", "libgbm1"]
      }
    },
    "apps/api": {
      "build": {
        "aptPackages": ["ffmpeg", "libvips-dev"]
      }
    }
  }
}

Os pacotes do serviço sobrescrevem os do defaults (não são mesclados). Se precisar dos pacotes do defaults mais os específicos, inclua todos no serviço.

Encontrando pacotes

• packages.ubuntu.com — Busca oficial de pacotes Ubuntu
• Erro no build? — O nome exato do pacote aparece no log de erro. Procure por E: Unable to locate package
• Pacotes -dev — Bibliotecas de desenvolvimento (headers). Necessários quando o npm precisa compilar addons nativos (ex: libvips-dev para sharp). Em runtime, apenas a lib base é necessária, mas não há problema em incluir a versão -dev

Próximos passos

• veloz.json — Referência completa de configuração
• Frameworks — Detecção automática de frameworks
• Troubleshooting — Resolver problemas de build