robodev

DocsSign in

Guides

PDF

Turn an HTML string into a PDF Buffer with ctx.pdf.fromHtml on APIs, jobs, and sockets.

Getting startedOffline dev with robodev devConnect a frontendStartersDatabaseDomainsFile-based APIsAuthEmailPDFOrganizationsStorageSecretsPushJobsSocketsLLMAgentsDeployLocal developmentCLI reference

defineApi, defineJob, and defineSocket handlers receive ctx.pdf. Call fromHtml with an HTML string. Chromium runs in a Gotenberg sidecar — never in Starbase, never in tenant node_modules, and never on the robodev dev laptop. Auth hooks do not get a PDF client.

robodev/api/invoice.ts

import { defineApi } from "@robodev-ai/sdk";
export const get = defineApi({
  timeoutMs: 25_000,
  handler: async ({ pdf }) => {
    const body = await pdf.fromHtml("<html><body><h1>Invoice</h1></body></html>");
    return {
      contentType: "application/pdf",
      headers: { "content-disposition": 'attachment; filename="invoice.pdf"' },
      body,
    };
  },
});

Options

  • format — "A4" (default), "Letter", or "Legal".
  • landscape — default false.
  • margin — inches. A number applies to all four sides (default 0.39). A box can set top / right / bottom / left; missing sides use 0.39. Each side is 0–2 inclusive.
  • html must be a non-empty string after trim.

Timeouts

Handlers, jobs, and sockets default to 10s (max 30s via timeoutMs). The PDF call itself aborts at 15s. If the handler budget is 10s, handler_timeout 504 wins first — set timeoutMs: 25_000 when calling fromHtml. See File-based APIs (/docs/api), Jobs (/docs/jobs), and Sockets (/docs/sockets).

Hosted vs robodev dev

  • Hosted Starbase talks to Gotenberg on the Docker network. Gotenberg is not on Caddy and has no public port.
  • robodev dev does not run Chromium. It POSTs HTML to {STARBASE_URL}/internal/pdf (default https://robodev.povio.dev). No robodev auth and no linked project. Override STARBASE_URL=http://localhost:4000 to dogfood a local Starbase. The project .env STARBASE_URL is not read. See Offline dev (/docs/dev) and CLI env (/docs/cli).
  • Do not add puppeteer, playwright, pdfkit, or their -core packages to robodev/package.json — they are denied. Use ctx.pdf only.

Errors

  • invalid_request (400) — empty html or bad format / landscape / margin.
  • pdf_unconfigured (400) — GOTENBERG_URL is blank.
  • pdf_too_large (413) — HTML over 512 KiB or PDF over 8 MiB.
  • pdf_rate_limited (429) — per-project, per-IP, or platform in-flight cap.
  • pdf_failed (502) — Gotenberg down, non-PDF, network, 15s timeout, or hop unreachable.