Skip to main content
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

OptionTypeDefaultDescription
apiKeystringprocess.env.PDFN_API_KEYAPI key for pdfn Cloud or custom server
baseUrlstringAuto-detectedServer URL (Cloud if apiKey set, otherwise localhost:3456)
timeoutnumber30000Default 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

ParameterTypeRequiredDescription
reactReactElementYesReact component to render and convert to PDF
debugDebugOptions | booleanNoEnable debug overlays (grid, margins, headers, breaks)
standardPDFStandardNoPDF/A or PDF/UA archival standard (pdfn Cloud only)
filenamestringNoFilename for Content-Disposition header
metadataobjectNoPDF document metadata (see below)
idempotencyKeystringNoDeduplication key — identical keys return cached results
timeoutnumberNoRequest timeout in ms (overrides client default)

​
Metadata fields

FieldTypeDescription
titlestringDocument title (shows in PDF readers)
authorstringAuthor name
subjectstringDocument subject
keywordsstringKeywords for search
creatorstringApplication 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

ParameterTypeRequiredDescription
reactReactElementYesReact component to render to HTML
debugDebugOptions | booleanNoEnable 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 },
});
OptionDescription
gridShows a baseline grid overlay
marginsHighlights page margins
headersShows header/footer regions
breaksMarks page break positions

​
Next steps

Troubleshooting

Error codes, common issues, and fixes

Self-Hosting

Run PDF generation on your own infrastructure