# PDFx

> Build PDFs with React. No magic. Just components.

PDFx is an open-source React PDF component library that follows the shadcn/ui model: run the CLI to add a component, the source lands in your project, and you own it fully. No runtime PDFx package dependency, no version lock-in, MIT licensed.

Website: https://pdfx.akashpise.dev
GitHub: https://github.com/akii09/pdfx
npm (CLI): https://www.npmjs.com/package/pdfx-cli
License: MIT

## Quick Start

```bash
# Initialize your project (creates pdfx.json + theme)
npx pdfx-cli init

# Add a component — source is copied into YOUR codebase
npx pdfx-cli add table

# Add all components at once
npx pdfx-cli add --all

# List available components
npx pdfx-cli list

# Add a full pre-built block (invoice, report)
npx pdfx-cli block add invoice-modern
npx pdfx-cli block list
```

## What is PDFx?

PDFx provides 24 production-ready PDF components built on top of `@react-pdf/renderer`. Instead of importing from a package you cannot customise, you copy the component source directly into your project via the CLI and modify it however you need.

Key traits:
- **No runtime dependency** — after `pdfx add`, you own the file
- **Full TypeScript** — every component is typed with PDFComponentProps
- **Theme system** — nine built-in presets, visual Theme Builder, or define your own
- **CLI-driven** — `pdfx add`, `pdfx list`, `pdfx diff`, `pdfx theme`, `pdfx block` commands
- **AI-ready docs** — MCP Server and Skills File docs for LLM-assisted workflows
- **MIT licensed** — free forever, no cost

## Theme System

PDFx ships nine built-in themes. Switch with:

```bash
npx pdfx-cli theme switch modern
```

Themes: `professional` (default), `modern`, `minimal`, `executive`, `corporate`, `elegant`, `vivid`, `forest`, `blueprint`

Visual theming is also available at:

- Theme Builder: https://pdfx.akashpise.dev/theme-builder

Each theme exports a token object used inside components:
```ts
const theme = usePdfxTheme();
// theme.colors.primary, theme.spacing.md, theme.typography.body.fontSize, ...
```

## Component Reference

All 24 components by category:

### Typography
- **Heading** (`/components/heading`) — H1–H6 hierarchy with theme-aware sizing
- **Text** (`/components/text`) — Inline and block text with typographic variants
- **Link** (`/components/link`) — Clickable hyperlinks inside PDF documents

### Layout
- **Stack** (`/components/stack`) — Flexbox container (row or column)
- **Section** (`/components/section`) — Top-level document section with optional title
- **Card** (`/components/card`) — Bordered content card with header and body
- **Divider** (`/components/divider`) — Horizontal rule with configurable weight and color
- **PageBreak** (`/components/page-break`) — Force content onto a new PDF page
- **KeepTogether** (`/components/keep-together`) — Prevent a group from splitting across pages
- **PageHeader** (`/components/page-header`) — Fixed header on every page with logo, title, subtitle
- **PageFooter** (`/components/page-footer`) — Fixed footer with contact info or legal copy
- **PageNumber** (`/components/page-number`) — Dynamic page X of Y counter
- **Watermark** (`/components/watermark`) — Diagonal or centered text watermark on every page

### Data
- **Table** (`/components/table`) — Composable table with rows and cells
- **DataTable** (`/components/data-table`) — Data-driven table from an object array; columns auto-inferred
- **List** (`/components/list`) — Ordered and unordered lists with custom bullet styles
- **Badge** (`/components/badge`) — Small inline label for statuses, tags, or categories
- **KeyValue** (`/components/key-value`) — Two-column label/value pairs (perfect for invoice metadata)
- **Alert** (`/components/alert`) — Info, warning, error, and success callout boxes

### Visual
- **Image** (`/components/pdf-image`) — Embed raster images with sizing and aspect-ratio control
- **Graph** (`/components/graph`) — SVG bar, line, area, pie, donut, and horizontal-bar charts
- **QRCode** (`/components/qrcode`) — Scannable QR codes as native PDF vector graphics

### Forms
- **Form** (`/components/form`) — Labeled field groups for invoices, contracts, and agreements
- **Signature** (`/components/signature`) — Signature block with name, role, date, and underline

## Pre-built Blocks

Blocks are complete multi-component PDF documents you can add with a single command.

### Invoice Blocks
```bash
npx pdfx-cli block add invoice-classic
npx pdfx-cli block add invoice-modern
npx pdfx-cli block add invoice-minimal
npx pdfx-cli block add invoice-corporate
npx pdfx-cli block add invoice-creative
npx pdfx-cli block add invoice-consultant
```

### Report Blocks
```bash
npx pdfx-cli block add report-financial
npx pdfx-cli block add report-marketing
npx pdfx-cli block add report-operations
npx pdfx-cli block add report-security
```

## CLI Command Reference

| Command | Description |
|---|---|
| `pdfx init` | Scaffold config + theme in your project |
| `pdfx add <component>` | Copy component source into your project |
| `pdfx add --all` | Copy all components at once |
| `pdfx list` | List all available components with install status |
| `pdfx diff <component>` | Show diff between your local copy and latest upstream |
| `pdfx theme init` | Create a custom theme file |
| `pdfx theme switch <name>` | Switch to any built-in preset theme |
| `pdfx theme validate` | Validate your theme token file |
| `pdfx block add <id>` | Copy a pre-built block into your project |
| `pdfx block list` | List all available blocks |

## Tech Stack

- **Rendering**: `@react-pdf/renderer` v4
- **Language**: TypeScript (strict)
- **Package manager**: pnpm v10 (workspace monorepo)
- **Build**: Vite + Turborepo
- **Linter**: Biome
- **Node.js**: 20+

## Repository Structure

```
pdfx/
  apps/
    www/                     # Docs site + registry server (Vite React SPA)
      src/registry/
        components/          # 24 component source files (source of truth)
        blocks/              # 10 block template source files
        index.json           # Registry manifest
      src/lib/
        build-registry.ts    # Transforms source → public/r/*.json
      public/r/              # HTTP-served JSON consumed by the CLI
  packages/
    shared/                  # Types, theme presets, Zod schemas, errors
    cli/                     # pdfx-cli — all CLI commands
  docs/                      # Architecture and decision docs
```

## How the Registry Works

The website and the registry are the same thing — same model as shadcn/ui.

1. Component source lives in `apps/www/src/registry/components/<name>/`
2. `pnpm build:registry` runs `build-registry.ts` which transforms source into `public/r/<name>.json`
3. `pdfx add <name>` fetches that JSON over HTTPS and writes the files into the user's project
4. No PDFx package is installed — the user owns the code from that point

## Documentation

- Docs: https://pdfx.akashpise.dev/docs
- Installation: https://pdfx.akashpise.dev/installation
- Components: https://pdfx.akashpise.dev/components
- Blocks: https://pdfx.akashpise.dev/blocks
- MCP & Skills: https://pdfx.akashpise.dev/mcp
- Theme Builder: https://pdfx.akashpise.dev/theme-builder
- Releases: https://pdfx.akashpise.dev/releases
- Contributing: https://github.com/akii09/pdfx/blob/main/CONTRIBUTING.md
- CLI Changelog: https://github.com/akii09/pdfx/blob/main/packages/cli/CHANGELOG.md