Skip to content
LpdfDocsv0.36-r1119.4

Lpdf is pre-release. The XML schema and SDK APIs can change between releases.

Installation

Lpdf generates PDF from XML, or from code that builds the same document. One engine runs in every SDK, so the output is identical on every platform. It is compiled to WebAssembly for the JavaScript SDK, to a WASI binary for the Python, Java, C#, and PHP SDKs (Java runs it compiled to JVM classes), and to a native library for PHP on Linux.

The examples in these docs are XML, and they work in every language: pass the XML to render, as under Create PDF below. Most examples also show the same document built in code, in a tab for each language, as under Create PDF with code. The builders are the same in every language: the same elements, the same attributes under the schema’s names, and the same constants, written in each language’s own case (fontSize in JavaScript, Java and PHP, font_size in Python, FontSize in C#).

  • Node.js 20 or later
  • No external runtime dependencies — the WASM engine is bundled in the package
Terminal window
npm install @lpdfio/lpdf
import { L } from '@lpdfio/lpdf'
import { writeFileSync } from 'node:fs'
const xml = `<lpdf version="1">
<document size="a4">
<section>
<layout margin="48pt">
<column gap="m">
<text font-size="xl">Hello, world</text>
<text>This PDF was made with Lpdf.</text>
</column>
</layout>
</section>
</document>
</lpdf>`
const engine = L.engine()
engine.render(xml).then((pdf) => writeFileSync('hello.pdf', pdf))

render returns a promise. The example is an ES module: save it as hello.mjs, or set "type": "module" in package.json. CommonJS loads the package with require and gets the same classes:

const { L } = require('@lpdfio/lpdf')

From 0.28.1 the package loads either way. Earlier versions load with require only: an import of @lpdfio/lpdf fails with ERR_PACKAGE_PATH_NOT_EXPORTED. To render a file, read it into a string and pass that to render.

The same document, built with L instead of written as XML. render takes either one and makes the same PDF.

import { L, NoAttr } from '@lpdfio/lpdf'
import { writeFileSync } from 'node:fs'
const doc = L.document({ size: 'a4' }, [
L.section(NoAttr, [
L.layout({ margin: '48pt' }, [
L.column({ gap: 'm' }, [
L.text({ fontSize: 'xl' }, ['Hello, world']),
L.text(NoAttr, ['This PDF was made with Lpdf.']),
]),
]),
]),
])
const engine = L.engine()
engine.render(doc).then((pdf) => writeFileSync('hello.pdf', pdf))

The first two numbers are the Lpdf engine, and the last number counts changes to this package only. 0.22.3 runs engine 0.22. Every engine release publishes all SDKs at X.Y.0, so the same X.Y means the same engine in every language. To stay on one engine and still get package fixes, use a tilde range in package.json:

"@lpdfio/lpdf": "~0.22.0"

A render stops after 5 seconds with the SDK’s render error, which names the limit: The render timed out after 5 seconds. A PDF renders in milliseconds, so a render that runs that long is a document far larger than usual or a fault in the engine, and stopping it frees the thread or the process it held. timeout on the engine sets another limit, in seconds, and timeout: 0 sets none. A render stopped at its limit leaves the engine as it was, and the next render runs as usual.

import { L } from '@lpdfio/lpdf'
const engine = L.engine({ timeout: 60 })

A render runs on a worker thread, one at a time, so it doesn’t hold up the event loop. At its limit the render rejects with an LpdfRenderError, the worker is stopped, and the next render starts a new one. In the browser, initLpdf(wasmUrl, licenseKey, { timeout: 60 }) takes the same option, and renders run on a Web Worker started from a blob: URL: a page with a Content-Security-Policy allows blob: in worker-src.

A render may allocate 1024 MB, which holds thousands of pages of text and tables. One that needs more stops with the SDK’s render error, which names the cap: the render needs more memory than its cap of 1024 MB: raise the cap in the engine's options, or render the document in smaller parts. What counts is what the render allocates, the data it binds included. In the Python, Java, C# and PHP SDKs the fonts, images and files sent with a render count too; in JavaScript what is loaded on the engine before the render doesn’t. There is no limit on the size of the XML or of a document built in code. maxMemoryMb on the engine sets another cap, a whole number of megabytes from 1 to 4096: lower in a small container, higher for a big document on a machine with the memory for it. 4096 is the most the engine can address as a 32-bit WebAssembly module, and PHP’s native library keeps the same range. A render stopped at its cap leaves the engine as it was, and the next render runs as usual.

If the engine crashes, by a fault in it or a render that runs out of memory before its cap stops it, the render fails with the same message in every SDK: The engine crashed during the render. This is a bug in Lpdf, or the render ran out of memory before its cap stopped it: please report it with the document at https://github.com/lpdfio/lpdf/issues. The next render runs on a fresh engine. PHP’s native library is the exception, below.

import { L } from '@lpdfio/lpdf'
const engine = L.engine({ maxMemoryMb: 2048 })

Past the cap the render rejects with an LpdfRenderError. In the browser, initLpdf(wasmUrl, licenseKey, { maxMemoryMb: 2048 }) takes the same option. After a crash the error’s cause holds the engine’s own error, and the worker is replaced for the next render.

An image or a font that comes from a file is declared in assets with a src path. The SDK reads the file from the machine that renders the PDF, so a relative path is relative to the working directory: JavaScript, Python and PHP on their own, Java and C# only through the engine’s SrcFallback (srcFallback in Java), as under Attachments. The engine does not fetch URLs or read data URIs. An image file the SDK cannot read is an error, and a font file it cannot read falls back to Helvetica without one. To supply the bytes yourself, call loadImage(name, bytes) or loadFont(name, bytes) on the engine and leave src out.

Asset names use lowercase letters, digits, and -, and start with a letter: logo, serif-bold.