# Repository: diegomura/react-pdf
# Stars: 16533

## CLAUDE.md

# CLAUDE.md

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

## Project Overview

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

```bash
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

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

### Package Dependency Flow

```
@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

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

- **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

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

- 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

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

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

```bash
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):**

```bash
pip install pymupdf
```

```python
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

Uses [Changesets](https://github.com/changesets/changesets) for versioning:

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


## README.md

<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?

This package is used to _create_ PDFs using React. If you wish to _display_ existing PDFs, you may be looking for [react-pdf](https://github.com/wojtekmaj/react-pdf).

## How to install

```sh
yarn add @react-pdf/renderer
```

## How it works

```jsx
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

```jsx
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

```jsx
import React from 'react';
import ReactPDF from '@react-pdf/renderer';

ReactPDF.render(<MyDocument />, `${__dirname}/example.pdf`);
```

## Contributors

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

Thank you to all our sponsors! [[Become a sponsors](https://opencollective.com/react-pdf#sponsors)]

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

## Backers

Thank you to all our backers! [[Become a backer](https://opencollective.com/react-pdf#backer)]

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

## License

MIT © [Diego Muracciole](http://github.com/diegomura)

---

[![](https://img.shields.io/npm/dt/@react-pdf/renderer.svg?style=flat)](https://www.npmjs.com/package/@react-pdf/renderer)