Getting Started

This guide covers installing dependencies, running the dev server, building for production, and embedding the WebViewer into your own page.

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm
• A ComPDFKit license key (contact ComPDF for an evaluation license)

Installation

git clone <repository-url>
cd compdfkit-web-sdk
pnpm install

The workspace contains two packages:

Package	Path	Description
@compdfkit/core	packages/core	Closed-source PDF engine; builds into packages/webview/lib/.
@compdfkit/webview	packages/webview	Open-source Vue 3 UI layer (the focus of this documentation).

Development

# Dev server on http://localhost:3032 (proxies the core build)
pnpm dev

# Dev with core watch mode (rebuilds the engine on core changes)
pnpm dev:core

The dev server runs at http://localhost:3032. In standalone mode (running the webview app directly, not embedded), loadConfig applies development defaults including a license and renderLayerPermission: true.

Production builds

pnpm build          # Build the webview only (Vite → packages/webview/dist/)
pnpm build:core     # Build the core engine (Rollup → packages/webview/lib/)
pnpm build:webviewer # Build webviewer.js (the iframe embed entry)
pnpm build:release  # Full release: core → webviewer → webview → release/

See Deployment for the full release layout.

Tests & lint

# Unit tests (webview only, Vitest + happy-dom)
pnpm --filter @compdfkit/webview test:unit

# Lint (webview only)
pnpm --filter @compdfkit/webview lint

There is no monorepo-wide test runner. The core package has no test infrastructure beyond individual .test.js files run manually.

Embedding the WebViewer

The integrator-facing entry is webviewer.js (packages/core/webviewer.js), bundled into packages/webview/lib/webviewer.js (ES) and webviewer.global.js (UMD, global name ComPDFKitViewer).

As an ES module

import ComPDFKitViewer from '@compdfkit/core/webviewer';

ComPDFKitViewer.init(
  {
    path: '/lib',                              // where the webviewer/ folder is served
    pdfUrl: '/files/sample.pdf',               // initial document
    license: 'YOUR_LICENSE_KEY',
    theme: 'light',                            // 'light' | 'dark'
    showToolbarControl: true,
  },
  document.getElementById('viewer')            // host element
).then(instance => {
  const { UI, Core, docViewer } = instance;
  // Ready to use — see the guides.
});

Via a <script> tag (UMD)

<div id="viewer"></div>
<script src="/lib/webviewer.global.js"></script>
<script>
  ComPDFKitViewer.init({ path: '/lib', pdfUrl: '/files/sample.pdf' }, document.getElementById('viewer'))
    .then(instance => { /* instance.UI, instance.Core */ });
</script>

How embedding works

1. ComPDFKitViewer.init(options, element) creates an <iframe> pointing at webviewer/index.html?version=...#d=<initialDoc>&docId=<docId>, optionally appending &css=, &header=, &theme= hash params.
2. Inside the iframe, the Vite-built webview app boots: main.js → Suspenser.vue → App/index.vue.
3. App/index.vue awaits i18next, then performs a config handshake with the parent (loadConfig): the iframe posts requestConfig, the parent replies with the integrator's options (and optional config script URL).
4. The core ComPDFKitViewer is constructed from the bundled lib/webview.min.js and registered as instance 1.
5. window.instance = { docViewer, Core, UI } is defined inside the iframe.
6. The iframe posts viewerLoaded to the parent; webviewer.js captures iframe.contentWindow.instance and resolves its init promise with it.

Options reference

Option	Purpose
path	Base URL where the webviewer/ folder is served (trailing / is added).
pdfUrl	Initial document URL.
config	URL of an optional integrator config script, loaded inside the iframe.
css	URL of a custom stylesheet injected into the iframe.
showToolbarControl	boolean → toggles the toolbar via the &header= hash param.
theme	'dark' / 'light'.
backgroundColor	Sets the iframe background color.
assetPath	Sets the iframe data-assetpath (URI-encoded).
license	License key forwarded to the engine.
Feature flags	isAnnotationPopup, renderLayerPermission, webviewerServer, autoJumpNextSign, disableDigitalSignature, disableElectronicSignature, enableReply, enableDefaultFont, webFontURL, isRenderAnnotations.

The instance object

After initialization, instance exposes three surfaces:

instance.UI      // UI-layer APIs (setLanguage, setTheme, disableElements, setHeaderItems, …)
instance.Core    // Engine APIs forwarded through the core bridge
instance.docViewer // The underlying ComPDFKitViewer document viewer (instance 1)

instance.UI is the public surface documented across these guides. Head to the UI Customization overview or the API reference to continue.

Next steps

• Architecture — understand the three-layer design.
• UI Customization — start customizing the interface.
• Header & Toolbar — modify the toolbar.