---
title: "DocRaptor"
description: "Use DocRaptor for MainSDK PDF rendering - hosted HTML to PDF, setup, main.yaml, test documents and swapping from the built-in renderer."
section: "integrations"
canonical: "https://mainsdk.dev/docs/integrations/docraptor"
updated: "2026-10-28"
---

# DocRaptor

> Use DocRaptor for MainSDK PDF rendering - hosted HTML to PDF, setup, main.yaml, test documents and swapping from the built-in renderer.

Canonical: https://mainsdk.dev/docs/integrations/docraptor · Updated: 2026-10-28

DocRaptor is a hosted service that turns HTML and CSS into PDF documents. The `docraptor` driver behind [`pdf`](https://mainsdk.dev/docs/interfaces/pdf) renders your templates there instead of in the built-in renderer. Pick it when your documents need print layout features the built-in renderer doesn't cover.

> **Note:** `pdf` has no spec yet. The calls and options on this page are provisional, taken from the catalog and the product requirements, and may change when the spec lands.

## Interfaces it serves

### PDF documents (`pdf`)

- Status: Preview · ships as a beta API
- Driver: `docraptor` (DocRaptor)
- Docs: https://mainsdk.dev/docs/interfaces/pdf.md

```yaml
pdf:
  driver: docraptor
```

Swap to another provider: `builtin`, `gotenberg`, `documenso`.

## Before you start

1. Create a DocRaptor account and copy its API key.
2. Store the key in your secrets manager.

## Configure

```yaml title="main.yaml"
pdf:
  driver: docraptor
```

Hosted `pdf` drivers take their keys as `secret:` references (for example `secret:DOCRAPTOR_API_KEY`); the key field name is not defined yet [TBD].

## Use it

```ts title="lib/invoice.ts"
import { pdf } from "mainsdk";

export async function invoiceFor(order: { id: string }, user: { locale: string }) {
  return pdf.render("invoice", { order, locale: user.locale });
}
```

## Local development and testing

`pdf` is phase 1, so `createTestApp()` from `@mainsdk/testing` renders on its in-memory fake with no hosted service. DocRaptor offers watermarked test documents for trying real renders. `chaos.on("pdf", { outage: true })` simulates DocRaptor being down.

## What MainSDK adds on top

- Text, money and dates localised through [`i18n`](https://mainsdk.dev/docs/interfaces/i18n); a missing translation fails the `i18n` check, not the reader.
- The same `pdf.render()` call on every driver.

See [PDF documents](https://mainsdk.dev/docs/interfaces/pdf).

## Limits and notes

- `pdf` has no spec; the DocRaptor driver is listed in the catalog and requirements.
- DocRaptor receives the document data, which often holds personal data. Check its regions against your MainSDK data region (US, EU or India).
- Store generated documents through [`files`](https://mainsdk.dev/docs/interfaces/files), not in DocRaptor.

## Swap to or from it

```yaml title="main.yaml"
pdf:
  driver: docraptor   # was builtin
```

Rendering holds no state, but whether templates need changes between renderers is still open.

## FAQ

**Do I need DocRaptor to render PDFs?** No. The built-in renderer is the default.

## Next

- [PDF documents](https://mainsdk.dev/docs/interfaces/pdf)
- [Built in](https://mainsdk.dev/docs/integrations/built-in) and [Documenso](https://mainsdk.dev/docs/integrations/documenso)