Document Verification Module for Nuxt

A reusable Nuxt 3 module for document verification.
Add a simple <DocumentVerification /> component and endpoint configuration to verify and preview documents.

Highlights

• Plug-and-play verification page backed by the useDocumentVerification composable
• Configurable document fields with optional resolver functions for derived values
• Automatic routing support: watches the URL and re-verifies on change
• Built‑in loading and error handling states
• Document image support and smart status fallback when only a boolean validity flag is available
• Centralised styling with CSS custom properties, including a default dark theme

Installation

1. Copy the document-verification package into your Nuxt workspace (or install it through your preferred package manager if published).
2. Enable the module in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: [
    // ...other modules
    '~/packages/document-verification/nuxt',
  ],

  documentVerification: {
    logo: '/art/documents-logo.svg',
    verificationEndpoint: '/api/documents',
    documentIdParam: 'document_id',
    backLink: '/',
    backLinkText: 'Back to dashboard',
    showBackLink: true,
    buttonColor: '#4f46e5',
    buttonHoverColor: '#4338ca',
    showDocument: true,
    displayField: 'displayUrl',
    displayTitle: 'Uploaded Document',
    displayType: 'image',
    showDocumentTitle: true,
    idField: 'id',
    issuedToField: 'recipientName',
    titleField: 'documentTitle',
    issueDateField: 'issuedOn',
    validityField: 'isValid',
    statusResolver: (payload) => payload.statusText,
    messages: {
      description: 'Enter the document ID to verify authenticity.',
      requiredIdError: 'Document ID is required',
      verificationFailedError: 'We could not verify that document',
      generalError: 'Something unexpected happened. Try again shortly.',
    },
    fields: [
      { label: 'Document ID:', key: 'id', type: 'id' },
      { label: 'Issued To:', key: 'issuedTo', type: 'text' },
      { label: 'Programme:', key: 'title', type: 'text' },
      { label: 'Issue Date:', key: 'issueDate', type: 'date' },
      {
        label: 'Status:',
        key: 'status',
        type: 'status',
        resolver: (raw, normalised) =>
          (raw.statusText ?? normalised.isValid) ? 'Valid' : 'Invalid',
      },
    ],
  },
})

The configuration object is optional—omit or override keys to fall back to the bundled defaults.

Usage

The module globally registers the DocumentVerification component. Drop it into any page:

<template>
  <DocumentVerification />
</template>

All verification requests read the document identifier from the current route query string. By default the ID comes from the ?document_id= parameter; override documentIdParam to match your API naming.

Verification Endpoint

Expose an endpoint that accepts the configured identifier and returns the document payload. A minimal JSON response looks like:

{
  "id": "DOC-123456",
  "issuedTo": "Ayo Bello",
  "title": "Data Analytics Credential",
  "issueDate": "2024-05-12",
  "status": "Valid",
  "isValid": true,
  "displayUrl": "https://cdn.example.com/documents/DOC-123456.png",
  "displayType": "image"
}

By default the module requests /api/documents?document_id=DOC-123456. Override documentIdParam when your API expects a different query key.

All response fields are treated as strings except the validity flag. If a status string is missing the module falls back to isValid and surfaces Valid / Invalid automatically.

Configuration Reference

Key	Description	Default
logo	Logo URL displayed at the top of the page	/logo.png
verificationEndpoint	API endpoint that validates a document	required
backLink / backLinkText	Destination + label for the back button	'/' / 'Back to Home'
showBackLink	Toggle visibility of the back button	true
buttonColor / buttonHoverColor	Primary button colours	#4f46e5 / #4338ca
fields	Array describing the detail rows (label, key, type, optional resolver)	Built-in defaults
showDocument	Toggle document image section (hides it entirely when false)	true
displayField	Field containing the primary document asset (image/PDF)	'displayUrl'
displayTitle	Heading shown above the preview when visible	'Document Preview'
displayType	Explicitly mark the asset as 'image' or 'pdf'; falls back to URL sniffing when unset	undefined
showDocumentTitle	Controls whether the image heading renders	true
idField, issuedToField, titleField, issueDateField, statusField, validityField	Maps raw payload keys to the normalised document fields	sensible defaults
statusResolver, validityResolver	Functions that derive status text / validity boolean from the raw payload	undefined
documentIdParam	Name of the ID parameter used in the query string	'document_id'
messages	Override copy for the UI (see below)	bundled strings

Messages

Provide the messages object to tailor UI copy:

messages: {
  description: 'Verify the document below.',
  requiredIdError: 'Please supply a document ID',
  verificationFailedError: 'Verification failed',
  generalError: 'Something went wrong',
  missingConfigError: 'Document verification is not configured.'
}

Field Definitions

Each field in fields accepts:

Property	Purpose
label	Text shown in the UI (: is optional)
key	Normalised document property to read from
type	One of id, text, status, date, image, or pdf
resolver	(raw, normalised) => unknown function that supplies a value when the raw payload uses a different shape

Only fields that resolve to a non-empty value are rendered. type: 'status' also exposes field.isValid so you can style badges appropriately.

When showDocument is false, the asset block is skipped altogether even if the API responds with a URL. Use showDocumentTitle to hide the heading while keeping the preview itself, or override displayTitle to customise the heading copy. Set displayType to 'image' or 'pdf' when you know the asset format; otherwise the component falls back to inferring it from the URL (still supporting PDF detection). The displayField can point to an image or a PDF; PDFs render inside the viewer with a fallback link.

Turn off the footer back button entirely by setting showBackLink: false.

documentVerification: {
  // ...
  displayField: 'assets.preview.url',
  displayTitle: 'Supporting Evidence',
  displayType: 'pdf'
}

Styling & Theming

All component styles live in packages/document-verification/src/runtime/assets/documentVerification.css. The sheet defines a set of CSS variables prefixed with --dv- plus a dark-mode override block. Override them from your host application to match your brand:

/* app.vue, main.css, etc. */
:root {
  --dv-primary-color: #1e40af;
  --dv-primary-hover: #1d4ed8;
  --dv-link-color: #0f172a;
  --dv-border-radius: 12px;
}

[data-theme='dark'] {
  --dv-card-bg: #010409;
  --dv-surface-color: #111827;
  --dv-border-color: #1f2937;
  --dv-button-text: #f8fafc;
}

Set data-theme="dark" on any ancestor of the verification component to automatically swap to the dark palette:

<template>
  <section data-theme="dark">
    <DocumentVerification />
  </section>
</template>

Because every component imports the shared stylesheet, overrides apply whether you render the bundled page or re-use individual building blocks.

Composable

Import useDocumentVerification() when you want to extend or completely redesign the UI. It exposes:

const {
  documentId,
  isLoading,
  error,
  document,
  fields,
  verifyDocument,
  clearError,
  setDocumentId,
  config,
} = useDocumentVerification()

The composable mirrors the logic used by the default page—form submission, error handling, field normalisation, and status fallbacks—so you can build bespoke layouts without re-implementing verification logic.

Playground

Run the playground inside packages/document-verification/playground to experiment with configuration, custom CSS, or dark mode. The example page ships with a theme toggle that flips the data-theme attribute to demonstrate the built-in palette changes.

Testing

Vitest unit tests cover the composable and utility helpers. Run them from the package root:

npm run test

Happy verifying!