use example.com in image conversion test and relax JPEG size assertion
- Replaced https://www.wikipedia.org with https://example.com in test/test.ts for the third PDF generation test
- Removed the strict expectation that JPEG size must be smaller than PNG; now only asserts that WebP is smaller than PNG
- Updated test comment to note that JPEG may not be smaller for simple graphics pages
## 2026-03-01 - 4.1.2 - fix(smartfs)
replace smartfile with smartfs, update file reading to use SmartFs, remove GraphicsMagick/Ghostscript dependency checks, bump dev and runtime dependencies, update tests and docs, and adjust npmextra configuration
- Replace usage/export of @push.rocks/smartfile with @push.rocks/smartfs and update readFileToPdfObject to use SmartFs + SmartFsProviderNode
- Remove execFile import and the GraphicsMagick/Ghostscript dependency-checking helpers from smartpdf (no more gm/gs checks)
"legal":"\n## License and Legal Information\n\nThis 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. \n\n**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.\n\n### Trademarks\n\nThis 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.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy 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.\n"
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
## 🚀 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.
SmartPDF is your Swiss Army knife for PDF operations in Node.js. Whether you're generating invoices from HTML, snapshotting web pages, merging documents, or converting PDF pages to images — SmartPDF handles it all through a clean, async-first TypeScript API backed by headless Chromium.
### ✨ 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
| Feature | Description |
|---------|-------------|
| 📝 **HTML → PDF** | Render any HTML string (with full CSS) into an A4-sized PDF |
| 🌐 **Website → PDF**| Capture a live URL as a PDF — either A4 or full-page scroll |
| 🔀 **PDF Merging** | Combine multiple PDF buffers into a single document |
| 🖼️ **PDF → Images** | Convert PDF pages to **PNG**, **WebP**, or progressive **JPEG** |
| 📑 **Text Extraction**| Pull raw text content from any PDF buffer |
| 🔌 **Smart Port Management** | Automatic port allocation so multiple instances never collide |
| 🎛️ **DPI Control** | Built-in scale constants for screen, high-quality, and print resolutions |
| 🌐 **BYO Browser** | Optionally pass your own Puppeteer `Browser` instance |
## 📦 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
```
> **Prerequisites:** SmartPDF uses headless Chromium via Puppeteer under the hood. On most systems this is handled automatically. If you run into browser-launch issues (CI, Docker, etc.), make sure the required system libraries are installed — see the [Puppeteer troubleshooting guide](https://pptr.dev/troubleshooting).
textExtraction?: string;// Extracted text (when available)
};
}
```
SmartPDF uses a client-server architecture for maximum performance. Always remember:
## 📚 How It Works
1.**Create** an instance
2.**Start** the server
3.**Do your PDF magic**
4.**Stop** the server
SmartPDF spins up a lightweight Express server bound to `localhost` and a headless Chromium browser. When you call a generation method:
1.Your HTML is registered internally and served at `http://localhost:{port}/{id}`
2.Puppeteer navigates to that URL, waits for the page to fully render, and captures a PDF
3. A header-based security check ensures only the correct content is captured
4. The server and browser are torn down when you call `stop()`
This architecture means you get **pixel-perfect CSS rendering**, **web font support**, and **full JavaScript execution** — the same rendering engine that powers Chrome.
`getPdfResultForWebsite` uses a 1980×1200 viewport and respects the page's own width/height. `getFullWebsiteAsSinglePdf` uses a 1920px-wide viewport and measures the full scroll height, producing a single tall page.
### 🔀 Merge Multiple PDFs
Combine any number of PDF buffers into one document using `pdf-lib`:
-`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
| Method | Returns | Description |
|--------|---------|-------------|
| `start(browser?)` | `Promise<void>` | Starts internal server + browser. Optionally accepts an existing Puppeteer `Browser`. |
| `stop()` | `Promise<void>` | Shuts down server and browser (unless external browser was provided). |
| `getA4PdfResultForHtmlString(html)` | `Promise<IPdf>` | Renders HTML at 794×1122 viewport → A4 PDF |
| `getPdfResultForWebsite(url)` | `Promise<IPdf>` | Captures website at 1980×1200 viewport → PDF |
| `getFullWebsiteAsSinglePdf(url)` | `Promise<IPdf>` | Captures full scrollable page at 1920px wide → single-page PDF |
| `mergePdfs(buffers)` | `Promise<Uint8Array>` | Merges an array of PDF `Uint8Array` buffers |
| `readFileToPdfObject(path)` | `Promise<IPdf>` | Reads a PDF file from disk into an `IPdf` object |
| `extractTextFromPdfBuffer(buffer)` | `Promise<string>` | Extracts raw text from a PDF buffer |
| `convertPDFToPngBytes(buffer, opts?)` | `Promise<Uint8Array[]>` | Converts each PDF page to a PNG buffer |
| `convertPDFToWebpBytes(buffer, opts?)` | `Promise<Uint8Array[]>` | Converts each PDF page to a WebP buffer |
| `convertPDFToJpegBytes(buffer, opts?)` | `Promise<Uint8Array[]>` | Converts each PDF page to a progressive JPEG buffer |
#### Image Conversion Options
```typescript
interfaceIPdf{
name: string;// Filename
buffer: Buffer;// PDF content
id: string|null;// Unique identifier
metadata?:{
textExtraction?: string;// Extracted text
};
{
scale?: number;// DPI multiplier (default: 3.0)
quality?: number;// 0–100, WebP/JPEG only (default: 85)
maxWidth?: number;// Max output width in pixels
maxHeight?: number;// Max output height in pixels
}
```
## 🤝 Contributing
### `ISmartPdfOptions` Interface
We love contributions! Please feel free to submit a Pull Request.
```typescript
{
port?: number;// Use a specific port
portRangeStart?: number;// Auto-allocation range start (default: 20000)
portRangeEnd?: number;// Auto-allocation range end (default: 30000)
}
```
## 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.
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
**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.
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 or third parties, 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 or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
### Company Information
Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany
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.
For any legal inquiries or 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.
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.
@@ -17,7 +17,7 @@ import * as smartjimp from '@push.rocks/smartjimp';
export{
smartbuffer,
smartfile,
smartfs,
smartdelay,
smartpromise,
smartpath,
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
