Skip to content

About

Declarative React reconciler for pdfnative. Compile JSX directly to on-device, accessible PDF/A documents. No DOM dependencies, no headless browsers, no SaaS round-trips. Built for Edge and offline-first apps.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

38 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

pdfnative-react

npm version CI License: MIT TypeScript pdfnative OpenSSF Scorecard

Write PDFs the way you write UIs. pdfnative-react turns declarative JSX into real, on-device PDF documents powered by the zero-dependency pdfnative engine — no DOM, no headless browser, no SaaS round-trips. Your documents never leave the process.

import { Document, Heading, Text, Table, renderToBytes } from 'pdfnative-react';

const bytes = renderToBytes(
    <Document title="Invoice #1024" footerText="Acme Inc">
        <Heading level={1}>Invoice #1024</Heading>
        <Text>Thank you for your business.</Text>
        <Table
            headers={['Item', 'Qty', 'Total']}
            rows={[
                { cells: ['Pro plan', '1', '$49.00'], type: 'default', pointed: false },
            ]}
            zebra
        />
    </Document>,
);
// → Uint8Array, a valid PDF (%PDF-… …%%EOF)

Why pdfnative-react

  • Declarative & familiar. 19 components mirror @react-pdf/renderer ergonomics (Document, Page, Text, Image, Link, usePdf, PDFViewer, PDFDownloadLink, BlobProvider).
  • On-device. A custom React reconciler compiles your tree — synchronously, with no DOM — to the pdfnative model and renders the bytes locally.
  • Honest model. Components map 1:1 onto pdfnative blocks. There is no CSS/flexbox engine and no <View> — it is a declarative block flow.
  • Fine typography. Paragraphs that split across pages under widow and orphan rules, headings kept with what follows, justification with hanging punctuation, kerning, OpenType features, units and short words that never break — all opt-in. See Typography.
  • Print colour and PDF/X-4. CMYK and named spot inks (/Separation, /DeviceN mixes) on every painted colour position (outline bookmarks stay process RGB, as the PDF specification says), colour bars in the bleed, CMYK and Gray output intents, the PDF/X-4 conformance claim — alone or combined with PDF/A-2 in one file — with every constraint linted before the render. See Print.
  • Right-to-left and bidirectional text. direction="auto" | "rtl" | "ltr" on the document or per paragraph; Arabic and Hebrew lines wrap from the right under the full UAX #9 algorithm, and every right-to-left run carries its logical text as /ActualText, so extraction returns the source string.
  • JPEG 2000 images. A JP2 file or a raw J2K codestream passes straight through as /JPXDecode — never decoded, never re-encoded — in <Image> and in watermarks, with a lint rule for the PDF/A constraints.
  • Byte-reproducible. Pin creationDate and the same document renders to the same bytes on every host, in every time zone — proven by the repository on Linux, Windows and macOS. See Reproducible output.
  • Server-ready. renderToResponse returns a web-standard Response, streaming by default — one line in a Next.js route handler, and the same code on Edge, Deno, Bun and Workers. See Server rendering.
  • Token-frugal AI authoring. A compact DocSpec lets LLM agents emit documents with a fraction of the tokens of JSX, validated by a versioned JSON Schema — see Agent authoring.
  • Autonomously usable. doctor(), capabilityManifest(), validateSpec() and a stable E_* error taxonomy let an agent check the environment, discover the API and verify its own output before rendering — see the agent contract.
  • Checks its own work. lintDocument reports accessibility problems and pre-empts the engine constraints that would otherwise throw mid-render — 41 lint rules, see Linting.
  • Validated against veraPDF and validatePdfX. A PDF/A and PDF/X corpus covering both authoring doors is validated with the pinned veraPDF reference validator and the engine's PDF/X validator — locally and as a blocking gate, with negative canaries the validators must reject. See CONTRIBUTING.md.
  • 32 Unicode scripts. Every bundled font module of the engine — Latin with its tone-marked African languages, Arabic, Hebrew, the Indic family down to Gujarati, Gurmukhi, Kannada, Malayalam and Odia, Thai, Lao, Khmer, Myanmar, Tai Tham, Cham, CJK, colour emoji and more — through one resolveFonts call, embedded as lean subsets.
  • Typed, tested, tree-shakeable. Strict TypeScript, dual ESM + CJS with per-condition types, source maps, provenance-signed publishes, 949 tests.

Install

