Quick setup

The five-minute path: license → install → render. For everything else (env vars, conversion service, secure mode, AI providers, custom themes, plugins), see Advanced setup.

1. Get a license

The license token is a string of the form trupdf.<payload>.<sig>. The SDK validates the signature, binds the feature gate, and refuses to construct premium engines without the corresponding entitlement.

2. Configure the registry

TruPDF packages are published to GitHub Packages. Add a .npmrc at the root of your app:

@trupdf:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep the PAT out of source control. In CI, read it from a secret and write .npmrc at build time.

3. Install

pnpm add @trupdf/viewer react react-dom

The @trupdf/viewer package bundles every public surface — viewer engine, annotations, forms, redaction, signing, conversion client, OCR, compare, content edit, AI, licensing. All runtime dependencies install transitively — nothing else to configure.

Yarn / npm: substitute yarn add or npm install. pnpm is the repo's own package manager; either works for consumers.

4. Render in React

import { useEffect, useState } from 'react';
import { DocViewer, LicenseManager } from '@trupdf/viewer';
 
const LICENSE_TOKEN = process.env.NEXT_PUBLIC_TRUPDF_LICENSE!;
 
export function App() {
  const [license, setLicense] = useState<LicenseManager | null>(null);
 
  useEffect(() => {
    const m = new LicenseManager();
    void m.init(LICENSE_TOKEN).then(() => setLicense(m));
    return () => {
      m.destroy();
    };
  }, []);
 
  if (!license) return <div>Loading viewer…</div>;
  return <DocViewer source="/files/sample.pdf" licenseManager={license} />;
}

That's it. The viewer auto-wires every downstream surface:

• Trial tier — watermark on every page render, burned into every save/export, hard-cliff overlay on expiry.
• Pro / enterprise — premium engines (redaction, signing, conversion, compare, collab, OCR) construct on demand; no watermark, no overlay.

5. Render without React

The viewer chrome is React internally, but hosts don't have to be. The Vue, Angular, and Svelte wrapper packages — @trupdf/vue, @trupdf/angular, @trupdf/svelte — each expose framework-idiomatic components / directives plus a mountTruPDF(host, options) helper that renders the viewer into any DOM element:

import { LicenseManager } from '@trupdf/viewer';
import { mountTruPDF } from '@trupdf/vue'; // or /angular, /svelte
 
const license = new LicenseManager();
await license.init(licenseToken);
 
const handle = mountTruPDF(document.querySelector('#viewer')!, {
  source: '/files/sample.pdf',
  licenseManager: license,
});
 
// Later:
handle.update({ source: '/files/other.pdf', licenseManager: license });
handle.unmount();

options accepts every DocViewer prop plus an optional className.

6. Drive the viewer programmatically

TruPDFSDK is the typed, framework-agnostic control surface — navigation, zoom, annotations, forms, plugins, and a fully typed event bus. Attach it to the running engine via the engineRef prop:

import { DocViewer, TruPDFSDK } from '@trupdf/viewer';
 
const sdk = new TruPDFSDK();
 
<DocViewer
  source="/files/sample.pdf"
  licenseManager={license}
  engineRef={(engine) => {
    if (engine) void sdk.attach(engine);
    else sdk.detach();
  }}
/>;
 
sdk.events.on('document.loaded', ({ numPages }) => {
  console.info(`loaded ${numPages} pages`);
});
sdk.goToPage(3);
sdk.setScale(1.5);

attach() / detach() are lifecycle-safe — call them from any mount/unmount hook.

7. Load existing annotations (XFDF)

import { AnnotationManager, deserializeXFDF } from '@trupdf/viewer';
 
const manager = new AnnotationManager({ defaultAuthor: 'Reviewer' });
for (const r of deserializeXFDF(xfdfText)) manager.ingest(r);
 
<DocViewer
  source="…"
  licenseManager={license}
  annotationManager={manager}
/>

Saved annotations round-trip through XFDF and AcroForm — same wire formats Acrobat reads / writes — so existing documents work unchanged.

8. Save changes

import { SaveEngine, serializeXFDF } from '@trupdf/viewer';
 
const save = new SaveEngine(engine); // engine from `engineRef`
const bytes = await save.saveAll(); // native annots + XFDF inside the PDF
const xfdf = serializeXFDF(engine.getAnnotationManager().list()); // detached XFDF (for REST APIs)

Where next

• Advanced setup — env vars, conversion service, secure mode, AI provider config.
• Features → Viewer — every viewer prop and what it does.
• Customization → Theming — match your brand.
• Licensing — tier matrix, feature gates, trial limits, renewals.