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)- Declarative & familiar. 19 components mirror
@react-pdf/rendererergonomics (Document,Page,Text,Image,Link,usePdf,PDFViewer,PDFDownloadLink,BlobProvider). - On-device. A custom React reconciler compiles your tree — synchronously,
with no DOM — to the
pdfnativemodel 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,/DeviceNmixes) 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
creationDateand 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.
renderToResponsereturns a web-standardResponse, 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
DocSpeclets 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 stableE_*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.
lintDocumentreports 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
resolveFontscall, embedded as lean subsets. - Typed, tested, tree-shakeable. Strict TypeScript, dual ESM + CJS with per-condition types, source maps, provenance-signed publishes, 949 tests.
npm install pdfnative-react pdfnative reactRequires React 19, pdfnative ≥ 1.9, and Node.js ≥ 22 (the engine's
own floor since 1.6.0).
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).
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.
<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.
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.
<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.
<Document creationDate={new Date('2026-01-01T00:00:00Z')}> // this document
setDefaultCreationDate(new Date('2026-01-01T00:00:00Z')); // every document in this processEvery 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.
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';// 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({ … }).
<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.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.
<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.
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 rawBlob.
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>elementrenderSpecToBytes/renderSpecToBlob/renderSpecToStream/renderSpecToFile/renderSpecToFileStream/renderSpecToResponseschema(subject?)→ a Draft 2020-12 JSON Schema whose$idembeds 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 returnsschema('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.
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.
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 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.
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).
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.
Everything in 1.4.0 is additive. One install-time floor moved:
npm install pdfnative-react@^1.4.0 pdfnative@^1.9.0 react@^19pdfnative≥ 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()probesresolveBidiLevelsfirst 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,
/ActualTextspans 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.
/BaseFontreadsABCDEF+NotoSans-Regular(bare under PDF/A-1); strip^[A-Z]{6}\+when matching font names in post-processing. - New diagnostics.
TEXT_GLYPH_NOT_COVEREDreports a character no registered font covers — it used to render as a box or?silently; it is a warning onlayout.onDiagnosticand a throw underlayout.strict.PDFA1_JPX_IMAGE,PDFA_JPX_IMAGEandPDFA_GLYPH_WITHOUT_UNICODEjoin 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.
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@^19pdfnative≥ 1.8 became required.layout.typography,layout.pdfx, CMYK colour operands, colour bars andsetDeflateRawImpldo 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.checkSumAdjustmentcomputed); 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 pinnedcreationDate. setDeflateImplnow rejects a raw-DEFLATE function (pdfnative #78); pass zlib output, or use the newsetDeflateRawImpl.
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.
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@^19pdfnative≥ 1.7 became required. The four new chart kinds,layout.printand 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
/ToUnicodemap (their bytes change; text becomes searchable), and crowded chart x-labels are strided automatically (labelStride: 1restores 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.
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@^19pdfnative≥ 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').
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.
@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() |
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.
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.
| 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.
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 —
renderToResponseon 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
- Knowledge Base — architecture, the compile pipeline, the react-reconciler version contract, testing and reproducibility.
- AGENTS.md — guidance for AI agents working in this repo.
- AI Governance — the human-in-the-loop draftsman
contract for AI agents proposing issues/PRs (
npm run verify:issue). - CHANGELOG.md · ROADMAP.md · CONTRIBUTING.md