push.rocks/smartpdf

Fork 0

Files

Juergen Kunz be574df599

Default (tags) / security (push) Failing after 24s

Details

Default (tags) / test (push) Failing after 12s

Details

Default (tags) / release (push) Has been skipped

Details

Default (tags) / metadata (push) Has been skipped

Details

feat(image): add progressive JPEG generation support

- Add convertPDFToJpegBytes method for progressive JPEG images
- Integrate @push.rocks/smartjimp for true progressive encoding
- Update readme with comprehensive documentation
- Update legal section to Task Venture Capital GmbH

2025-08-02 17:29:38 +00:00

12 KiB

Raw Blame History

@push.rocks/smartpdf 📄✨

Transform HTML, websites, and PDFs into beautiful documents with just a few lines of code!

🚀 Why SmartPDF?

SmartPDF is your Swiss Army knife for PDF operations in Node.js. Whether you're generating invoices, creating reports, or converting web pages to PDFs, we've got you covered with a simple, powerful API.

✨ Features at a Glance

📝 HTML to PDF - Transform HTML strings with full CSS support
🌐 Website to PDF - Capture any website as a perfectly formatted PDF
🔀 PDF Merging - Combine multiple PDFs into one
🖼️ PDF to Images - Convert PDFs to PNG, WebP, or progressive JPEG
📑 Text Extraction - Pull text content from existing PDFs
🎯 Smart Port Management - Automatic port allocation for concurrent instances
💪 TypeScript First - Full type safety and IntelliSense support
⚡ High Performance - Optimized for speed and reliability

📦 Installation

# Using npm
npm install @push.rocks/smartpdf --save

# Using yarn
yarn add @push.rocks/smartpdf

# Using pnpm (recommended)
pnpm add @push.rocks/smartpdf

🎯 Quick Start

import { SmartPdf } from '@push.rocks/smartpdf';

// Create and start SmartPdf
const smartPdf = await SmartPdf.create();
await smartPdf.start();

// Generate a PDF from HTML
const pdf = await smartPdf.getA4PdfResultForHtmlString(`
  <h1>Hello, PDF World! 🌍</h1>
  <p>This is my first SmartPDF document.</p>
`);

// Save it
await fs.writeFile('my-first-pdf.pdf', pdf.buffer);

// Don't forget to clean up!
await smartPdf.stop();

📚 Core Concepts

🏗️ Instance Management

SmartPDF uses a client-server architecture for maximum performance. Always remember:

Create an instance
Start the server
Do your PDF magic
Stop the server

const smartPdf = await SmartPdf.create();
await smartPdf.start();
// ... your PDF operations ...
await smartPdf.stop();

🔌 Smart Port Allocation

Run multiple instances without port conflicts:

// Each instance automatically finds a free port
const instance1 = await SmartPdf.create(); // Port: 20000
const instance2 = await SmartPdf.create(); // Port: 20001
const instance3 = await SmartPdf.create(); // Port: 20002

// Or specify custom settings
const customInstance = await SmartPdf.create({
  port: 3000,              // Use specific port
  portRangeStart: 4000,    // Or define a range
  portRangeEnd: 5000
});

🎨 PDF Generation

📝 From HTML String

Create beautiful PDFs from HTML with full CSS support:

const smartPdf = await SmartPdf.create();
await smartPdf.start();

const pdf = await smartPdf.getA4PdfResultForHtmlString(`
  <!DOCTYPE html>
  <html>
    <head>
      <style>
        @import url('https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;700&display=swap');
        
        body {
          font-family: 'Roboto', sans-serif;
          margin: 40px;
          color: #333;
        }
        
        .header {
          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
          color: white;
          padding: 30px;
          border-radius: 10px;
          text-align: center;
        }
        
        .content {
          margin-top: 30px;
          line-height: 1.6;
        }
        
        .highlight {
          background-color: #ffd93d;
          padding: 2px 6px;
          border-radius: 3px;
        }
      </style>
    </head>
    <body>
      <div class="header">
        <h1>Invoice #2024-001</h1>
        <p>Generated on ${new Date().toLocaleDateString()}</p>
      </div>
      <div class="content">
        <h2>Bill To:</h2>
        <p>Acme Corporation</p>
        <p>Total: <span class="highlight">$1,234.56</span></p>
      </div>
    </body>
  </html>
`);

