@dvina/artifact-renderer

@dvina/artifact-renderer is an iframe-first SDK for embedding the Dvina Artifact Renderer inside your application.

It is designed for products that need to preview user uploads, generated artifacts, and private documents without rendering untrusted content directly inside the host app DOM.

Install

npm install @dvina/artifact-renderer

Important

This package is the host-side SDK. You also need to deploy the self-hosted viewer image to a dedicated origin such as https://viewer.example.com/.

docker run --pull always -p 8080:8080 kantist/artifact-renderer-viewer:latest

Quick Start

import { createViewer, type ViewerDocument } from "@dvina/artifact-renderer";

const container = document.querySelector("#viewer-slot");

if (!(container instanceof HTMLElement)) {
  throw new Error("Viewer container not found.");
}

const documentToPreview: ViewerDocument = {
  id: "artifact-123",
  name: "analysis.pdf",
  format: "pdf",
  source: {
    kind: "url",
    url: "https://cdn.example.com/previews/analysis.pdf",
  },
};

createViewer({
  container,
  viewerUrl: "https://viewer.example.com/",
  allowedOrigin: "https://viewer.example.com",
  document: documentToPreview,
});

Private Files

For private files, use a session-backed document and provide getSession().

createViewer({
  container,
  viewerUrl: "https://viewer.example.com/",
  allowedOrigin: "https://viewer.example.com",
  document: {
    id: "private-doc-7",
    name: "board-packet.docx",
    format: "docx",
    source: {
      kind: "session",
      sessionId: "board-packet-session",
      url: "https://api.example.com/viewer/files/private-doc-7/preview",
    },
  },
  getSession: async () => {
    const response = await fetch("https://api.example.com/viewer/sessions", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        documentId: "private-doc-7",
        scope: "artifacts:read",
      }),
      credentials: "include",
    });

    if (!response.ok) {
      throw new Error("Failed to create viewer session.");
    }

    return response.json();
  },
});

Main API

• createViewer(options)
• controller.loadDocument(document, options?)
• controller.setTheme(theme)
• controller.goToPage(page)
• controller.sendArtifactData(data, options?)
• controller.destroy()
• controller.getDiagnostics()

Theme Updates

Pass theme to createViewer(...) for the initial render, then call setTheme(...) when your app theme changes.

const controller = createViewer({
  container,
  viewerUrl: "https://viewer.example.com/",
  allowedOrigin: "https://viewer.example.com",
  document: documentToPreview,
  theme: { mode: "light" },
});

controller.setTheme({
  mode: "dark",
  tokens: {
    surface: "#0f1115",
    text: "#f3f5f8",
  },
});

setTheme(...) updates the viewer appearance without reloading the current document.

Runtime Notes

• browser-only package
• exact allowedOrigin is required
• private files should use short-lived bearer-token sessions

Related Packages

• @dvina/artifact-renderer-core
• @dvina/artifact-renderer-protocol

Documentation

See the repository documentation for:

• React integration
• Angular 20+ integration
• NestJS backend integration
• viewer deployment
• release checklist