Repository: diegomura/react-pdf

Stars: 16533

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview Copy Chapter

React-PDF is a library for creating PDF documents using React components. It's a monorepo using Lerna with independent versioning, Yarn 1.22.19 as the package manager, and all packages are ESM ("type": "module").

Common Commands Copy Chapter

yarn install              # Install dependencies and bootstrap monorepo
yarn build                # Build all packages (lerna run build)
yarn watch                # Watch mode - rebuilds on changes (for development)
yarn test                 # Run all tests (vitest)
yarn test packages/layout # Run tests for a specific package
yarn lint                 # Lint all packages (eslint packages)
yarn typecheck            # TypeScript type checking across all packages
yarn dev                  # Run example apps

To run a single test file: yarn vitest run path/to/test.ts

Architecture Copy Chapter

The library works as a pipeline: React components → reconciler → layout → render → PDF output.

Package Dependency Flow Copy Section

@react-pdf/renderer (main entry point - exports Document, Page, View, Text, etc.)
  ├── @react-pdf/reconciler    → React fiber reconciler that creates the internal element tree
  ├── @react-pdf/layout        → Resolves layout using Yoga (flexbox), handles pagination
  │     ├── @react-pdf/textkit     → Text measurement, line breaking, hyphenation
  │     ├── @react-pdf/stylesheet  → CSS-like style parsing and resolution
  │     ├── @react-pdf/image       → PNG/JPEG image fetching and parsing
  │     └── @react-pdf/font        → Font loading, registration, emoji support
  ├── @react-pdf/render        → Renders resolved layout tree to PDF drawing operations
  │     └── @react-pdf/pdfkit      → Low-level PDF generation (fork of pdfkit)
  └── @react-pdf/primitives    → Shared component type constants

Utility packages: @react-pdf/fns (helpers), @react-pdf/types (TypeScript types), @react-pdf/math (math utils), @react-pdf/svgkit (SVG support).

Build Copy Section

Each package uses Rollup for bundling. The renderer package produces multiple builds: server, browser, and minified variants. TypeScript is used throughout with strict mode.

Testing Copy Section

- Framework: Vitest with workspace configuration (vitest.workspace.js)
- Tested packages: fns, font, image, render, layout, svgkit, textkit, renderer, stylesheet, primitives
- Renderer has two test configs: main (fork pool) and browser (jsdom environment)
- Snapshot testing: jest-image-snapshot for visual regression tests
- Multi-React support: Tests can run against React 16, 17, 18, and 19 via environment variables

Writing Tests Copy Section

When making changes, always include tests. Add tests in the same location where tests already exist for the package being modified (e.g. packages/layout/tests/, packages/renderer/tests/).

Code Style Copy Section

- ESLint 9 with TypeScript parser, Prettier (single quotes), enforced via Husky pre-commit hooks
- Packages pdfkit, yoga, and examples are excluded from linting

Previewing PDFs Copy Chapter

To visually inspect generated PDFs during debugging, convert pages to images:

Using pdftoppm (preferred, often pre-installed via poppler-utils):

pdftoppm -png -r 200 document.pdf preview

This generates preview-1.png, preview-2.png, etc. at 200 DPI.

Fallback: PyMuPDF (if pdftoppm is unavailable):

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")

Versioning & Release Copy Chapter

Uses Changesets for versioning:

yarn changeset          # Create a changeset
yarn version-packages   # Apply changesets to bump versions
yarn release            # Publish to npm

README.md Copy Chapter

<p align="center">
<img src="https://user-images.githubusercontent.com/5600341/27505816-c8bc37aa-587f-11e7-9a86-08a2d081a8b9.png" height="280px">
<p align="center">React renderer for creating PDF files on the browser and server<p>
<p align="center">
<a href="https://www.npmjs.com/package/@react-pdf/renderer">
<img src="https://img.shields.io/npm/v/@react-pdf/renderer?style=flat&colorA=000000&colorB=000000" />
</a>
<a href="https://opencollective.com/react-pdf">
<img src="https://img.shields.io/opencollective/all/react-pdf?style=flat&colorA=000000&colorB=000000" />
</a>
<a href="https://github.com/diegomura/react-pdf/blob/master/LICENSE">
<img src="https://img.shields.io/github/license/diegomura/react-pdf?style=flat&colorA=000000&colorB=000000" />
</a>
<a href="https://blockchain.com/btc/address/bc1qj223udztpmt5dck46dw0yap08yum63ht56h90v">
<img src="https://img.shields.io/badge/BTC-f5f5f5?style=flat&colorA=000000&colorB=000000" />
</a>
<a href="https://blockchain.com/eth/address/0x4e1DB76bA0858BbCAa4DD804418D0D9EcF77B1cC">
<img src="https://img.shields.io/badge/ETH-f5f5f5?style=flat&colorA=000000&colorB=000000" />
</a>
</p>
</p>

Lost? Copy Chapter

This package is used to _create_ PDFs using React. If you wish to _display_ existing PDFs, you may be looking for react-pdf.

How to install Copy Chapter

yarn add @react-pdf/renderer

How it works Copy Chapter

import React from 'react';
import { Document, Page, Text, View, StyleSheet } from '@react-pdf/renderer';
// Create styles
const styles = StyleSheet.create({
  page: {
    flexDirection: 'row',
    backgroundColor: '#E4E4E4',
  },
  section: {
    margin: 10,
    padding: 10,
    flexGrow: 1,
  },
});
// Create Document Component
const MyDocument = () => (
  <Document>
    <Page size="A4" style={styles.page}>
      <View style={styles.section}>
        <Text>Section #1</Text>
      </View>
      <View style={styles.section}>
        <Text>Section #2</Text>
      </View>
    </Page>
  </Document>
);

Web. Render in DOM Web. Render in DOM')" title="Copy section prompt for LLMs"> Copy Section

import React from 'react';
import ReactDOM from 'react-dom';
import { PDFViewer } from '@react-pdf/renderer';
const App = () => (
  <PDFViewer>
    <MyDocument />
  </PDFViewer>
);
ReactDOM.render(<App />, document.getElementById('root'));

Node. Save in a file Node. Save in a file')" title="Copy section prompt for LLMs"> Copy Section

import React from 'react';
import ReactPDF from '@react-pdf/renderer';
ReactPDF.render(<MyDocument />, ${__dirname}/example.pdf);

Contributors Copy Chapter

This project exists thanks to all the people who contribute. Looking to contribute? Please check our [[contribute]](https://github.com/diegomura/react-pdf/blob/master/.github/CONTRIBUTING.md) document for more details about how to setup a development environment and submitting code.

<a href="https://github.com/diegomura/react-pdf/blob/master/.github/CONTRIBUTING.md"><img src="https://opencollective.com/react-pdf/contributors.svg?width=890" /></a>

Sponsors Copy Chapter

Thank you to all our sponsors! [Become a sponsors]

<a href="https://opencollective.com/react-pdf#sponsors" target="_blank"><img src="https://opencollective.com/react-pdf/sponsors.svg?width=890"></a>

Backers Copy Chapter

Thank you to all our backers! [Become a backer]

<a href="https://opencollective.com/react-pdf#backers" target="_blank"><img src="https://opencollective.com/react-pdf/backers.svg?width=890"></a>

License Copy Chapter

MIT © Diego Muracciole

---