Installation

Prerequisites

Registry Configuration

VerifyKit packages are published to an internal npm registry. Before installing, configure npm to resolve @trexolab-scoped packages from the TrexoLab registry. Everything else (React, and any other package you depend on) continues to resolve from the default npm registry.

Registry URL: https://verifykit.trexolab.com/api/registry

Option 1: Per-project .npmrc (recommended)

Create a .npmrc file in your project root. This is the recommended approach -- it scopes the registry to @trexolab packages only, and any developer who clones your project will use the correct registry automatically.

echo '@trexolab:registry=https://verifykit.trexolab.com/api/registry' > .npmrc

Or manually create a file called .npmrc in your project root with this single line:

@trexolab:registry=https://verifykit.trexolab.com/api/registry

Option 2: Global npm configuration

This configures the registry globally for your user account:

npm config set @trexolab:registry https://verifykit.trexolab.com/api/registry

To verify it was set:

npm config get @trexolab:registry
# Should print: https://verifykit.trexolab.com/api/registry

Option 3: Inline flag (one-off install)

npm install @trexolab/verifykit-react --registry=https://verifykit.trexolab.com/api/registry

This works for a quick test but is not recommended for projects -- every npm install must include the flag.

Installing Packages

Pinning a version works. The registry keeps every published release, so npm install @trexolab/verifykit-react@0.6.0 resolves as expected; a plain install without a version gives you the latest. Each version advertises the dependencies it actually shipped with — pdfjs-dist is a dependency of releases before 0.6.0 and bundled from 0.6.0 onward.

React application

# npm
npm install @trexolab/verifykit-react
 
# yarn
yarn add @trexolab/verifykit-react
 
# pnpm
pnpm add @trexolab/verifykit-react
 
# bun
bun add @trexolab/verifykit-react

@trexolab/verifykit-core is installed automatically as a dependency.

pdf.js is not something you install. Since v0.6.0 it is bundled inside @trexolab/verifykit-react (in a lazily-loaded chunk, so it is not in your initial bundle). You do not add pdfjs-dist to your package.json, and npm ls pdfjs-dist will not list it. The one piece you still supply is the worker URL — see PDF.js Worker Setup.

Peer dependencies: react and react-dom 19+.

Core only (headless / Node.js)

# npm
npm install @trexolab/verifykit-core
 
# yarn
yarn add @trexolab/verifykit-core
 
# pnpm
pnpm add @trexolab/verifykit-core
 
# bun
bun add @trexolab/verifykit-core

Vanilla JS (npm)

# npm
npm install @trexolab/verifykit-vanilla
 
# yarn
yarn add @trexolab/verifykit-vanilla
 
# pnpm
pnpm add @trexolab/verifykit-vanilla
 
# bun
bun add @trexolab/verifykit-vanilla

Or skip npm entirely and use the CDN -- see Vanilla JS via CDN below.

Revocation plugin

# npm
npm install @trexolab/verifykit-plugin-revocation
 
# yarn
yarn add @trexolab/verifykit-plugin-revocation
 
# pnpm
pnpm add @trexolab/verifykit-plugin-revocation
 
# bun
bun add @trexolab/verifykit-plugin-revocation

Bundler Configuration

No bundler configuration is needed. The engine ships as a .wasm file and every bundler below resolves it from the reference the package makes, emitting it as a hashed asset beside your JavaScript — which is also what lets the browser compile it while it downloads. This means:

• Vite -- works out of the box. No vite-plugin-wasm needed.
• webpack 5 -- works out of the box. No asyncWebAssembly experiment needed.
• Next.js -- works out of the box. No webpack.experiments configuration needed.
• Turbopack -- works out of the box.
• Node.js / Deno / Bun -- works out of the box.

If you need to load the WASM binary from a custom URL (e.g., for CSP compliance or to reduce initial bundle parse time), use setWasmUrl() before any verification call:

import { setWasmUrl } from '@trexolab/verifykit-core'
 
setWasmUrl('/custom/path/verifykit_core_wasm_bg.wasm')

Or pass wasmUrl in the config:

const verifier = await createVerifier({
  wasmUrl: '/custom/path/verifykit_core_wasm_bg.wasm',
})

PDF.js Worker Setup

