⚡ Quick Start

Run directly with npx - no installation required!

npx @jamesmontemagno/pdf-diff original.pdf modified.pdf

Requires Node.js 18 or later

📦 Installation

Option 1: Use directly with npx (recommended)

# No installation needed - runs the latest version
npx @jamesmontemagno/pdf-diff file1.pdf file2.pdf

Option 2: Global installation

# Install globally
npm install -g @jamesmontemagno/pdf-diff

# Then use anywhere
pdf-diff file1.pdf file2.pdf

Option 3: Project dependency

# Add to your project
npm install --save-dev @jamesmontemagno/pdf-diff

# Use in package.json scripts
"scripts": {
  "diff-pdfs": "pdf-diff docs/v1.pdf docs/v2.pdf"
}

✨ Features

📄 Visual Reports

Generate beautiful HTML and PDF reports showing all differences with syntax highlighting.

🔄 CI/CD Ready

Exit codes, JSON/JUnit output formats, and fail-on-diff flag for automated pipelines.

🎯 Page Selection

Compare specific pages only with flexible page range syntax.

💬 Interactive Mode

Guided prompts help you configure comparisons step by step.

💻 Usage Examples

Basic comparison

# Compare two PDFs and generate HTML + PDF reports
npx @jamesmontemagno/pdf-diff original.pdf modified.pdf

CI/CD pipeline

# Exit with code 1 if differences found, output as JSON
npx @jamesmontemagno/pdf-diff old.pdf new.pdf --fail-on-diff --format json

Custom output directory

# Save reports to a specific folder
npx @jamesmontemagno/pdf-diff a.pdf b.pdf --out ./my-reports

Compare specific pages

# Only compare pages 1-3 and page 5
npx @jamesmontemagno/pdf-diff a.pdf b.pdf --pages "1-3,5"

HTML report only

# Generate only HTML report (faster)
npx @jamesmontemagno/pdf-diff a.pdf b.pdf --report html

Interactive mode

# Launch guided prompts
npx @jamesmontemagno/pdf-diff --interactive

JUnit output for CI

# Output in JUnit XML format for test reporters
npx @jamesmontemagno/pdf-diff a.pdf b.pdf --format junit

⚙️ CLI Options

Option	Description	Default
`-r, --report <type>`	Report type: `html`, `pdf`, or `both`	`both`
`-o, --out <dir>`	Output directory for reports	`./pdf-diff-report`
`--open`	Open HTML report in browser after completion	enabled
`--no-open`	Don't open report in browser	-
`-f, --format <type>`	Output format: `text`, `json`, or `junit`	`text`
`--fail-on-diff`	Exit with code 1 if differences found	disabled
`-p, --pages <spec>`	Pages to compare (e.g., `1-3,5,7`)	all pages
`-t, --threshold <float>`	Change percentage threshold for failure	-
`-i, --interactive`	Interactive mode with guided prompts	disabled
`-V, --version`	Display version number	-
`-h, --help`	Display help information	-

🚦 Exit Codes

Code	Meaning
`0`	PDFs are identical (or differences below threshold)
`1`	PDFs have differences (when `--fail-on-diff` is used)

Tip: Use --fail-on-diff in CI pipelines to fail builds when document changes are detected.

🔄 CI/CD Integration

GitHub Actions Example

name: PDF Comparison
on: [push, pull_request]

jobs:
  compare:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Compare PDFs
        run: |
          npx @jamesmontemagno/pdf-diff \
            docs/expected.pdf \
            docs/generated.pdf \
            --fail-on-diff \
            --format junit \
            --out ./pdf-diff-results
      
      - name: Upload Report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: pdf-diff-report
          path: ./pdf-diff-results/

📊 Output Formats

Text (default)

Human-readable summary with statistics printed to the terminal.

JSON

Machine-readable output for programmatic processing:

{
  "summary": {
    "originalFile": "original.pdf",
    "modifiedFile": "modified.pdf",
    "originalPages": 5,
    "modifiedPages": 5
  },
  "statistics": {
    "additions": 42,
    "deletions": 15,
    "unchanged": 230,
    "changePercentage": 19.8
  },
  "pages": [
    { "pageNumber": 1, "hasChanges": true },
    { "pageNumber": 2, "hasChanges": false }
  ]
}

JUnit XML

Compatible with CI test reporters:

<testsuite name="PDF Diff" tests="5" failures="2">
  <testcase name="Page 1" classname="pdf-diff">
    <failure message="Page 1 has differences"/>
  </testcase>
  <testcase name="Page 2" classname="pdf-diff"/>
</testsuite>

📋 Requirements

Node.js 18+ - Required for running the CLI
Chromium - Automatically installed by Playwright for PDF report generation

Note: The first run may take a moment as Playwright downloads Chromium for PDF generation. Subsequent runs will be faster.

🔧 Troubleshooting

Browser installation issues

If you see errors about browser installation, run:

npx playwright install chromium

Permission errors

On Linux, you may need to install system dependencies:

npx playwright install-deps chromium

Skip PDF report generation

If you only need the HTML report and want to skip Chromium:

npx @jamesmontemagno/pdf-diff a.pdf b.pdf --report html

📂 Source Code

PDF Diff is open source! View the code, report issues, or contribute on GitHub:

github.com/jamesmontemagno/pdf-diff