@hyperdrive.bot/html-to-pdf

DevSquad HTML-to-PDF Converter

Smart HTML-to-PDF converter that automatically chooses the best method based on content height to ensure single-page output with optimal quality.

🚀 Features

• Intelligent Height Detection: Measures content height and chooses optimal conversion method
• Direct PDF Method: For normal-sized content (≤200 inches tall) with selectable text
• PNG-to-PDF Method: For very long content that exceeds PDF height limits
• Responsive Design Handling: Properly handles responsive CSS and web fonts
• Lazy Loading Support: Automatically scrolls to trigger lazy-loaded content
• CLI Interface: Easy command-line usage with various options
• Production Ready: Used for client proposals and professional documents

📦 Installation

cd packages/cli/html-to-pdf
npm install

🔧 Usage

Basic Usage

# Convert HTML to PDF
node index.js input.html output.pdf

# With verbose logging
node index.js proposal.html proposal.pdf --verbose

# Custom browser width for responsive layouts
node index.js document.html output.pdf --width=1920

Advanced Examples

# Mobile responsive view
node index.js responsive.html mobile.pdf --width=375

# Tablet view
node index.js responsive.html tablet.pdf --width=768

# Desktop high-res view
node index.js report.html desktop.pdf --width=1920 --verbose

# Convert from URL
node index.js https://example.com/proposal.html remote.pdf

NPM Scripts

# Show help
npm run test:help

# Development mode (with verbose logging)
npm run dev input.html output.pdf

🧠 How It Works

• Page Loading: Loads HTML with proper viewport and font loading
• Lazy Content Trigger: Scrolls through page to trigger any lazy-loaded content
• Height Measurement: Measures total content height accurately
• Method Selection:
  • Height ≤ 19,200px (~200 inches): Direct PDF generation (preserves text selection)
  • Height > 19,200px: PNG-to-PDF method (ensures single-page output)
• PDF Generation: Creates single-page PDF with chosen method

📊 Performance

Typical conversion times:

• Small documents (1-5 pages): 3-8 seconds
• Medium proposals (5-15 pages): 8-15 seconds
• Large reports (15+ pages): 15-30 seconds

Output quality:

• Direct PDF: Selectable text, vector graphics, small file sizes
• PNG-to-PDF: Pixel-perfect rendering, larger file sizes

⚙️ Configuration Options

node index.js <input.html> <output.pdf> [options]

Arguments

• input.html - Path to HTML file or URL (required)
• output.pdf - Output PDF path (required)

Options

• --width=<pixels> - Browser width (default: 1366, range: 300-4000)
• --verbose - Show detailed conversion logs
• --help, -h - Show help information

💡 Use Cases

Client Proposals

node index.js proposal.html client-proposal.pdf --width=1366

Financial Reports

node index.js financial-report.html quarterly-report.pdf --verbose

Technical Documentation

node index.js api-docs.html documentation.pdf --width=1200

Marketing Materials

node index.js landing-page.html brochure.pdf --width=1920

🔍 Troubleshooting

Common Issues

"Input file not found"

• Verify the HTML file path exists
• Use absolute paths if needed

"Conversion failed: Timeout"

• Increase system resources
• Check for heavy external resources in HTML
• Use --verbose to see where it fails

"Width must be between 300 and 4000"

• Use reasonable browser widths
• Common values: 375 (mobile), 768 (tablet), 1366 (laptop), 1920 (desktop)

Performance Tips

• Self-host fonts instead of using CDN fonts for faster loading
• Optimize images in HTML before conversion
• Remove unnecessary scripts that don't affect visual output
• Use local assets when possible to avoid network delays

🎯 Best Practices

HTML Optimization

<!-- ✅ Good: Self-hosted fonts -->
<link rel="stylesheet" href="./fonts/custom-font.css">

<!-- ✅ Good: Optimized images -->
<img src="./images/logo-optimized.png" alt="Logo">

<!-- ❌ Avoid: Heavy external resources -->
<script src="https://heavy-analytics.com/tracker.js"></script>

CSS for PDF

/* ✅ Good: Print-specific styles */
@media print {
  body { -webkit-print-color-adjust: exact; }
  .no-print { display: none; }
}

/* ✅ Good: Fixed dimensions */
.container { max-width: 1200px; margin: 0 auto; }

📈 Success Stories

✅ Client Proposals: Generated professional PDFs for 50+ client proposals ✅ Financial Reports: Converted complex multi-section reports seamlessly
✅ Marketing Materials: Created pixel-perfect brochures from responsive designs ✅ Technical Documentation: Handled long-form documentation with embedded media

🔗 Integration

With Build Systems

# Add to package.json scripts
"scripts": {
  "build:pdf": "node ../cli/html-to-pdf/index.js dist/index.html output.pdf"
}

With CI/CD

- name: Generate PDF
  run: |
    cd packages/cli/html-to-pdf
    npm install
    node index.js ../../web/dist/proposal.html ../../../artifacts/proposal.pdf

DevSquad CLI Tools | Part of the DevSquad development ecosystem