await fs.writeFile('invoice.pdf', pdf.buffer);
await smartPdf.stop();

🌐 From Website

Capture any website as a PDF with two powerful methods:

Standard A4 Format

Perfect for articles and documents:

const pdf = await smartPdf.getPdfResultForWebsite('https://example.com');

Full Page Capture

Capture the entire scrollable area:

const fullPagePdf = await smartPdf.getFullWebsiteAsSinglePdf('https://example.com');

🔀 Merge Multiple PDFs

Combine PDFs like a pro:

// Load your PDFs
const invoice = await smartPdf.readFileToPdfObject('./invoice.pdf');
const terms = await smartPdf.readFileToPdfObject('./terms.pdf');
const contract = await smartPdf.getA4PdfResultForHtmlString('<h1>Contract</h1>...');

// Merge them in order
const mergedPdf = await smartPdf.mergePdfs([
  contract.buffer,
  invoice.buffer,
  terms.buffer
]);

await fs.writeFile('complete-document.pdf', mergedPdf);

🖼️ Image Generation

🎨 Convert PDF to Images

SmartPDF supports three image formats, each with its own strengths:

PNG - Crystal Clear Quality

const pngImages = await smartPdf.convertPDFToPngBytes(pdf.buffer, {
  scale: SmartPdf.SCALE_HIGH  // 216 DPI - perfect for most uses
});

// Save each page
pngImages.forEach((png, index) => {
  fs.writeFileSync(`page-${index + 1}.png`, png);
});

WebP - Modern & Efficient

const webpImages = await smartPdf.convertPDFToWebpBytes(pdf.buffer, {
  quality: 90,  // 0-100 quality scale
  scale: 2.0    // 144 DPI - great for web
});

JPEG - Progressive Loading

const jpegImages = await smartPdf.convertPDFToJpegBytes(pdf.buffer, {
  quality: 85,              // Balance between size and quality
  scale: SmartPdf.SCALE_SCREEN,  // 144 DPI
  maxWidth: 1920            // Constrain dimensions
});

📏 DPI & Scale Guide

SmartPDF makes it easy to get the right resolution:

// Built-in scale constants
SmartPdf.SCALE_SCREEN  // 2.0 = ~144 DPI (web display)
SmartPdf.SCALE_HIGH    // 3.0 = ~216 DPI (high quality, default)
SmartPdf.SCALE_PRINT   // 6.0 = ~432 DPI (print quality)

// Or calculate your own
const scale = SmartPdf.getScaleForDPI(300); // Get scale for 300 DPI

🖼️ Thumbnail Generation

Create perfect thumbnails for document previews:

const thumbnails = await smartPdf.convertPDFToWebpBytes(pdf.buffer, {
  scale: 0.5,      // Small but readable
  quality: 70,     // Lower quality for tiny files
  maxWidth: 200,   // Constrain to thumbnail size
  maxHeight: 200
});

📊 Format Comparison

Choose the right format for your needs:

Format	File Size	Best For	Special Features
PNG	Largest	Screenshots, diagrams, text	Lossless, transparency
JPEG	30-50% of PNG	Photos, complex images	Progressive loading
WebP	25-40% of PNG	Modern web apps	Best compression

🛡️ Best Practices

1. Always Use Try-Finally

let smartPdf: SmartPdf;

try {
  smartPdf = await SmartPdf.create();
  await smartPdf.start();
  
  // Your PDF operations
  
} finally {
  if (smartPdf) {
    await smartPdf.stop(); // Always cleanup!
  }
}

2. Optimize HTML for PDFs

