Hello
')); // the first call downloads PD4ML (once) ``` **Ahead of time, with the `pd4ml` command.** This is better for servers, CI and container images, where a download in the middle of a request is unwelcome: ``` npx pd4ml install ``` Either way, the module: - downloads the most recent PD4ML 4.x release; - downloads the Bouncy Castle jars PD4ML needs for encryption and signing, from Maven Central; - checks every file against its published SHA-1 checksum; - stores them in a per-user cache directory: `%LOCALAPPDATA%\pd4ml-node` on Windows, `~/.cache/pd4ml-node` elsewhere, or `PD4ML_HOME`. The module then uses that build. Later runs do not check for newer PD4ML releases: run `npx pd4ml install` again to update. Updating the npm package does not change the PD4ML build. | Option | | |---|---| | *(none)* | the most recent 4.x release, or an update to it | | `--snapshots` | the most recent 4.x build, including development snapshots | | `npx pd4ml install 4.0.23fx2` | an exact version | | `--jakarta` | the `-jakarta` variant (for Jakarta EE / Servlet 6 environments) | | `--home DIR` | install into `DIR` (default: `PD4ML_HOME`, else the cache directory) | | `--force` | download again | | `--no-bouncycastle` | skip the Bouncy Castle jars (encryption and signing will not work) | | `npx pd4ml list` | list the available versions | The same is available from code, which suits an application's start-up: ```js const pd4ml = require('pd4ml'); pd4ml.install(); // downloads only when that build is not there yet console.log(pd4ml.installedVersion(), pd4ml.installedClasspath()); ``` To check the installation, run `npx pd4ml version`. **Turning the automatic download off.** Set `PD4ML_AUTO_INSTALL=0`, for example on servers that must not reach the internet, or where the build is provisioned separately. The module then throws a `BridgeError` until a build is installed or configured. The automatic download never runs when a build is configured through [2.3](#2.3-other-ways-to-provide-pd4ml). > **Services and containers**: the account the application runs as must see the installed > build. Install it as that account, or install into a shared directory and set `PD4ML_HOME` > for the application too. In a Dockerfile: > > ``` > RUN npm ci && PD4ML_HOME=/opt/pd4ml npx pd4ml install > ENV PD4ML_HOME=/opt/pd4ml PD4ML_AUTO_INSTALL=0 > ``` ### 2.3 Other ways to provide PD4ML The module looks for PD4ML in this order: 1. `configure({ classpath: [...] })`, called before the first conversion; 2. the `PD4ML_CLASSPATH` environment variable: jars and class directories separated by `;` (Windows) or `:` (elsewhere), with `dir/*` for all jars of a directory; 3. the `PD4ML_CLASSPATH_FILE` environment variable: a file with one entry per line; 4. the build `npx pd4ml install` (or the first use) downloaded. Typical reasons to use them: - **Offline or air-gapped servers**: run `npx pd4ml install --home ./pd4ml-libs` on a machine with network access, copy the directory, and set `PD4ML_HOME` and `PD4ML_AUTO_INSTALL=0` on the target. - **A licensed or specific jar**: `PD4ML_CLASSPATH=/opt/pd4ml/pd4ml.jar:/opt/pd4ml/lib/*`. - **A PD4ML development build** (for the v42 layout engine, see [4.3](#4.3-layout-engines)): a classpath file listing the build's classes and its Maven dependencies, in `PD4ML_CLASSPATH_FILE`. ## 3. Quick start ```js const { PD4ML, PageSize } = require('pd4ml'); const pd = new PD4ML(); pd.setPageSize(PageSize.A4); pd.readHtmlString('Hello, PDF
Generated with PD4ML.
'); pd.writePDF('hello.pdf'); ``` Or in one call: ```js const { htmlToPdf } = require('pd4ml'); const pdf = htmlToPdf(Buffer.from('Invoice 42
')); console.log(pdf.subarray(0, 5).toString()); // %PDF- ``` With TypeScript or ES modules: ```ts import { PD4ML, PageSize } from 'pd4ml'; const pd = new PD4ML(); pd.setPageSize(PageSize.A4); pd.readHtmlString('Hello
'); const pdf: Buffer = pd.writePDF(); ``` ## 4. How it works ### 4.1 The two-phase model A document is **read once and written any number of times**: - `readHTML` parses the document and lays it out; - each `writePDF`, `writeDOCX`, `writeRTF` or `renderAsImages` call then produces one output from that same layout. Settings (page size, headers, fonts...) go before `readHTML`. See [the two-phase model](https://pd4ml.com/docs/#6.1-the-two-phase-model). ```js const { PD4ML } = require('pd4ml'); const pd = new PD4ML(); pd.readHtmlString('Quarterly report
'); pd.writePDF('report.pdf'); pd.writeDOCX('report.docx'); const thumbnails = pd.renderPng(); // PNG images, one Buffer per page ``` ### 4.2 The bridge, threads and the event loop - **One bridge per process.** The first use of PD4ML starts a Java bridge process. It serves every conversion of the Node process and ends with it. Starting Java takes a fraction of a second; after that, converting an ordinary document takes milliseconds. - **Synchronous calls.** Each call waits for Java's answer, like any other CPU-bound work in Node: a long conversion blocks the event loop while it runs. Behind the scenes a worker thread does the communication, so callbacks such as progress listeners ([5.14](#5.14-progress-diagnostics-and-metadata)) still run on your thread. - **Servers with concurrent requests** stay responsive by converting in worker threads: each worker (`worker_threads`, or a pool such as `piscina`) can load `pd4ml` and convert on its own. Each worker starts its own bridge, unless all of them use one bridge server (next item). - **Shared bridge server.** Several processes or workers, or short-lived ones (serverless, CLI tools), can use one long-running bridge instead of each starting Java: ``` npx pd4ml serve --port 8723 # keep it running (systemd, a sidecar container, pm2) ``` Then set `PD4ML_BRIDGE=tcp://127.0.0.1:8723`, or call `configure({ server: 'tcp://127.0.0.1:8723' })`. The server listens on the loopback interface only, and each connection has its own objects. - **JVM options** (memory, system properties): set `PD4ML_JVM_OPTIONS="-Xmx2g"`, or call `configure({ jvmOptions: ['-Xmx2g'] })` before the first use. Java runs headless. - **The bridge's console output** is discarded unless `PD4ML_BRIDGE_LOG=path` (or `configure({ logFile })`) keeps it. `shutdown()` stops the bridge; the next use starts it again. ### 4.3 Layout engines PD4ML 4.2 introduces a second HTML layout engine, **v42**, written to match current browsers closely (flexbox, grid, modern CSS). `new PD4ML()` uses it by default: ```js const { PD4ML, hasLayoutEngines } = require('pd4ml'); if (hasLayoutEngines()) { const pd = new PD4ML(); // v42 const legacy = new PD4ML({ engine: 'v40' }); // the previous engine console.log(pd.engine, legacy.engine); } ``` Builds before 4.2 have one engine only; this includes the current public release, 4.1.x. With such a build: - the module uses that build's engine and emits a warning once (`process.emitWarning`); - `hasLayoutEngines()` returns false; - asking for an engine explicitly throws. ### 4.4 JavaScript and Java values - Java methods keep their **Java names** (`setPageSize`, `readHTML`...) and take JavaScript values: strings, numbers, booleans, `null`; arrays for Java arrays and lists; plain objects for `Map`s; `Buffer`/`Uint8Array` for `byte[]` and input streams. - **Classes**: the PD4ML classes are exported under their own names (`PageSize`, `PageMargins`, `Units`, `Constants`, `PdfSpec`, `LayoutEngine`...). Static fields and methods are properties (`PageSize.A4`, `PdfSpec.getInstance('pdf/a-2b')`), constructors use `new`. Any other class: `Java.type('java.util.Locale')`. - **Objects**: a Java object comes back as a proxy with all its Java methods. Helpers start with `$`, so they never hide a Java method: `$get('width')` and `$set(...)` for public fields, `$class`, `$enum` (an enum constant's name), `$instanceOf(...)`. `String(obj)` is Java's `toString()`. - **Numbers**: JavaScript has one number type. An integer goes to Java as an `int`; where a method has both `int` and `float` overloads and you want the float one, pass `Java.float(10)`. Java numbers come back as JavaScript numbers, `byte[]` as a `Buffer`. - Java objects are released when JavaScript garbage-collects them. ### 4.5 Exceptions Java exceptions are thrown as `JavaError`, which knows the Java class and its superclasses: ```js const { PD4ML, JavaError } = require('pd4ml'); try { const pd = new PD4ML(); pd.readHTML('file:///no/such/document.html'); pd.writePDF(); } catch (e) { if (e instanceof JavaError && e.isInstanceOf('java.io.IOException')) { console.log('cannot read the document:', e.javaMessage); } else { throw e; } } ``` `e.javaClass`, `e.causes` and `e.javaTrace` hold the details. Other errors: | Error | Thrown when | |---|---| | `BridgeError` | the bridge itself fails: no Java, no PD4ML build, or the process ended | | `CallbackError` | a JavaScript callback threw, such as a progress listener; the original error is `cause` | | `InstallError` | downloading PD4ML fails | --- ## 5. Use cases The snippets below are complete and runnable. Files they read (`report.html`...) are assumed to exist in the working directory. ### 5.1 HTML string to PDF This is the common case for web applications: render HTML with your template engine (Handlebars, EJS, Nunjucks, JSX to string) and convert it in memory. ```js const { PD4ML } = require('pd4ml'); const html = 'Order 1001
Thank you for your order.
'; const pd = new PD4ML(); pd.readHtmlString(html); const pdf = pd.writePDF(); // the PDF as a Buffer ``` `writePDF`, `writeDOCX` and `writeRTF` return the document as a `Buffer` when given no target. Given a file path, a file descriptor, or a writable stream (an HTTP response, an `fs.WriteStream`), they write into it. ### 5.2 Files and URLs ```js const { PD4ML } = require('pd4ml'); const pd = new PD4ML(); pd.readHTML('report.html'); // also: 'https://example.com/report', a URL object pd.writePDF('report.pdf'); ``` **Relative links** (`
`, ``) resolve against the
document's own location when it is read from a path or URL. When the HTML comes from a string or
a `Buffer`, pass the base location. Otherwise images and stylesheets go missing without an error
(see [reading the source](https://pd4ml.com/docs/#6.2-reading-the-source)):
```js
const { PD4ML } = require('pd4ml');
const html = 'Styled
'; const pd = new PD4ML(); pd.readHtmlString(html, '.'); // a directory, file path or URL pd.writePDF('styled.pdf'); ``` For a document in a known encoding other than UTF-8, call `pd.readHTML(buffer, baseUrl, 'windows-1251')`. To read from a stream, collect it into a Buffer first (`Buffer.concat(chunks)`, or `await new Response(stream).arrayBuffer()`). ### 5.3 Page size, orientation, margins and scaling ```js const { PD4ML, PageSize, PageMargins, Units } = require('pd4ml'); const pd = new PD4ML(); pd.setPageSize(PageSize.LETTER.rotate()); // landscape pd.setPageMargins(new PageMargins(15, 20, 15, 20, Units.MM)); // left, top, right, bottom pd.setHtmlWidth(1000); // the virtual browser width the page is laid out in pd.readHtmlString("| wide content |
$[title]
", 30, '1+');
pd.setPageFooter(
""
+ 'Invoice $[invoice] — $[customer] — page $[page] of $[total]
',
24, '1+');
pd.readHtmlString('Invoice
' + 'Line item
'.repeat(80)); pd.writePDF('invoice.pdf'); ``` The second argument is the area height in pixels. The third is the page scope: `'1'` (first page), `'2+'` (all but the first), `'odd'`, `'even'`, `'3-7'`... You can also write headers and footers inline in the HTML with PD4ML's extension tags. See [headers, footers, watermarks and backgrounds](https://pd4ml.com/docs/#8.-headers-footers-watermarks-and-backgrounds) and the [usage examples](https://pd4ml.com/docs/usage-examples.html#set-page-header-and-footer). ### 5.5 Watermarks and page backgrounds ```js const { PD4ML } = require('pd4ml'); const pd = new PD4ML(); pd.setWatermark("DRAFT", 120, 350, // left, top (px) 0.15, // opacity 45, // rotation, degrees 1, // scale true, true, // visible on screen, in print '1+'); // pages pd.setPageBackground("", '1+'); pd.readHtmlString('Proposal
'); pd.writePDF('draft.pdf'); ``` ### 5.6 Fonts PD4ML's built-in fonts cover Unicode broadly. For a specific typeface (a corporate font, CJK coverage), give it a font directory: ```js const { PD4ML } = require('pd4ml'); const pd = new PD4ML(); pd.useTTF('/opt/fonts', true); // a directory of TTF/OTF fonts (indexed: see below) pd.embedTTFs(true, false); // embed only the glyphs used pd.applyKerning(true); pd.enableLigatures(true); ``` Index a font directory once, ahead of time. PD4ML then reads the index (`pd4fonts.properties`) instead of scanning all the fonts on every conversion ([font indexing](https://pd4ml.com/docs/#4.3-font-indexing)): ``` java -jar..
pd.enableHyperlinks(true); // become clickable links (the default)
pd.readHtmlString("Introduction
...
Details
");
pd.writePDF('bookmarked.pdf');
```
PD4ML's `` tag generates a table of contents with page numbers from the headings; see
the [usage examples](https://pd4ml.com/docs/usage-examples.html#add-toc). For explicit page
breaks, use CSS `page-break-before` / `break-before`, or ``.
### 5.8 PDF/A and PDF/UA
```js
const { PD4ML, PdfSpec, Constants } = require('pd4ml');
const pd = new PD4ML();
pd.readHtmlString("Annual report Annual report
");
pd.writePDF('archive.pdf', PdfSpec.PDFA_3B); // archival
pd.writePDF('accessible.pdf', PdfSpec.PDFUA_1); // accessible
pd.writePDF('both.pdf', PdfSpec.PDF_1_7.combine(PdfSpec.PDFA_2A));
pd.writePDF('keyword.pdf', 'pdf/a-2b'); // by keyword
const status = pd.getLastRenderInfo(Constants.PD4ML_PDFA_STATUS); // after writing
```
`PdfSpec.listKeywords()` lists the keywords; an unknown one throws a `RangeError`
(`PdfSpec.getInstance` alone would fall back to PDF 1.7 without an error).
- PDF/A embeds all fonts.
- PDF/UA needs well-structured HTML: real headings, `alt` texts, `lang`, table headers.
Combine it with `pd.setErrorPolicy(ErrorPolicy.PEDANTIC)` to be told when the source does not
satisfy the standard.
Details: [PDF/A, PDF/UA and e-invoicing](https://pd4ml.com/docs/#11.2-pdfa-pdfua-and-e-invoicing-formats).
### 5.9 ZUGFeRD / Factur-X e-invoices
`PdfSpec.ZUGFeRD` and `PdfSpec.FacturX` select the PDF/A-3 container the standards require. The
HTML attaches the invoice XML with PD4ML's attachment tag. The
[ZUGFeRD and Factur-X page](https://pd4ml.com/docs/features/zugferd-and-factur-x-pdf-invoices.html)
has the complete recipe, including the required attachment names.
```js
const { PD4ML, PdfSpec } = require('pd4ml');
const pd = new PD4ML();
pd.readHTML('invoice.html'); // contains the of factur-x.xml
pd.writePDF('invoice.pdf', PdfSpec.FacturX);
```
### 5.10 Passwords and permissions
```js
const { PD4ML, Constants } = require('pd4ml');
const pd = new PD4ML();
pd.setPermissions('owner-secret', Constants.AllowPrint | Constants.AllowCopy, Constants.AES_256BIT);
pd.readHtmlString('Confidential
');
pd.writePDF('protected.pdf');
```
Combine the `Allow*` flags with `|`, or start from `Constants.DefaultPermissions` and remove flags
with `& ~`. Encryption needs the Bouncy Castle jars, which the installation downloads. See
[permissions and encryption](https://pd4ml.com/docs/#11.1-permissions-and-encryption).
### 5.11 Word (DOCX, RTF) and images
```js
const { PD4ML, Constants } = require('pd4ml');
const pd = new PD4ML();
pd.readHtmlString('Letter
Dear customer, ...
');
pd.writeDOCX('letter.docx');
pd.writeRTF('letter.rtf');
const pages = pd.renderPng(); // a PNG Buffer per page
const tiffs = pd.renderAsImages(Constants.TIFF); // one TIFF per page
pd.renderAsImages('pages', 'page', Constants.PNG24); // page files in a directory
```
The image formats are `PNG8`, `PNG24`, `TIFF` and `TIFF_COMPRESSED` (constants in `Constants`).
The TIFF formats need Java 9 or later.
The v42 engine does not support the multi-page TIFF formats yet; use the v40 engine for them.
With the v42 engine, DOCX/RTF output can be made *editable*: positioned content becomes text
boxes and form fields instead of pictures. To enable it, call
`pd.setParam(Constants.PD4ML_WORD_EDITABLE, 'true')`.
### 5.12 Interactive forms and multi-column layout
```js
const { PD4ML } = require('pd4ml');
const pd = new PD4ML();
pd.generateForms(true, null); // /
Introduction
...
Details
"); pd.writePDF('bookmarked.pdf'); ``` PD4ML's `Annual report
"); pd.writePDF('archive.pdf', PdfSpec.PDFA_3B); // archival pd.writePDF('accessible.pdf', PdfSpec.PDFUA_1); // accessible pd.writePDF('both.pdf', PdfSpec.PDF_1_7.combine(PdfSpec.PDFA_2A)); pd.writePDF('keyword.pdf', 'pdf/a-2b'); // by keyword const status = pd.getLastRenderInfo(Constants.PD4ML_PDFA_STATUS); // after writing ``` `PdfSpec.listKeywords()` lists the keywords; an unknown one throws a `RangeError` (`PdfSpec.getInstance` alone would fall back to PDF 1.7 without an error). - PDF/A embeds all fonts. - PDF/UA needs well-structured HTML: real headings, `alt` texts, `lang`, table headers. Combine it with `pd.setErrorPolicy(ErrorPolicy.PEDANTIC)` to be told when the source does not satisfy the standard. Details: [PDF/A, PDF/UA and e-invoicing](https://pd4ml.com/docs/#11.2-pdfa-pdfua-and-e-invoicing-formats). ### 5.9 ZUGFeRD / Factur-X e-invoices `PdfSpec.ZUGFeRD` and `PdfSpec.FacturX` select the PDF/A-3 container the standards require. The HTML attaches the invoice XML with PD4ML's attachment tag. The [ZUGFeRD and Factur-X page](https://pd4ml.com/docs/features/zugferd-and-factur-x-pdf-invoices.html) has the complete recipe, including the required attachment names. ```js const { PD4ML, PdfSpec } = require('pd4ml'); const pd = new PD4ML(); pd.readHTML('invoice.html'); // contains theConfidential
'); pd.writePDF('protected.pdf'); ``` Combine the `Allow*` flags with `|`, or start from `Constants.DefaultPermissions` and remove flags with `& ~`. Encryption needs the Bouncy Castle jars, which the installation downloads. See [permissions and encryption](https://pd4ml.com/docs/#11.1-permissions-and-encryption). ### 5.11 Word (DOCX, RTF) and images ```js const { PD4ML, Constants } = require('pd4ml'); const pd = new PD4ML(); pd.readHtmlString('Letter
Dear customer, ...
'); pd.writeDOCX('letter.docx'); pd.writeRTF('letter.rtf'); const pages = pd.renderPng(); // a PNG Buffer per page const tiffs = pd.renderAsImages(Constants.TIFF); // one TIFF per page pd.renderAsImages('pages', 'page', Constants.PNG24); // page files in a directory ``` The image formats are `PNG8`, `PNG24`, `TIFF` and `TIFF_COMPRESSED` (constants in `Constants`). The TIFF formats need Java 9 or later. The v42 engine does not support the multi-page TIFF formats yet; use the v40 engine for them. With the v42 engine, DOCX/RTF output can be made *editable*: positioned content becomes text boxes and form fields instead of pictures. To enable it, call `pd.setParam(Constants.PD4ML_WORD_EDITABLE, 'true')`. ### 5.12 Interactive forms and multi-column layout ```js const { PD4ML } = require('pd4ml'); const pd = new PD4ML(); pd.generateForms(true, null); // /