Skip to main content

JSON to PDF

renderDocumentJson() turns a single, fully serializable value into PDF bytes — no callbacks, no in-memory font or image handles. Everything the document needs (metadata, fonts, images, headers/footers, encryption, and absolute-positioned content) is described as plain JSON, so a document can come straight from a config file, an API request, or an LLM.

import { renderDocumentJson } from "@barrierbreak/a11ydocs-pdf";

const bytes = await renderDocumentJson({
title: "Hello",
blocks: [
{ type: "heading", text: "Invoice #42", options: { level: 1 } },
{ type: "paragraph", text: "Thanks for your business." }
]
});

It is a thin layer over createDocument() and renderTemplate(): the body blocks are the same template blocks, and renderDocumentJson adds the three things a template spec cannot carry as JSON — declared fonts, image bytes, and data-driven headers/footers — plus document-level options at the root.

renderDocumentJson is asynchronous because fonts and images may load from disk or the network. For a fully inline document (every asset is base64), renderDocumentJsonSync() returns the bytes directly.

The document shape​

PdfDocumentJson is the input type. Every field is optional except blocks.

interface PdfDocumentJson {
// Document options (applied at creation)
title?: string;
info?: DocumentInfo;
language?: string; // BCP 47, e.g. "en-US"
tagged?: boolean; // accessible structure tree
conformance?: DocumentConformanceProfile; // "pdfa-2b", "pdfua-1", …
compress?: boolean;
encryption?: DocumentEncryptionOptions;
defaultPageSize?: PageSize;

// Assets, declared once and referenced by name
fonts?: JsonFontDeclaration[];
defaultFont?: string;
defaults?: TextDefaults;

// Layout
page?: TemplatePageOptions; // size, margin, header/footer heights
styles?: TemplateStylesheet;
pageNumber?: TemplatePageNumberOptions;
autoOutline?: boolean | TemplateAutoOutlineOptions;
strictLayout?: boolean | TemplateStrictLayoutOptions;

// Header / footer as data (page tokens interpolated)
header?: JsonBlock[];
footer?: JsonBlock[];

// Body — required, non-empty
blocks: JsonBlock[];
}

Block types, styles, and page options are identical to the template API; see Template Stylesheets for styles.

Fonts​

Declare fonts once under fonts, then reference them by name from any block's font option (a registered family name is a valid PdfFont). Each source is base64, a file path (Node), a url, or a Google Fonts lookup.

await renderDocumentJson({
fonts: [
{ name: "Body", source: { google: { family: "Inter" } } },
{ name: "Mono", source: { path: "fonts/JetBrainsMono.ttf" } },
{ name: "Brand", source: { base64: "<base64 ttf>" } }
],
defaultFont: "Body",
blocks: [
{ type: "paragraph", text: "Set in Inter.", options: { font: "Body" } },
{ type: "paragraph", text: "code()", options: { font: "Mono" } }
]
});

A font may declare weighted faces so the bold / italic flags resolve:

{
name: "Body",
source: {
regular: { google: { family: "Inter" } },
bold: { google: { family: "Inter", weight: 700 } }
}
}

No fonts and no defaultFont falls back to the engine's built-in font, which renders Latin text without an embed.

Images​

Image blocks carry a src instead of raw bytes — base64, a file path, or a url:

blocks: [
{ type: "png", src: { path: "assets/logo.png" }, options: { width: 96 } },
{ type: "jpeg", src: { base64: "<base64 jpeg>" }, options: { width: 200 } }
]

The block type is the image format (png, jpeg, bmp, jbig2, tiff, jp2, webp, gif, svg).

Headers and footers​

In the template API, headers and footers are callbacks. Over JSON they are static block arrays with tokens interpolated on every page: {{pageNumber}}, {{pageCount}} (alias {{totalPages}}), {{title}}, and {{author}}.

await renderDocumentJson({
title: "Quarterly Report",
page: { size: "A4", footerHeight: 40 },
footer: [
{ type: "paragraph", text: "{{title}} — page {{pageNumber}} of {{pageCount}}" }
],
blocks: [/* … */]
});

Document options​

Encryption, conformance, language, tagged structure, and metadata live on the root and are applied when the document is created:

await renderDocumentJson({
tagged: true,
language: "en-US",
conformance: "pdfua-1",
encryption: { userPassword: "open-sesame", algorithm: "aes-256" },
blocks: [{ type: "paragraph", text: "Confidential." }]
});

Absolute positioning (coordinate system)​

A block flows by default. Add a position and it is drawn at exact PDF-point coordinates instead — useful for stamps, labels, logos, and form fields placed on a designed page. Positioned and flow blocks mix freely in the same blocks array.

interface BlockPosition {
x: number;
y: number;
width?: number; // required for `rect` and image blocks
height?: number;
page?: number; // 1-based; pages are created as needed. Default 1.
origin?: "bottom-left" | "top-left"; // default "bottom-left"
}
await renderDocumentJson({
page: { size: "A4" },
blocks: [
{ type: "paragraph", text: "Body text flows normally." },

// Placed at exact coordinates:
{ type: "paragraph", text: "PAID", options: { fontSize: 28, color: "red" },
position: { x: 400, y: 736 } },
{ type: "rect", width: 130, height: 48,
style: { paint: "stroke", stroke: { color: "red", width: 2 } },
position: { x: 380, y: 720 } },
{ type: "textField", name: "signature",
position: { x: 72, y: 600, width: 220, height: 14 } }
]
});

Coordinates are in PDF points. With the default bottom-left origin, y grows upward; set origin: "top-left" on a block to measure from the top. See the coordinate system.

Positionable block types: paragraph, the image formats (png, jpeg, …), rect, textField, checkBox, signatureField. A position on any other type (for example table or list) throws INVALID_DOCUMENT_JSON. A positioned paragraph is a single line — the page text API does not wrap, so width/height are ignored for it.

A document whose blocks are all positioned (no flow content) is valid; blank pages are created up to the highest page referenced, and each created page must receive at least one block.

Synchronous rendering​

When every font and image source is inline base64, render without await:

import { renderDocumentJsonSync } from "@barrierbreak/a11ydocs-pdf";

const bytes = renderDocumentJsonSync({
blocks: [{ type: "paragraph", text: "No async assets here." }]
});

path, url, and google sources require loading and throw INVALID_DOCUMENT_JSON in the sync variant — use renderDocumentJson for those.

Node and the browser​

base64, url (fetch), and google sources work in both Node and the browser. A path source reads from the filesystem and is Node-only; node:fs is imported lazily, only when a path appears, so the browser bundle stays clean. See Browser Usage.

What JSON cannot express​

The format covers the full declarative surface but not the callback-based or low-level imperative APIs:

  • Custom blocks (render(flow) callbacks) — see Custom Blocks.
  • Digital signing — DocumentSignatureOptions.sign is a callback; sign with the programmatic API (see Digital Signatures).
  • pageNumber.format callback — use footer tokens for numbering.
  • Free imperative drawing beyond positioned blocks — soft masks, blend modes, transparency groups, and arbitrary PdfPage graphics.

For those, drop down to createDocument() and the page/flow APIs.

Validation​

A malformed document throws PdfEngineError with code INVALID_DOCUMENT_JSON and a message that names the offending path — for example a missing blocks array, an undeclared font name, a bad image src, or a position on a non-positionable block. The caller's input object is never mutated during rendering.

API reference​