be574df599
- 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
425 lines
12 KiB
Markdown
425 lines
12 KiB
Markdown
# @push.rocks/smartpdf 📄✨
|
|
|
|
> **Transform HTML, websites, and PDFs into beautiful documents with just a few lines of code!**
|
|
|
|
[](https://www.npmjs.com/package/@push.rocks/smartpdf)
|
|
[](https://www.typescriptlang.org/)
|
|
[](./license)
|
|
|
|
## 🚀 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```typescript
|
|
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:
|
|
|
|
1. **Create** an instance
|
|
2. **Start** the server
|
|
3. **Do your PDF magic**
|
|
4. **Stop** the server
|
|
|
|
```typescript
|
|
const smartPdf = await SmartPdf.create();
|
|
await smartPdf.start();
|
|
// ... your PDF operations ...
|
|
await smartPdf.stop();
|
|
```
|
|
|
|
### 🔌 Smart Port Allocation
|
|
|
|
Run multiple instances without port conflicts:
|
|
|
|
```typescript
|
|
// 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:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
const pdf = await smartPdf.getPdfResultForWebsite('https://example.com');
|
|
```
|
|
|
|
#### Full Page Capture
|
|
Capture the entire scrollable area:
|
|
|
|
```typescript
|
|
const fullPagePdf = await smartPdf.getFullWebsiteAsSinglePdf('https://example.com');
|
|
```
|
|
|
|
### 🔀 Merge Multiple PDFs
|
|
|
|
Combine PDFs like a pro:
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
const webpImages = await smartPdf.convertPDFToWebpBytes(pdf.buffer, {
|
|
quality: 90, // 0-100 quality scale
|
|
scale: 2.0 // 144 DPI - great for web
|
|
});
|
|
```
|
|
|
|
#### JPEG - Progressive Loading
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
// 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:
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
// 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:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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](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.
|
|
|
|
### Company Information
|
|
|
|
Task Venture Capital GmbH
|
|
Registered at District court Bremen HRB 35230 HB, Germany
|
|
|
|
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
|
|
|
|
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works. |