laru-cap-pdf
v0.0.1
Published
Laru — Capacitor (cap) plugin: native iOS/Android HTML-to-PDF, fast and scalable to 500+ pages.
Maintainers
ranasl62Readme
laru-cap-pdf
Laru — Capacitor (cap) plugin: native iOS/Android HTML-to-PDF. Fast, robust, efficient — one native render pass, no page limit, streams to file for maximum PDF generation. Full control via a rich options API; uses WebKit/WebView (no canvas).
Why Laru is better
| vs canvas-based (html2pdf, jsPDF+html2canvas) | vs other native plugins |
|-----------------------------------------------|--------------------------|
| One native render pass — no per-page bitmap; 500+ pages in one go. | All options implemented: timeout, waitForSelector, margins, printBackground, httpHeaders, PDF metadata (iOS). |
| Faster — same document in a fraction of the time. | You own the code — MIT, no vendor lock-in. |
| Full CSS/JS — pass baseUrl; relative assets resolve. | Same API as laru-pdf-js for a consistent experience. |
Install
npm install laru-cap-pdf
npx cap syncUsage
import { LaruCapPdf } from 'laru-cap-pdf';
// From HTML string (pass baseUrl when using relative CSS/JS paths)
const result = await LaruCapPdf.fromData({
data: '<html><body><h1>Hello</h1></body></html>',
documentSize: 'A4',
orientation: 'portrait',
type: 'base64', // or 'file' | 'share'
fileName: 'document.pdf',
baseUrl: 'file:///android_asset/', // required if HTML has relative links/scripts
});
console.log(result.base64); // or result.path for type: 'file'
// From URL with auth headers
const result2 = await LaruCapPdf.fromUrl({
url: 'https://example.com/page',
httpHeaders: { 'Authorization': 'Bearer token' },
type: 'file',
fileName: 'page.pdf',
});Options (HtmlToPdfOptions)
All options are supported on both iOS and Android unless noted. Every option is optional — only data (fromData) or url (fromUrl) is required.
| Option | Type | Description |
|--------|------|-------------|
| Page layout | | |
| documentSize | 'A2' | 'A3' | 'A4' | 'Letter' | 'Legal' | Paper size. Default: A4. Ignored if customPageSize is set. |
| orientation | 'portrait' | 'landscape' | Page orientation. |
| customPageSize | { widthPt, heightPt } | Custom size in points (1 pt = 1/72"). Overrides documentSize. |
| margins | { top?, bottom?, left?, right? } | Page margins in points (pt). |
| marginPreset | 'none' | 'minimal' | 'normal' | 'wide' | Quick margins when margins not set (0, 18pt, 36/72pt, 72pt). |
| printBackground | boolean | Include CSS backgrounds (default true). |
| omitBackground | boolean | Do not print backgrounds (alias for printBackground: false). |
| injectStyles | string | Extra CSS injected before print (e.g. @page { margin: 0; }). |
| scale | number | Scale factor 0.1–3 (default 1). |
| fitToPage | boolean | Use scale 0.95 to fit content to page. |
| pageRange | string | Only include these pages, e.g. "1-5" or "1,3,5". |
| headerHtml | string | HTML fragment for header (fixed at top, each page). |
| footerHtml | string | HTML fragment for footer (fixed at bottom, each page). |
| Output | | |
| type | 'base64' | 'share' | 'file' | How to return/save the PDF. For 500+ pages use file. |
| fileName | string | Filename for share/file output. |
| outputPath | string | For type 'file': directory to write to (optional). |
| encoding | string | HTML charset for fromData (default UTF-8). Android. |
| Loading & behavior | | |
| baseUrl | string | Required for fromData when HTML uses relative CSS/JS/images. |
| enableJavaScript | boolean | Allow JS (default true). |
| loadImages | boolean | Load images (default true). Android. |
| userAgent | string | Custom User-Agent for the WebView. |
| viewport | { width, height } | Viewport size in pixels (responsive layout). |
| preferColorScheme | 'light' | 'dark' | Force color scheme for @media (prefers-color-scheme). |
| mediaType | 'print' | 'screen' | CSS media to emulate (default print). |
| runBeforePrint | string | JavaScript to run in the page right before generating PDF. |
| delayAfterLoad | number | Ms to wait after load before generating PDF. |
| timeout | number | Max ms to wait for load; rejects on timeout. |
| waitForSelector | string | CSS selector; wait until element exists (or timeout) before generating. |
| retry | number | Retries on failure (e.g. network). Default: 0. |
| retryDelay | number | Ms between retries. Default: 500. |
| fromUrl only | | |
| httpHeaders | Record<string, string> | Extra headers (e.g. Authorization). |
| PDF metadata | | iOS (keywords too); Android best-effort. |
| title, author, subject, creator, keywords, producer | string | PDF document metadata. |
Platform support
- iOS: Full support. WKWebView + UIPrintPageRenderer. PDF metadata (title, author, subject, creator) supported. Requires Xcode on macOS to build.
- Android: Full support. WebView + PrintDocumentAdapter. For share type the app may need to configure FileProvider.
- Web: Rejects with a message; use browser Print → Save as PDF or laru-pdf-js for the same API.
No arbitrary limits (unlike the market)
Laru does not impose the typical limits of commercial or free HTML-to-PDF libraries:
- No page limit — Generate 500+ or thousands of pages in one pass (use
type: 'file'for large docs). - No file size cap — Output size is only limited by device storage.
- Generous timeouts —
timeoutanddelayAfterLoadcan be up to 24 hours (86 400 000 ms) for long-running or batch jobs; no 30s/2 min cap. - Wide scale range —
scalefrom 0.01 to 10 (1%–1000%); no narrow 0.5–2 range. - Custom page size — Any dimensions via
customPageSize; not limited to presets. - Page range — Export only the pages you need with
pageRange.
Only platform realities apply: PDF metadata (title, author, etc.) is iOS only; Share on Android requires your app to configure a FileProvider.
Testing
npm install --legacy-peer-deps # if laru-pdf-js is not published
npm testTests cover web validation (same options as native). Native behavior is tested on device/simulator.
Performance, efficiency & maximum PDF
- Fastest path: Set
enableJavaScript: falseandloadImages: falsewhen your HTML doesn’t need them — load and render are faster. - Efficient output: Use
type: 'file'for any document that might be large. The PDF is streamed to disk (no full-doc buffer in memory). Usetype: 'base64'only for small PDFs. - One native render pass: No per-page bitmap or canvas; the engine paginates in a single pass, so generation stays fast and memory use is predictable.
- Result:
path,base64, and when availablepages(page count) for diagnostics or progress. - Robustness: WebView is destroyed on timeout or error to avoid leaks; use
retryandretryDelayfor flaky networks. - No page cap: Generate as many pages as you need; for very large jobs, keep
type: 'file'and ensure enough free disk space.
License
MIT