Installation

Prerequisites

Requirement	Minimum	Notes
Node.js	20.19.0+	Required for development and `@trexolab/verifykit-core` in Node.js
Browser	Chrome 109+, Firefox 115+, Safari 16.4+, Edge 109+	Must support ES2022+, `structuredClone`, WebAssembly
React	19+	Only required for `@trexolab/verifykit-react`

VerifyKit packages are published to an internal npm registry. Before installing, configure npm to resolve @trexolab-scoped packages from the TrexoLab registry. All other packages (React, pdfjs-dist, etc.) continue 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.

bash

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:

bash

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

To verify it was set:

bash

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

Option 3: Inline flag (one-off install)

bash

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

React application

bash

# 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.

Core only (headless / Node.js)

bash

# 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)

bash

# 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

bash

# 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 (v0.3.1+). The WASM binary is base64-embedded directly in the JavaScript bundle. 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',
})

Note: If you are upgrading from a version before 0.3.1, you can remove any WASM-related bundler configuration (vite-plugin-wasm, webpack asyncWebAssembly experiments, etc.).

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.

CDN (recommended)

Use the legacy worker from unpkg:

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

React:

tsx

<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

Copy the worker file to your public directory and reference it with a local path:

bash

cp node_modules/pdfjs-dist/legacy/build/pdf.worker.min.mjs public/

tsx

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

Important: The worker version must match the pdfjs-dist version used by VerifyKit (5.5.207). Using a mismatched version will cause rendering errors.

Vanilla JS via CDN

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

html

<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

typescript

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

Browser (React)

tsx

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:

tsx

<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