/react-pdf

name: react-pdf
description:
  "Generates PDF documents using the React-PDF library (@react-pdf/renderer) with TypeScript and JSX.
  Use when creating PDFs, generating reports, invoices, forms, resumes, or any document that needs
  flexbox layout, SVG graphics, custom fonts, or professional typesetting. Prefer over Python PDF
  libraries (ReportLab, fpdf2) when layout complexity matters."
allowed-tools:
  - Bash
  - Read
  - Write
  - Grep
  - Glob

Generating PDFs with React-PDF

When to Use

• Generating PDF documents (reports, invoices, resumes, forms, certificates)
• Creating PDFs that need complex layouts (multi-column, grids, cards)
• Building PDFs with inline SVG graphics, charts, or icons
• Producing documents with custom Google Fonts or emoji
• Any PDF task where flexbox layout is easier than absolute coordinate math

When NOT to Use

• Reading or extracting text from existing PDFs — use `pdfplumber` or `pypdf` instead
• Filling existing PDF forms — use Python `pypdf` or `pdftk`
• Converting HTML to PDF — use Playwright or WeasyPrint instead
• Simple one-off text PDFs with no layout needs — a Python script may be simpler

CRITICAL REQUIREMENTS

1. **Fonts MUST be local files** - Remote font URLs (http/https) do NOT work. Always download fonts to local files before using them. 2. **Wrap async code in IIFE** - Top-level await causes errors. Always use `(async () => { ... })()` pattern. 3. **Disable hyphenation for custom fonts** - Custom fonts lack hyphenation dictionaries and may crash or break words incorrectly. Always call `Font.registerHyphenationCallback((word) => [word]);` after registering custom fonts.

Files

• `{baseDir}/skills/react-pdf/references/google-fonts.txt` - Metadata for ~65 popular Google Fonts with TrueType URLs. Each

line is a font variant in tab-separated format: `font name`, `style`, `category`, `weight`, `url`.

• `{baseDir}/skills/react-pdf/references/components.md` - Full component API reference and supported CSS properties
• `{baseDir}/skills/react-pdf/assets/example-template.tsx` - Minimal working example demonstrating fixed footers, page numbers,

and unbreakable content. Read this before starting to understand the basic patterns. Note: not all APIs are shown here — always refer to the docs and `{baseDir}/skills/react-pdf/references/components.md` for the full API.

Prerequisites

npm install react @react-pdf/renderer
npm install -D tsx @types/react

`tsx` runs TypeScript + JSX files directly via Node with no config — no `tsconfig.json` needed. It uses esbuild under the hood and handles JSX transformation automatically.

Core Components

• **Document**: Root component (metadata, settings)
• **Page**: Individual pages (A4, Letter, or custom dimensions)
• **View**: Container component (similar to div)
• **Text**: Text content, supports nesting for inline styling
• **Image**: Embed images (JPG, PNG, base64)
• **Link**: Clickable hyperlinks (external or internal)
• **Note**: Annotation notes
• **Canvas**: Freeform drawing with pdfkit methods
• **Svg**: Vector graphics (Circle, Rect, Path, Line, Polygon, etc.)
• **StyleSheet**: Create reusable styles

For full component props and CSS properties, see [references/components.md]({baseDir}/skills/react-pdf/references/components.md).

Basic Example

import React from "react";
import { Document, Page, Text, View, StyleSheet, renderToFile } from "@react-pdf/renderer";

const styles = StyleSheet.create({
  page: { flexDirection: "column", backgroundColor: "#ffffff", padding: 40 },
  title: { fontSize: 24, marginBottom: 20, fontWeight: "bold" },
  text: { fontSize: 12, lineHeight: 1.5 },
});

const MyDocument = () => (
  <Document>
    <Page size="A4" style={styles.page}>
      <View style={{ margin: 10, padding: 20 }}>
        <Text style={styles.title}>Document Title</Text>
        <Text style={styles.text}>Your content here</Text>
      </View>
    </Page>
  </Document>
);

(async () => {
  await renderToFile(<MyDocument />, "./output.pdf");
  console.log("PDF saved!");
})();

Running Scripts

PDF generation scripts use JSX, which Node cannot run directly. Use `tsx` to execute them:

npx tsx my-document.tsx

`npx tsx` works without installing tsx globally — it downloads on demand. If tsx is installed as a dev dependency (`npm install -D tsx`), it runs instantly without the npx download step.

Always wrap rendering in async IIFE:

// Good
(async () => {
  await renderToFile(<MyDocument />, "./output.pdf");
})();

// Bad - top-level await may fail
await renderToFile(<MyDocument />, "./output.pdf");

Previewing PDFs

To visually inspect generated PDFs, convert pages to images. Try `pdftoppm` first (often pre-installed), fall back to Python's PyMuPDF if unavailable.

**Option 1: pdftoppm (poppler-utils)** — preferred, no install needed in many environments:

pdftoppm -png -r 200 document.pdf preview
# → preview-1.png, preview-2.png, ...

**Option 2: PyMuPDF (Python)** — fallback if pdftoppm is not available:

pip install pymupdf

import fitz

doc = fitz.open("document.pdf")
for i, page in enumerate(doc):
    pix = page.get_pixmap(dpi=200)
    pix.save(f"page-{i+1}.png")

Rendering Methods

import { renderToFile, renderToBuffer } from "@react-pdf/renderer";

// To file
(async () => {
  await renderToFile(<MyDocument />, "./document.pdf");
})();

// To buffer
(async () => {
  const buffer = await renderToBuffer(<MyDocument />);
})();

Styling

Three methods: `StyleSheet.create()`, inline objects, or mixed arrays.

const styles = StyleSheet.create({ container: { padding: 20 } });

<View style={styles.container} />
<View style={{ padding: 20 }} />
<View style={[styles.container, { marginTop: 10 }]} />

Supported Units

`pt` (default, 72 DPI), `in`, `mm`, `cm`, `%`, `vw`, `vh`

Common Style Properties

{
  // Flexbox
  flexDirection: "row", ju