const optimizedHtml = `
  <style>
    /* Use print-friendly styles */
    @media print {
      .no-print { display: none; }
    }
    
    /* Avoid page breaks in wrong places */
    h1, h2, h3 { page-break-after: avoid; }
    table { page-break-inside: avoid; }
  </style>
  ${yourContent}
`;

3. Handle Large Documents

For documents with many pages:

// Process in batches
const pages = await smartPdf.convertPDFToPngBytes(largePdf.buffer);

for (let i = 0; i < pages.length; i += 10) {
  const batch = pages.slice(i, i + 10);
  await processBatch(batch);
}

🎯 Advanced Usage

🌐 Custom Browser Instance

Bring your own Puppeteer instance:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: 'new',
  args: ['--no-sandbox', '--disable-dev-shm-usage']
});

const smartPdf = await SmartPdf.create();
await smartPdf.start(browser);

// SmartPdf won't close your browser
await smartPdf.stop();
await browser.close(); // You manage it

⚡ Parallel Processing

Process multiple PDFs concurrently:

const urls = ['https://example1.com', 'https://example2.com', 'https://example3.com'];

const pdfs = await Promise.all(
  urls.map(url => smartPdf.getFullWebsiteAsSinglePdf(url))
);

// Or with multiple instances for maximum performance
const instances = await Promise.all(
  Array(3).fill(null).map(() => SmartPdf.create())
);

await Promise.all(instances.map(i => i.start()));

// Process in parallel across instances
const results = await Promise.all(
  urls.map((url, i) => instances[i % instances.length].getFullWebsiteAsSinglePdf(url))
);

// Cleanup all instances
await Promise.all(instances.map(i => i.stop()));

📝 API Reference

Class: SmartPdf

Static Methods

create(options?: ISmartPdfOptions) - Create a new SmartPdf instance
getScaleForDPI(dpi: number) - Calculate scale factor for desired DPI

Instance Methods

start(browser?: Browser) - Start the PDF server
stop() - Stop the PDF server
getA4PdfResultForHtmlString(html: string) - Generate A4 PDF from HTML
getPdfResultForWebsite(url: string) - Generate A4 PDF from website
getFullWebsiteAsSinglePdf(url: string) - Capture full webpage as PDF
mergePdfs(buffers: Uint8Array[]) - Merge multiple PDFs
readFileToPdfObject(path: string) - Read PDF file from disk
extractTextFromPdfBuffer(buffer: Buffer) - Extract text from PDF
convertPDFToPngBytes(buffer: Uint8Array, options?) - Convert to PNG
convertPDFToWebpBytes(buffer: Uint8Array, options?) - Convert to WebP
convertPDFToJpegBytes(buffer: Uint8Array, options?) - Convert to JPEG

Interface: IPdf

interface IPdf {
  name: string;              // Filename
  buffer: Buffer;            // PDF content
  id: string | null;         // Unique identifier
  metadata?: {
    textExtraction?: string; // Extracted text
  };
}

🤝 Contributing

We love contributions! Please feel free to submit a Pull Request.

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

12 KiB Raw Blame History

@push.rocks/smartpdf 📄✨

🚀 Why SmartPDF?

✨ Features at a Glance

📦 Installation

🎯 Quick Start

📚 Core Concepts

🏗️ Instance Management

🔌 Smart Port Allocation

🎨 PDF Generation

📝 From HTML String

🌐 From Website

Standard A4 Format

Full Page Capture

🔀 Merge Multiple PDFs

🖼️ Image Generation

🎨 Convert PDF to Images

PNG - Crystal Clear Quality

WebP - Modern & Efficient

JPEG - Progressive Loading

📏 DPI & Scale Guide

🖼️ Thumbnail Generation

📊 Format Comparison

🛡️ Best Practices

1. Always Use Try-Finally

2. Optimize HTML for PDFs

3. Handle Large Documents

🎯 Advanced Usage

🌐 Custom Browser Instance

⚡ Parallel Processing

📝 API Reference

Class: SmartPdf

Static Methods

Instance Methods

Interface: IPdf

🤝 Contributing

License and Legal Information

Trademarks

Company Information

12 KiB

Raw Blame History