pdfkit 0.20.0

v0.20.0

on Node.js NPM

Highlights

TLDR: "A PDF generation library for Node.js" -> "A JavaScript PDF generation library"

Standard Font Support rewritten

Standard font support has been rewritten to use pre-parsed font metrics instead of parsing raw AFM definitions at runtime. The new approach is more efficient (less runtime overhead and memory usage) and reduces the size of the browser bundle significantly. Standalone build which bundles all standard fonts is down to 1.3MB from 2.3MB.

In Node, font metrics are loaded lazily as before, while in browser builds, except the standalone one, each font must be imported from pdfkit/standard-fonts/* and registered with registerStdFonts(). Previously, to use a standard font in browser was necessary to use a bundler.

See usage example in output helpers section below.

Removal of Node specific dependencies

Buffer is no longer used internally. Uint8Array is now the minimum denominator for binary data in both Node and browsers. Since Buffer is a Uint8Array subclass, this change is fully backward compatible.

Native fs, zlib and ReadableStream are conditionally imported only in Node. Browser builds use minimal implementations. This approach gives us the best of both worlds: Node builds still use the native modules, while browser ones are portable.

Many thanks to @diegomura for his help in removing the Node specific dependencies.

registerFile API

The new registerFile(path, data) API allows registering in-memory files globally. The data argument must be a Uint8Array. Passing undefined as data unregisters the path.

In browsers, it can be used as a simplified virtual file system. In Node, this is useful for registering fonts, images and other resources that are not available on disk. The native file system is still used when the path is not registered.

import { PDFDocument, registerFile } from 'pdfkit';

const response = await fetch('/fonts/Roboto-Regular.ttf');
const fontData = new Uint8Array(await response.arrayBuffer());

registerFile('fonts/Roboto-Regular.ttf', fontData);

const doc = new PDFDocument();

// register an alias for the font path
doc.registerFont('Roboto', 'fonts/Roboto-Regular.ttf');
// or use the path directly
doc.font('fonts/Roboto-Regular.ttf');

// Optionally unregister the path when it is no longer needed.
registerFile('fonts/Roboto-Regular.ttf', undefined);

toBytes and toBlob output helpers

Experimental toBytes(document) and toBlob(document) output helpers are available under pdfkit/output. They return a Promise that resolves to a contiguous Uint8Array or a Blob, respectively. These helpers are useful when a binary API, worker or parser needs one contiguous Uint8Array or a Blob.

import { PDFDocument, registerStdFonts } from 'pdfkit';
import Helvetica from 'pdfkit/standard-fonts/Helvetica';
import HelveticaBold from 'pdfkit/standard-fonts/HelveticaBold';
import { toBlob } from 'pdfkit/output';

registerStdFonts(Helvetica, HelveticaBold);
const doc = new PDFDocument();
const output = toBlob(doc);

// Add your content to the document here, as usual.

doc.end();
const blob = await output;
const url = URL.createObjectURL(blob);
iframe.src = url;

// Revoke the URL when the iframe no longer needs the PDF.
// URL.revokeObjectURL(url);

Named exports

Added named exports for PDFDocument from the main Node and browser entry points while preserving the default PDFDocument export. This will make it easier to transition to ESM in the future. LineWrapper and registerFile are also exported as named exports.

by @blikblum (written by hand)

CHANGELOG

• [BREAKING CHANGE] Remove the virtual file system (pdfkit/virtual-fs). Browser builds no longer depend on fs: use registerFile to register Uint8Array data under a path, pass a Uint8Array or ArrayBuffer directly to registerFont, image and file, or pass a data URL directly to image and file
• Add registerFile(path, data, options) to globally register in-memory files in Node and browsers, with optional birthtime and ctime metadata. Passing undefined as data unregisters the path
• [BREAKING CHANGE] Export PDFDocument, LineWrapper and registerFile as named exports from the main Node and browser entry points while preserving the default PDFDocument export
• Add experimental toBlob(document) and toBytes(document) output helpers under pdfkit/output
• Accept already-parsed fontkit Font instances in doc.font() and registerFont
• Load the PDF/A ICC profile from disk only when needed in Node, while continuing to bundle it in browser builds
• Add tools to convert raw AFM standard-font definitions into parsed or compact runtime JavaScript modules
• [BREAKING CHANGE] Use generated standard-font data instead of parsing raw AFM definitions at runtime. Node loads font metrics lazily; browser applications must import each font they use from pdfkit/standard-fonts/* and register it with registerStdFonts()
• [BREAKING CHANGE] Restrict AcroForm options to documented mappings and explicit escape hatches.
• [BREAKING CHANGE] Stop automatically uppercasing annotation option keys.
• [BREAKING CHANGE] Throw from addNamedEmbeddedFile when no ref is given, instead of writing an unparseable undefined token into the /EmbeddedFiles name tree
• Do not mutate options passed to doc.annotate() and its convenience methods (link, note, strike, lineAnnotation, rectAnnotation, ellipseAnnotation, textAnnotation, fileAnnotation)
• Persist font options when adding a new page. Fixes #1739
• Use Uint8Array instead of Node's Buffer internally
• Fix date text field formatting emitting invalid JavaScript, so the format was never applied. Fixes #1546
• Fix indentAllLines applying the indent again on every paragraph and every page break, and keep it applied across continued text. Fixes #1606
• Fix a hole in a sparse array being skipped entirely, which shifted every later entry down one
• Encrypt strings inside name trees. Fixes #1513