Generate & Render

Import pdfn from @pdfn/react and create a client. It auto-detects your environment — local dev server, pdfn Cloud, or a custom endpoint.

Client setup

import { pdfn } from '@pdfn/react';

const client = pdfn();

pdfn() reads the PDFN_API_KEY environment variable automatically. If set, it connects to pdfn Cloud. If not, it falls back to localhost:3456 for local development.

Client options

Option	Type	Default	Description
`apiKey`	`string`	`process.env.PDFN_API_KEY`	API key for pdfn Cloud or custom server
`baseUrl`	`string`	Auto-detected	Server URL (Cloud if apiKey set, otherwise `localhost:3456`)
`timeout`	`number`	`30000`	Default request timeout in ms

// Shorthand — API key string
const client = pdfn('pdfn_live_...');

// Full config
const client = pdfn({
  apiKey: process.env.PDFN_API_KEY,
  baseUrl: 'https://my-pdfn-server.com',
  timeout: 60000,
});

generate()

Generates a PDF and returns a buffer. Requires a running pdfn server (local dev server or pdfn Cloud).

const { data, error } = await client.generate({
  react: <Invoice data={invoiceData} />,
});

if (error) {
  console.error(error.code, error.message);
  return;
}

fs.writeFileSync('invoice.pdf', data.buffer);

Generate parameters

Parameter	Type	Required	Description
`react`	`ReactElement`	Yes	React component to render and convert to PDF
`debug`	`DebugOptions \| boolean`	No	Enable debug overlays (grid, margins, headers, breaks)
`standard`	`PDFStandard`	No	PDF/A or PDF/UA archival standard (pdfn Cloud only)
`filename`	`string`	No	Filename for `Content-Disposition` header
`metadata`	`object`	No	PDF document metadata (see below)
`idempotencyKey`	`string`	No	Deduplication key — identical keys return cached results
`timeout`	`number`	No	Request timeout in ms (overrides client default)

Metadata fields

Field	Type	Description
`title`	`string`	Document title (shows in PDF readers)
`author`	`string`	Author name
`subject`	`string`	Document subject
`keywords`	`string`	Keywords for search
`creator`	`string`	Application that created the document

These fields override the matching props on <Document>. If you set title on both <Document> and metadata, the metadata value wins.

Generate response

// Success
{
  data: {
    buffer: Buffer,          // PDF file contents
    id: string,              // Generation ID
    metrics: {
      durationMs: number,    // Time to generate
      sizeBytes: number,     // PDF file size
    },
    standard?: string,       // PDF/A standard (if requested)
    createdAt: string,       // ISO timestamp
  },
  error: null
}

// Error
{ data: null, error: PdfnError }

Examples

React component with options:

const { data, error } = await client.generate({
  react: <Invoice number="INV-001" customer="Acme Corp" />,
  filename: 'invoice-001.pdf',
  metadata: { title: 'Invoice #001', author: 'Acme Corp' },
  standard: 'PDF/A-2b',
});

With debug overlays (development):

const { data, error } = await client.generate({
  react: <Invoice />,
  debug: { grid: true, margins: true },
});

With idempotency key (deduplication):

const { data, error } = await client.generate({
  react: <Invoice id={order.id} />,
  idempotencyKey: `invoice-${order.id}`,
});

render()

Renders a React component to a self-contained HTML string. Runs locally — no server required. Use this when you want to preview HTML or convert to PDF with your own Puppeteer/Playwright setup (see Self-Hosting).

const { data, error } = await client.render({
  react: <Invoice data={invoiceData} />,
});

if (error) {
  console.error(error.message);
  return;
}

console.log(data.html); // Full HTML document

Render parameters

Parameter	Type	Required	Description
`react`	`ReactElement`	Yes	React component to render to HTML
`debug`	`DebugOptions \| boolean`	No	Enable debug overlays

Render response

// Success
{
  data: {
    html: string,            // Self-contained HTML document
    metrics: {
      totalTime: number,     // Render time in ms
    },
  },
  error: null
}

// Error
{ data: null, error: PdfnError }

Debug options

Both generate() and render() accept a debug option for development overlays:

// Enable all overlays
client.render({ react: <Invoice />, debug: true });

// Enable specific overlays
client.render({
  react: <Invoice />,
  debug: { grid: true, margins: true, headers: false, breaks: false },
});

Option	Description
`grid`	Shows a baseline grid overlay
`margins`	Highlights page margins
`headers`	Shows header/footer regions
`breaks`	Marks page break positions

Getting Started

Core

Guides

Generate & Render

Client setup

Client options

generate()

Generate parameters

Metadata fields

Generate response

Examples

render()

Render parameters

Render response

Debug options

Next steps

Troubleshooting

Self-Hosting

​Client setup

​Client options

​generate()

​Generate parameters

​Metadata fields

​Generate response

​Examples

​render()

​Render parameters

​Render response

​Debug options

​Next steps

Troubleshooting

Self-Hosting

Client setup

Client options

generate()

Generate parameters

Metadata fields

Generate response

Examples

render()

Render parameters

Render response

Debug options

Next steps