@stsdti/esign-vue3-webcomponents

Vue 3 components for integrating with the eSign cloud signing service. Supports both Vue 3 (ESM) and framework-free usage as a native custom element.

Requirements

• Node 20+
• Vue 3.5+ (ESM usage only)
• Modern browser with Custom Elements v1, Shadow DOM v1, and WebAssembly support (Chrome 67+, Firefox 63+, Safari 15.4+)

Installation

npm install @stsdti/esign-vue3-webcomponents

Vue 3 usage

EsignCloudDocument

Drop-in button component that handles the full cloud signing workflow: certificate selection, OAuth2 authorization, optional visible signature placement, and document signing.

<template>
  <EsignCloudDocument
    esign-api-host="https://your-esign-api-host"
    bearer-token="your-jwt-token"
    :to-sign-document-callback="fetchDocument"
    @signatureCancel="onCancel"
    @signatureDone="onDone"
  />
</template>

<script setup>
import { EsignCloudDocument } from '@stsdti/esign-vue3-webcomponents'

async function fetchDocument() {
  const res = await fetch('/api/document')
  return await res.text() // base64-encoded PDF
}

function onCancel() {
  console.log('Signing cancelled')
}

function onDone(signedDocument) {
  console.log('Signed PDF (base64):', signedDocument)
}
</script>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | esignApiHost | String | '' | eSign API service base URL | | bearerToken | String | '' | JWT bearer token from your identity provider | | toSignDocument | String | '' | Base64-encoded PDF to sign (static) | | toSignDocumentCallback | Function | — | Async function returning the base64 PDF (preferred over toSignDocument for lazy loading) | | wasmUrl | String | https://cdn.jsdelivr.net/npm/@embedpdf/[email protected]/dist/pdfium.wasm | URL to the pdfium WASM binary used for PDF rendering | | align | String | 'left' | Dropdown menu alignment: 'left' or 'right' | | disabled | Boolean | false | Disables the signing button |

Events

| Event | Payload | Description | |-------|---------|-------------| | signatureCancel | — | User dismissed or cancelled the signing dialog | | signatureDone | String (base64) | Signed PDF document |

Signing flow

1. User clicks the sign button → the dialog opens and credentials are retrieved from the eSign API
2. If not yet authorized, an OAuth2 tab opens and the component polls until authorization completes
3. User selects a certificate (or the default is used automatically)
4. For visible signatures: user positions the signature box on the PDF preview
5. The document is signed server-side and signatureDone is emitted with the result

Custom element (framework-free)

The package ships a self-contained IIFE bundle that registers <esign-cloud-document> as a native HTML custom element. No Vue, no build step on the consumer side — just a <script> tag.

Build

npm run build:ce

Output: dist/esign-webcomponents.js

Usage

<script src="esign-webcomponents.js"></script>

<esign-cloud-document
  esign-api-host="https://your-esign-api-host"
  bearer-token="your-jwt-token"
  wasm-url="https://cdn.jsdelivr.net/npm/@embedpdf/[email protected]/dist/pdfium.wasm"
></esign-cloud-document>

<script>
  const el = document.querySelector('esign-cloud-document')

  // Provide the PDF lazily via callback (preferred)
  el.toSignDocumentCallback = async () => {
    const res = await fetch('/api/document')
    return await res.text() // base64 string
  }

  el.addEventListener('signatureDone', (e) => {
    const signedPdfBase64 = e.detail[0]
    console.log('Signed PDF length:', signedPdfBase64.length)
  })

  el.addEventListener('signatureCancel', () => {
    console.log('Signing cancelled')
  })
</script>

Note: signatureDone carries its payload at e.detail[0]. Vue custom element events wrap emit arguments in an array.

Attributes

All props map to kebab-case HTML attributes:

| Attribute | Description | |-----------|-------------| | esign-api-host | eSign API service base URL | | bearer-token | JWT bearer token | | to-sign-document | Base64-encoded PDF (static) | | wasm-url | URL to the pdfium WASM binary | | align | Dropdown alignment: left or right | | disabled | Disables the signing button |

toSignDocumentCallback must be set as a JavaScript property — it cannot be passed as an HTML attribute.

Important: The custom element bundle must be served over HTTP(S). file:// URLs will block WASM loading and Web Worker creation.

Playground

The playground/ folder contains a standalone HTML page for testing the custom element build without a framework.

One-time setup

# Build the bundle
npm run build:ce

# Symlink dist/ into playground/ so the page can load the file when served
ln -s ../dist playground/dist

Run

npx serve playground

Open http://localhost:3000 in your browser.

Development

# Install dependencies
npm install

# Start dev server (Vue app)
npm run dev

# Build library — ESM package (Vue 3)
npm run build

# Build custom element bundle — IIFE (framework-free)
npm run build:ce