The workerUrl option is required for both the React and Vanilla JS packages. It specifies the URL to the PDF.js worker script that handles PDF rendering in a background thread.

Which file, and which version

pdf.worker.min.mjs from pdfjs-dist@5.5.207, the legacy/build/ copy.

The version is not a preference. The pdf.js library is bundled inside @trexolab/verifykit-react; the worker is not, and pdf.js refuses to run a library and a worker whose versions differ. 5.5.207 is what this release of VerifyKit bundles, so 5.5.207 is what the worker has to be.

Two things follow from the library being bundled:

• npm ls pdfjs-dist tells you nothing. pdf.js is not a dependency of your project — nothing appears there unless something else in your tree pulls it in, and what appears is not the copy VerifyKit uses.
• There is no node_modules/pdfjs-dist to copy the worker out of. It has to be fetched, by URL at runtime or by download at build time; both are below.

If the pair ever does not match, the console names both versions — The API version "5.5.207" does not match the Worker version "…". That message is the authoritative check; trust it over this page if you have upgraded VerifyKit since it was written.

Use the legacy build. It transpiles newer JavaScript syntax for older engines — see Browser Support for what that buys you.

CDN (recommended)

Use the legacy worker from unpkg:

https://unpkg.com/pdfjs-dist@5.5.207/legacy/build/pdf.worker.min.mjs

React:

<VerifyKitProvider config={{
  workerUrl: 'https://unpkg.com/pdfjs-dist@5.5.207/legacy/build/pdf.worker.min.mjs',
}}>

Vanilla JS:

const viewer = VerifyKit.create(el, {
  workerUrl: 'https://unpkg.com/pdfjs-dist@5.5.207/legacy/build/pdf.worker.min.mjs',
})

Self-Hosted

Since v0.6.0 pdfjs-dist is bundled into the SDK rather than installed into your project, so there is no node_modules/pdfjs-dist to copy from. Fetch the matching worker directly instead — either way, once the file is in public/ the viewer never reaches outside your origin for it:

# from a CDN
curl -o public/pdf.worker.min.mjs \
  https://unpkg.com/pdfjs-dist@5.5.207/legacy/build/pdf.worker.min.mjs

# or from the npm registry, if your network allows one and not the other
npm pack pdfjs-dist@5.5.207 --pack-destination /tmp \
  && tar -xzOf /tmp/pdfjs-dist-5.5.207.tgz package/legacy/build/pdf.worker.min.mjs \
     > public/pdf.worker.min.mjs

<VerifyKitProvider config={{ workerUrl: '/pdf.worker.min.mjs' }}>

Vanilla JS via CDN

No npm install required. Add two tags to your HTML <head>:

<link rel="stylesheet" href="https://verifykit.trexolab.com/cdn/verifykit.css">
<script src="https://verifykit.trexolab.com/cdn/verifykit.umd.js"></script>

This exposes a global VerifyKit object with a create() method. See the Quick Start for a complete example.

Verifying Installation

After installing, run a quick test to confirm the WASM engine loads correctly.

Node.js

import { createVerifier } from '@trexolab/verifykit-core'
 
const verifier = await createVerifier()
console.log('VerifyKit core initialized successfully')
verifier.dispose()

Browser (React)

import { VerifyKitProvider } from '@trexolab/verifykit-react'
import '@trexolab/verifykit-react/styles.css'
 
// If this renders without errors, the WASM engine loaded successfully
function App() {
  return (
    <VerifyKitProvider config={{
      workerUrl: 'https://unpkg.com/pdfjs-dist@5.5.207/legacy/build/pdf.worker.min.mjs',
      theme: { mode: 'system' },
    }}>
      <p>VerifyKit is ready.</p>
    </VerifyKitProvider>
  )
}

AIA Certificate Chain Resolution

By default, the core engine resolves missing intermediate certificates via AIA (Authority Information Access) URLs. This requires network access. To disable it:

const verifier = await createVerifier({ enableAIA: false })

Or in the React provider:

<VerifyKitProvider config={{ enableAIA: false, workerUrl: '...' }}>

Next Steps

• Quick Start -- working examples for React, Node.js, and Vanilla JS
• Examples -- practical, copy-paste-ready code examples
• API Reference -- complete type and function reference