npm install pdfnative-react pdfnative react

Requires React 19, pdfnative ≥ 1.9, and Node.js ≥ 22 (the engine's own floor since 1.6.0).

Components

Every component maps 1:1 onto a pdfnative block.

Component Renders
Document The required root (title, footerText, metadata, fontEntries, layout, outline, pageLabels, watermark, header, footer, attachments, tagged, print, pdfx, outputIntent, typography, creationDate, direction).
Page An explicit page boundary (content auto-paginates otherwise).
Section Sugar: a heading grouped with its content (title, level, color, break).
Heading A section heading (level 1–3, keepWithNext); feeds the auto TableOfContents.
Paragraph / Text A wrapping paragraph (fontSize, lineHeight, align incl. 'justify', indent, color, keepWithNext, splittable, direction).
List / Item A bullet or numbered (ordered) list; items may nest sub-lists.
Table / Row / Cell A data table (headers/rows or JSX children; cellBorders, cellVAlign, zebra, caption, …).
Image An embedded JPEG, PNG (no alpha channel — flatten colour types 4 and 6 first) or JPEG 2000 (data: Uint8Array; a JP2 file or a J2K codestream passes through as /JPXDecode).
Link A clickable hyperlink (url/href).
Spacer Vertical whitespace (height).
PageBreak A hard page break.
TableOfContents / Toc An auto-generated TOC built from headings.
Barcode QR, Code 128, EAN-13, PDF417, Data Matrix (format, data).
Svg Inline vector graphics (path data or markup; <text> renders as selectable PDF text).
Chart Native vector charts — bar, barH, line, pie, donut, stackedBar, stackedBarH, area, scatter; log/time scales, dual axes, data labels, one colour per bar (series.colors) (guide).
FormField Interactive AcroForm widgets (fieldType, name).

Every color prop — and chart palettes, table borders and zebra stripes, watermarks, headers and footers — accepts a hex string, an RGB tuple, a CMYK tuple in percent ([0, 60, 100, 0]), a PDF operator string, or a named ink declared under print.spotColours: { spot: 'PANTONE 300 C', tint: 0.5 } (a /Separation) or { inks: { 'PANTONE 300 C': 1, Varnish: 0.3 } } (a /DeviceN mix).

Document-level page furniture

watermark, header, footer, attachments, tagged, print, pdfx, outputIntent, typography, creationDate and direction are props on <Document> rather than components, because they are page furniture, not blocks in the flow. They fold into layout under the engine's own keys, and an explicit layout prop always wins.

<Document
    watermark="DRAFT"                                  // or the full WatermarkOptions
    header={{ left: 'Acme Inc', right: '{date}' }}
    footer={{ center: '{title}', right: 'Page {page} of {pages}' }}
    tagged="pdfa3b"
    attachments={[{ filename: 'data.xml', data, mimeType: 'application/xml' }]}
    print={{ bleed: 14.17, marks: { crop: true, colourBars: true } }}   // print production (engine ≥ 1.7; colour bars ≥ 1.8)
    typography={{ splitParagraphs: true, orphans: 2, widows: 2 }}       // engine ≥ 1.8
    creationDate="2026-01-01T00:00:00Z"                                 // byte-reproducible output
    direction="auto"                                                    // engine ≥ 1.9; 'ltr' | 'rtl' force it
/>

Header and footer templates resolve {page}, {pages}, {date} and {title} at render time ({date} follows a pinned creationDate). print adds bleed/trim/art/crop boxes, vector printer's marks, colour bars and large-format userUnit, and declares named inks under print.spotColours; metadata.trapped and the print-dialog viewer preferences (duplex, printPageRange, numCopies, pickTrayByPDFSize under layout.viewerPreferences) complete the prepress surface — see samples/layout/print-production.tsx. tagged and pdfx combine: tagged="pdfa2b" or "pdfa2u" beside pdfx="pdfx4" writes both identifications into one file (PDF/A-1 and PDF/A-3 stay incompatible with PDF/X-4, and L_PDFX_TAGGED_CONFLICT says why). direction sets the base text direction of every paragraph ('auto' detects it from the first strong character; <Paragraph direction> overrides it per block); omitted, the output is byte-identical to 1.3.

Typography

<Document
    fontEntries={fontEntries}                                    // kerning, features and 'fr' need a registered font
    typography={{
        splitParagraphs: true, orphans: 2, widows: 2,            // paragraphs break across pages, never leaving a lone line
        keepHeadingsWithNext: { minLines: 3 },                   // a heading takes three lines of its paragraph along
        unitBinding: true, bindShortWords: true,                 // "150 €", "12 kg" and "a" never end a line
        punctuationSpacing: 'fr',                                // narrow no-break spaces before ; ! ? — 'fr-CA' too
        opticalMargins: true, kerning: true,                     // hanging punctuation, GPOS pair kerning
        fontFeatures: ['smcp', 'onum'], metrics: 'exact',        // OpenType features; Adobe Core 14 advances for base-14 text
    }}
>
    <Heading level={2} keepWithNext>Results</Heading>
    <Paragraph align="justify" splittable>…</Paragraph>
</Document>

All twelve keys are off by default: a document that sets none renders byte-identically to earlier releases. align="justify" is paragraph-only (ParagraphAlign = Align | 'justify'). No hyphenation dictionary ships — soft hyphens (U+00AD) are honoured and setHyphenationProvider accepts yours. Anything a font cannot deliver is a lint finding (L_TYPOGRAPHY_INEFFECTIVE) before it is an engine diagnostic. Guide: docs/TYPOGRAPHY.md.

Right-to-left text

const fontEntries = await resolveFonts({
    ar: () => import('pdfnative/fonts/noto-arabic-data.js'),
    he: () => import('pdfnative/fonts/noto-hebrew-data.js'),
});

<Document fontEntries={fontEntries} direction="auto">   // 'auto' | 'ltr' | 'rtl'
    <Paragraph>{arabicText}</Paragraph>                 // set from the right margin
    <Paragraph direction="ltr">{englishText}</Paragraph> // per-block override
</Document>

direction="auto" resolves each paragraph's base direction from its first strong character (UAX #9 P2–P3); 'rtl' and 'ltr' force it. Digits, brackets and punctuation pair and mirror under the full bidirectional algorithm, and every right-to-left run carries its logical text as an /ActualText span, so extractText and copy-paste return the source string (layout.actualText: false opts out). Omit direction and the document renders byte-identically to 1.3. Sample: samples/text/rtl-direction.tsx.

Print colour and PDF/X-4

<Document
    pdfx="pdfx4"
    fontEntries={fontEntries}
    metadata={{ trapped: 'False' }}
    outputIntent={{ iccProfile: pressProfile, outputConditionIdentifier: 'FOGRA39' }}   // a prtr profile — none is bundled
    print={{ bleed: 14.17, marks: { crop: true, registration: true, colourBars: true } }}
>
    <Heading level={1} color={[0, 0, 0, 100]}>Press sheet</Heading>
    <Paragraph color="0 1 1 0">Set in DeviceCMYK.</Paragraph>
</Document>

pdfx="pdfx4" writes the PDF/X-4 identification, a /GTS_PDFX output intent, a TrimBox per page and /Trapped. Every constraint the engine enforces — an output intent with a printer profile, a known trapping state, embedded fonts, no PDF/A-1 or PDF/A-3 claim beside it, no encryption, a TrimBox or an ArtBox — is an L_PDFX_* lint rule before it is a throw. Check the bytes with the engine's validatePdfX() (recipe); a valid result means the structural prerequisites hold, not that a certified preflight passed. Guide: docs/PRINT.md.

Spot colours. Declare the press inks once under print.spotColours, then paint with them anywhere a colour goes — headings, paragraphs, links, table borders and zebra stripes, chart palettes, watermarks, headers and footers:

<Document
    pdfx="pdfx4"
    print={{
        bleed: 14.17,
        spotColours: [
            { name: 'Brand Blue', alternate: [100, 44, 0, 0] },   // CMYK alternate, in percent
            { name: 'Varnish', alternate: [0, 0, 0, 8] },
        ],
    }}
>
    <Heading level={1} color={{ spot: 'Brand Blue' }}>One plate of its own</Heading>
    <Paragraph color={{ spot: 'Brand Blue', tint: 0.5 }}>A 50 % tint — a /Separation space.</Paragraph>
    <Paragraph color={{ inks: { 'Brand Blue': 1, Varnish: 0.6 } }}>An ink mix — a /DeviceN space.</Paragraph>
</Document>

An ink that is not declared is L_SPOT_UNDECLARED, a mix across alternate spaces (CMYK beside RGB) is L_SPOT_INK_MIX, a bad declaration is L_PRINT_BOXES — each before the engine's own throw, which arrives as E_INPUT when the linter is skipped. Sample: samples/layout/print-spot-colours.tsx.

PDF/A-2 and PDF/X-4 in one file. tagged="pdfa2b" (or "pdfa2u") combines with pdfx="pdfx4": the file carries both XMP identifications and passes veraPDF and validatePdfX alike. PDF/A-1 (PDF 1.4) and PDF/A-3 (embedded files) remain incompatible with PDF/X-4, which is what L_PDFX_TAGGED_CONFLICT now fires on. Sample: samples/layout/print-dual-pdfa2b-pdfx4.tsx.

Reproducible output

<Document creationDate={new Date('2026-01-01T00:00:00Z')}>   // this document
setDefaultCreationDate(new Date('2026-01-01T00:00:00Z'));    // every document in this process

Every date the engine writes is UTC; the {date} placeholder and the trailer /ID follow the pin; the same document gives the same bytes on every host. The library reads no environment variable — a pipeline exporting SOURCE_DATE_EPOCH applies it in one line of its own. Encrypted output is not reproducible by design. renderToResponse({ etag: true }) is therefore a stable validator only when the document is pinned. Guide: docs/REPRODUCIBLE.md.

Rendering

import {
    renderToBytes,      // (node, options?) => Uint8Array
    renderToBlob,       // (node, options?) => Blob (application/pdf)
    renderToStream,     // (node, options?) => AsyncGenerator<Uint8Array> (constant memory)
    renderToFile,       // (node, path, options?) => Promise<void> (Node only)
    renderToFileStream, // (node, path, options?) => Promise<StreamToFileResult> (Node, constant memory)
    renderToResponse,   // (node, options?) => Promise<Response> (streams; web standard)
    compileDocument,    // (node) => DocumentParams (inspect the model, no render)
    inspectDocument,    // (node, options?) => LayoutInspection (page/block geometry, no render)
    lintDocument,       // (node, options?) => LintReport (accessibility + engine constraints)
} from 'pdfnative-react';

Serving a PDF

// app/invoice/[id]/route.tsx — Next.js App Router
export async function GET() {
    return renderToResponse(<Invoice />, { fileName: 'invoice.pdf' });
}

Streams page by page, so peak memory stays flat and the client receives bytes immediately. buffered: true switches to a single buffer and adds Content-Length. Works unchanged on Node, Edge, Deno, Bun and Cloudflare Workers — see docs/SERVER.md.

options is { layout?: Partial<PdfLayoutOptions>; fontEntries?: FontEntry[]; fonts?: FontsMap } and merges on top of anything set on <Document> — page size, margins, colors, PDF/A mode, encryption, viewer preferences, typography, debug overlay, and non-Latin fonts. renderToFileStream writes page by page with constant memory and preserves document-level features (outline, page labels). The fonts loader map is honored only by the async entry points (renderToFile, renderToFileStream, renderToResponse, usePdf, usePdfStream); for the synchronous entries resolve it first with fontEntries: await resolveFonts({ … }).

Bookmarks, page labels & viewer preferences

<Document
    outline="auto"                                  // or an explicit OutlineItem[] tree
    pageLabels={[{ startPage: 0, style: 'roman' }]} // roman front matter, then decimal
    layout={{ viewerPreferences: { pageMode: 'useOutlines' } }}
>
    …
</Document>

outline builds the reader's bookmark sidebar ('auto' derives it from your headings, or pass a nested OutlineItem[]). layout.viewerPreferences controls how a viewer opens the document. All PDF/A-safe.

Layout debugging

layout.debug overlays margin/content/cell boxes onto the PDF, and inspectDocument(node) returns the same geometry as data (page count, and each block's position/size) without rendering — handy for tests and tooling, and the cheapest way to see where a paragraph split.

Nested lists

<List>
    <Item>Fruits<List><Item>Apple</Item><Item>Pear</Item></List></Item>
    <Item>Vegetables</Item>
</List>

Sub-lists nest as a child <List>, as directly nested <Item> children, or via the items data prop ({ text, items }). Nested lists inherit the parent style.

Hooks & client components

These run in the browser. In a React Server Components app, import them from the pdfnative-react/client subpath, which ships with 'use client' already applied — no wrapper file needed. The root barrel exports them too, for apps without an RSC boundary.

import { usePdf } from 'pdfnative-react/client';

function Preview({ doc }: { doc: React.ReactElement }) {
    const { url, loading } = usePdf(doc);
    return loading ? <p>Rendering…</p> : <iframe title="preview" src={url} />;
}
  • usePdf(element, options?) → { url, blob, bytes, loading, error, update }
  • usePdfStream(element, options?) → { getStream() }
  • PDFViewer — live <iframe> preview.
  • PDFDownloadLink — one-click download (supports a render-prop child).
  • BlobProvider — render-prop access to the raw Blob.

Agent authoring (token-frugal)

pdfnative-react is a library, so the place LLM agents spend tokens is authoring documents. The compact DocSpec expresses the same document as terse, JSON-serializable tuples — and compiles to the exact same PDF as the JSX, because it is built on the very same components.

import { renderSpecToBytes, type DocSpec } from 'pdfnative-react';

const spec: DocSpec = {
    title: 'Invoice #1024',
    footerText: 'Acme Inc',
    creationDate: '2026-01-01T00:00:00Z',
    typography: { unitBinding: true, splitParagraphs: true },
    blocks: [
        ['h1', 'Invoice #1024'],
        ['p', 'Thank you for your business.', { align: 'justify' }],
        ['table', { h: ['Item', 'Total'], r: [['Pro plan', '$49.00']], zebra: true }],
        ['qr', 'https://acme.example/pay/1024', { align: 'right' }],
    ],
};

const bytes = renderSpecToBytes(spec);

The equivalent JSX is several times more tokens for a typical document (the gap widens on larger ones), because every block carries opening/closing tags and prop names. Same bytes out, far fewer tokens in.

  • compileSpec(spec) → DocumentParams · specToElement(spec) → <Document> element
  • renderSpecToBytes / renderSpecToBlob / renderSpecToStream / renderSpecToFile / renderSpecToFileStream / renderSpecToResponse
  • schema(subject?) → a Draft 2020-12 JSON Schema whose $id embeds the package version, so agents can detect contract drift. Subjects: doc-spec, render-options, lint-report, spec-validation, doctor, manifest, list. (docSpecSchema() is retained and returns schema('doc-spec').)

Block tuples: ['h1'|'h2'|'h3', text, opts?] (keepWithNext), ['p', text, opts?] (align incl. 'justify', keepWithNext, splittable, direction), ['ul'|'ol', items, opts?] (items may be { text, items } for nesting), ['table', { h?, r, cellBorders?, cellVAlign?, … }], ['img', { data }] (JPEG, PNG or JPEG 2000), ['link', text, { url }], ['sp', height?], ['br'], ['page', blocks], ['toc', opts?], ['qr'|'code128'|'ean13'|'pdf417'|'datamatrix', data, opts?], ['svg', data, opts?], ['chart', { chartType, series, … }] (a series' label is optional and colors gives one colour per bar), ['field', { fieldType, name, … }]. A spec also accepts the 19 top-level fields of <Document>: title, footerText, metadata, fontEntries, layout, outline, pageLabels, watermark, header, footer, attachments, tagged, print, pdfx, outputIntent, typography, creationDate, direction and blocks. Colour values take the same forms as in JSX, spot inks included ({ spot, tint? }, { inks }), declared under print.spotColours.

Running autonomously

An agent driving this package without a human should work through four cheap checks before spending a render:

import { doctor, capabilityManifest, validateSpec, lintSpec } from 'pdfnative-react';

doctor();                  // will this environment work? never throws
capabilityManifest();      // every component, block, entry point, error code
validateSpec(json);        // is the JSON well-formed? path-anchored findings
lintSpec(spec);            // is it accessible, and legal for the engine?

Every error carries one of 6 stable E_* codes and serializes to { ok: false, error: { code, message } }. Branch on the code, never the message.

Full contract: docs/AGENT_CONTRACT.md. Runnable: samples/agent/agent-loop.ts.

Fonts & environment

Re-exported from the engine: registerFonts, registerFont, loadFontData, downloadBlob (browser), initNodeCompression (Node), setDeflateImpl / setDeflateRawImpl / wrapZlib (inject a compressor elsewhere), setDefaultCreationDate / getDefaultCreationDate (a process-wide pin), setHyphenationProvider / getHyphenationProvider. Pass pre-loaded fonts via the fontEntries render option, or use the resolveFonts convenience:

import { resolveFonts, renderToBytes } from 'pdfnative-react';

const fontEntries = await resolveFonts({
    math: () => import('pdfnative/fonts/noto-sans-math-data.js'),
    lo: () => import('pdfnative/fonts/noto-lao-data.js'),
});
const bytes = renderToBytes(doc, { fontEntries });

The async entry points accept the loader map directly as options.fonts. validateFontData(data) runs an opt-in, read-only structural check on a custom font module ({ valid, errors, warnings }) before you embed it. The engine bundles 32 Unicode scripts as font modules — 1.9.0 added Gujarati (gu), Gurmukhi (pa), Kannada (kn), Malayalam (ml) and Odia (or) on the Indic shaping engine, after 1.8.0's Lao, Tai Tham, New Tai Lue, Tai Le and Cham — see samples/fonts/scripts-32.tsx. Since engine 1.9.0 every embedded font is a lean subset (a page of Noto Sans Kannada weighs tens of KB, not hundreds) whose /BaseFont carries the standard six-letter subset tag (ABCDEF+NotoSans-Regular).

Font weight — check before shipping to a browser

Font modules are embedded in your bundle when you import them, and some are large. Engine 1.6.0 expanded the colour-emoji subset from 221 to 1167 glyphs, which took it from ~0.25 MB to 4.0 MB — worth knowing, since this is the one package in the ecosystem that targets a browser bundle.

Module Size
noto-sans-math-data.js 1.5 MB
noto-sans-data.js 2.8 MB
noto-color-emoji-data.js 4.0 MB
noto-jp-data.js 12.6 MB
noto-sc-data.js 23.4 MB

The loaders passed to resolveFonts are dynamic imports, so a bundler puts each in its own chunk and loads it on demand rather than up front. For a smaller emoji set, generate one covering only the codepoints you use:

npx pdfnative-build-emoji-font --codepoints "1F600,1F44D,2764"

Server-side rendering is unaffected — nothing is bundled there.

Image helpers

fromBase64(base64) and fromUrl(url) produce the Uint8Array that <Image> expects, from a base64/data-URI payload or a fetched URL respectively — a JPEG, a PNG or a JPEG 2000 file (.jp2, or a raw .j2k codestream; see samples/media/image-jpx.tsx).

Beyond authoring: post-processing

pdfnative-react covers document authoring. For byte-level post-processing — merging/splitting, filling and flattening forms, text extraction, decryption, digital signatures, annotations, PDF/X or PDF/UA validation, or in-app font compilation — use the pdfnative engine directly on the bytes this library produces.

docs/RECIPES.md shows each of those, with working code — including the engine 1.9.0 calls this wrapper deliberately does not re-export: a { type: 'link' } markup annotation, an extractText round trip that bounds stream work with onStreamError (PdfStreamLimitError, PDF_STREAM_LIMIT), and composeLtvData for long-term-validation signatures.

Upgrading to 1.4

Everything in 1.4.0 is additive. One install-time floor moved:

npm install pdfnative-react@^1.4.0 pdfnative@^1.9.0 react@^19
  • pdfnative ≥ 1.9 is now required. layout.direction, spot colours, JPEG 2000 pass-through, the PDF/A-2 + PDF/X-4 dual claim and the five new Indic font modules do not exist before 1.9.0, so an older engine would throw mid-render or silently ignore the option. doctor() probes resolveBidiLevels first and tells a 1.8.x engine apart from a missing one (1.8.x — this release needs >= 1.9.0).
  • Rendering behaviour inherited from the engine, with no code change here: every font-embedding document changes bytes — lean, compact font subsets (a page of Noto Sans Kannada weighs tens of KB, not hundreds), one text object per line, /ActualText spans on untagged right-to-left and reordered Indic and South-East Asian runs, the full UAX #9 bidirectional algorithm, deeper table rows for deep descenders, a paginated table of contents, and a PDF/X refusal that names the level. Documents on base-14 fonts alone are byte-identical.
  • Font names carry a subset tag. /BaseFont reads ABCDEF+NotoSans-Regular (bare under PDF/A-1); strip ^[A-Z]{6}\+ when matching font names in post-processing.
  • New diagnostics. TEXT_GLYPH_NOT_COVERED reports a character no registered font covers — it used to render as a box or ? silently; it is a warning on layout.onDiagnostic and a throw under layout.strict. PDFA1_JPX_IMAGE, PDFA_JPX_IMAGE and PDFA_GLYPH_WITHOUT_UNICODE join the channel (13 codes).

No API was removed or narrowed — the api-surface, JSON Schema and manifest superset tests run against the frozen 1.2.0 and 1.3.0 captures, the frozen 1.3.0 samples compile against the 1.4.0 source, and the whole 1.3.0 test suite is replayed against it (npm run compat:previous) on every push. New: the direction document prop and paragraph prop (and DocSpec field and opt), print.spotColours with the { spot, tint? } and { inks } colour forms on every painted colour position, tagged="pdfa2b" | "pdfa2u" beside pdfx="pdfx4", JPEG 2000 in <Image> and watermark.image, chart series with an optional label and per-value colors, four lint rules (41 total), and the TextDirection, PdfSpotColor, PdfInkMix and SpotColourDef types.

Upgrading to 1.3

Everything in 1.3.0 is additive. One install-time floor moved:

# verify-docs:allow engine-version-token
npm install pdfnative-react@^1.3.0 pdfnative@^1.8.0 react@^19
  • pdfnative ≥ 1.8 became required. layout.typography, layout.pdfx, CMYK colour operands, colour bars and setDeflateRawImpl do not exist before 1.8.0, so an older engine would throw mid-render or silently write RGB. doctor() tells a 1.7.x engine apart from a missing one and says exactly what to upgrade.
  • Rendering behaviour inherited from the engine, with no code change here: every embedded TrueType subset changes bytes (hinting tables kept, head.checkSumAdjustment computed); printer's marks stop 0.5 pt short of the trim line; Indic, Khmer, Myanmar, Thai/Lao and Latin-with-marks text takes its designed mark positions; soft hyphens no longer render mid-word. Documents on base-14 fonts that use none of those are byte-identical.
  • Dates are written in UTC (+00'00'): same instant, different offset string; {date} follows a pinned creationDate.
  • setDeflateImpl now rejects a raw-DEFLATE function (pdfnative #78); pass zlib output, or use the new setDeflateRawImpl.

No API was removed or narrowed — tests/api-surface.test.ts, the JSON Schema and manifest superset tests and a compile of the frozen 1.2.0 samples against the 1.3.0 source prove it on every push. New: the typography, pdfx, outputIntent and creationDate document props (and DocSpec fields), align="justify", keepWithNext / splittable, CMYK colours everywhere, print.marks.colourBars, twelve lint rules (37 total), six engine helpers and eleven types re-exported, ParagraphAlign, and a Color type that admits the four-element tuple.

Upgrading to 1.2

Everything in 1.2.0 was additive. One install-time floor moved:

# verify-docs:allow engine-version-token
npm install pdfnative-react@^1.2.0 pdfnative@^1.7.0 react@^19
  • pdfnative ≥ 1.7 became required. The four new chart kinds, layout.print and the diagnostics channel do not exist before 1.7.0, so an older engine would throw mid-render. doctor() tells a 1.6.x engine apart from a missing one and says exactly what to upgrade.
  • Rendering behaviour inherited from the engine, with no code change here: RTL digit order, glyph mirroring and Arabic/Persian letterforms are now UAX #9-conformant (Arabic-script documents render differently — and correctly), form documents gain a complete /ToUnicode map (their bytes change; text becomes searchable), and crowded chart x-labels are strided automatically (labelStride: 1 restores the old behaviour).

No API was removed or changed. New: the Charts v2 props (axis2, xAxis, dataLabels, labelStride, labelRotation, series xValues/yAxis), the print document prop, metadata.trapped, layout.strict/onDiagnostic, seven lint rules (25 at the time), cacheControl/etag on renderToResponse, and ErrorOptions/cause on the error taxonomy.

Upgrading to 1.1

Everything in 1.1.0 was additive. Two install-time floors moved:

# verify-docs:allow engine-version-token
npm install pdfnative-react@^1.1.0 pdfnative@^1.6.0 react@^19
  • pdfnative ≥ 1.6 became required. <Chart> compiles to a block type that does not exist before 1.6.0, so an older engine would silently mis-render it.
  • Node ≥ 22 — inherited, not invented: the 1.6.0 engine requires it, so a compliant install is already there.

No API was removed or changed. New: <Chart>, renderToResponse, lintDocument, the watermark/header/footer/attachments/tagged document props, and the agent surface (doctor, capabilityManifest, validateSpec, schema(subject), ErrorCode). docSpecSchema() still works and delegates to schema('doc-spec').

Migrating from 0.2 to 1.0

1.0 marked the API as stable. The only breaking change was pdfnative becoming a peer dependency, installed alongside the wrapper. Everything else was additive — <Section>, nested lists, outline/pageLabels on <Document>, table cellBorders/cellVAlign, inspectDocument, renderToFileStream, resolveFonts, and fromUrl/fromBase64.

Migrating from @react-pdf/renderer

@react-pdf/renderer pdfnative-react
<Document> / <Page> <Document> / <Page>
<Text> <Text> (alias of <Paragraph>)
<View> + flexbox styles (none — declarative block flow; use blocks + <Spacer>)
StyleSheet per-component props (align, color, fontSize, …)
<PDFViewer> / <PDFDownloadLink> / <BlobProvider> same names, same shape
usePDF() usePdf()

Examples

Runnable, type-checked examples live in samples/: typography, right-to-left text, tables, images (JPEG 2000 included), links, barcodes, SVG, form fields, multi-page structure, custom fonts and 32 scripts, print production, CMYK, spot colours and PDF/X-4, the PDF/A-2 + PDF/X-4 dual claim, reproducible output, layout/PDF-A, the client hooks/components, and the compact agent spec. Every sample is rendered into a byte baseline that CI holds on three operating systems.

Engineering

One quality gate (npm run gate) is the definition of green: type-check of the sources, tests, samples, scripts and the frozen 1.2.0 and 1.3.0 samples; lint; build; the built artefacts probed, bundled for a browser and packed through publint and @arethetypeswrong/cli; 42 samples rendered and held to a byte baseline; coverage; verified documentation; a PDF/A and PDF/X conformance corpus validated in-process and by veraPDF. Zero breaking change is proven, not promised: the api-surface, schema and manifest supersets are checked against the frozen 1.2.0 and 1.3.0 captures, and the 1.3.0 test suite is replayed against the current sources (npm run compat:previous). fast-check property tests cover the untrusted-input surface. CI runs it on Linux (Node 22 and 24), Windows and macOS, with a Node 26 advisory job; seven required checks on three operating systems gate a merge (ci (22), ci (24), os (windows-latest), os (macos-latest), compat-previous, workflow lint, sample-regression), the workflows themselves are linted (zizmor and actionlint, SHA-256-verified), CodeQL scans the actions and the TypeScript, and Dependabot updates wait out a cooldown. Releases go through a guard → build → publish → attest pipeline with blocked egress and the npm client pinned by SHA-512, producing SBOMs and a build-provenance attestation (SLSA Build L2) through npm Trusted Publishing. Details in CONTRIBUTING.md.

The pdfnative ecosystem

Package Use it for
pdfnative The zero-dependency PDF engine — Node, browsers, Workers, Deno, Bun.
pdfnative-react Declarative React/JSX components with live preview (this package).
pdfnative-cli Render, sign, inspect, and verify PDFs from the shell.
pdfnative-mcp Generate PDFs from Claude Desktop, Cursor, Continue, Zed.
zipnative The sibling zero-dependency ZIP engine of the native family.
pkinative The sibling zero-dependency PKI engine of the native family.

The four engines share one design: no runtime dependency, one process, bytes in and bytes out — see the native family guide.

Documentation

Guides

  • Typography — the twelve keys, block-level controls, presets, limits.
  • Print — CMYK, spot colours, colour bars, output intents, PDF/X-4 (alone or beside PDF/A-2) and how to check it.
  • Reproducible output — pinning the creation date, what is covered, how the repository proves it.
  • Charts — the nine chart types, dual axes, log/time scales, accessibility, PDF/A.
  • Server rendering — renderToResponse on Next.js, Remix, Hono, Deno, Bun, Workers and Express.
  • Linting — the 41 lint rules, the diagnostics channel, and how to gate on them.
  • Recipes — merging, form filling, text extraction, decryption, PDF/X validation: calling the engine on the bytes this library produces.
  • Agent contract — driving the package autonomously.

Reference

License

MIT © 2026 Nizoka — Plika

About

Declarative React reconciler for pdfnative. Compile JSX directly to on-device, accessible PDF/A documents. No DOM dependencies, no headless browsers, no SaaS round-trips. Built for Edge and offline-first apps.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Sponsor this project

Used by

Contributors

Languages