Generate a PDF from Retool

Making the request

A REST API resource with a query on it, or a raw fetch inside a JavaScript query. Queries run on the Retool backend rather than in the browser, which is what keeps the API key off the client.

What it does with the response

Retool queries are built around returning data that components can bind to, and a PDF is not that. The path that works reliably is to keep the bytes out of the query result entirely: store the document at render time, return its URL, and give the URL to the component that needs it. Where a file genuinely has to reach the browser, Retool's download utility takes the content, a filename and a type and hands the user a file. Both routes work; the URL route is the one that does not put a multi-megabyte string through a query result and into the app's state.

Where the document can go afterwards

This is the part that differs most between platforms, and it is usually the reason one platform was chosen over another in the first place.

• a PDF viewer component, given a URL, which is the common case for an internal review tool
• a browser download, through the download utility, when a user clicks a button
• a database column, if you are storing a reference rather than the file
• an email or storage service, called from a second query rather than from the browser

The limit that bites in production

Queries run on the Retool backend, so the API key lives in a resource configuration rather than in the app. That is the right place for it. What it means in practice is that a self-hosted instance needs outbound network access to the render API, which is a firewall question that tends to surface late.

The shape that works

Render with storage on, return the document URL from the query, and bind the viewer component to that URL. The app state then holds a string rather than a file, which keeps the app responsive and keeps large payloads out of the query cache.

// A JavaScript query. Storage on, so what comes back is a reference
// rather than several megabytes going into the app's state.
const res = await fetch("https://api.pdfpipe.xyz/v1/pdf", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${environment.PDFPIPE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    html: buildInvoiceHtml.data,
    filename: `${invoiceNumber.value}.pdf`,
    store: true,
    options: { format: "A4", margin: "16mm" },
  }),
});

if (!res.ok) throw new Error(`Render failed: ${res.status}`);

const { id, url } = await res.json();

// Bind the PDF viewer component to this, rather than to a blob.
return { id, url };

The mistake people make

Returning the raw bytes from a query so a component can show them. The result goes into the app's state, the state is serialised, and an internal tool that felt instant now takes seconds to switch tabs. Keep files behind URLs and let the app hold references.

Frequently asked

Other platforms

Platforms of the same kind, and one from each of the other kinds.