npm package: @hyperdrive.bot/html-to-pdf
Description: Smart HTML-to-PDF converter with intelligent height detection for single-page output
Author: DevSquad
Latest version: 0.1.0

# 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

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

## 🔧 Usage

### Basic Usage

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

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

```bash
# Show help
npm run test:help

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

## 🧠 How It Works

1. **Page Loading**: Loads HTML with proper viewport and font loading
2. **Lazy Content Trigger**: Scrolls through page to trigger any lazy-loaded content  
3. **Height Measurement**: Measures total content height accurately
4. **Method Selection**:
   - **Height ≤ 19,200px (~200 inches)**: Direct PDF generation (preserves text selection)
   - **Height > 19,200px**: PNG-to-PDF method (ensures single-page output)
5. **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

```bash
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
```bash
node index.js proposal.html client-proposal.pdf --width=1366
```

### Financial Reports  
```bash
node index.js financial-report.html quarterly-report.pdf --verbose
```

### Technical Documentation
```bash
node index.js api-docs.html documentation.pdf --width=1200
```

### Marketing Materials
```bash
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
```html
<!-- ✅ 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
```css
/* ✅ 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
```bash
# Add to package.json scripts
"scripts": {
  "build:pdf": "node ../cli/html-to-pdf/index.js dist/index.html output.pdf"
}
```

### With CI/CD
```yaml
- 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