Rasterex APINPM Package/docs/getting-started/vue-quick-start

Vue Quick Start

Create a Vue viewer host, open a document, and enable a text annotation with the NPM SDK.

1. Create A Vue Project

Create a TypeScript Vue application.

bash

npm create vite@latest rasterex-vue -- --template vue-ts
cd rasterex-vue

1. Create A Vue Project

Folder Structure

The single-file component owns the viewer lifecycle and host controls.

text

rasterex-vue/
├── src/
│   ├── App.vue     # Creates, subscribes to, and destroys the viewer.
│   └── main.ts     # Mounts the Vue application.
└── package.json    # Declares Vue and @rasterex/viewer.

Folder Structure

2. Install The Viewer

Install the Viewer package. Use a document URL that the Canvas environment can reach.

bash

npm install @rasterex/viewer

2. Install The Viewer

3. Initialize And Open A Document

Create the viewer after the template ref exists. Keep unsubscribe functions and destroy the viewer before Vue removes the component.

vue

<script setup lang="ts">
import { onBeforeUnmount, onMounted, ref } from "vue";
import { createViewer, type RasterexViewer } from "@rasterex/viewer";

const FILE_URL = "https://files.example.com/sample.pdf"; // Replace with a Canvas-reachable document URL.
const hostRef = ref<HTMLElement | null>(null);
const ready = ref(false);
const status = ref("Starting viewer");
let viewer: RasterexViewer | null = null;
let stopOpened: (() => void) | null = null;
let stopFailed: (() => void) | null = null;
let stopCreated: (() => void) | null = null;

onMounted(async () => {
  if (!hostRef.value) return;

  viewer = createViewer({ container: hostRef.value });
  stopOpened = viewer.documents.on("opened", () => {
    ready.value = true;
    status.value = "Document opened";
  });
  stopFailed = viewer.documents.on("failed", (event) => {
    status.value = `Open failed: ${event.error.message}`;
  });
  stopCreated = viewer.annotations.on("created", (event) => {
    status.value = `Created annotation ${event.guid}`;
  });

  try {
    await viewer.mount();
    await viewer.ready();
    status.value = "Opening document";
    await viewer.documents.open({ url: FILE_URL, displayName: "sample.pdf" });
  } catch (error) {
    status.value = error instanceof Error ? error.message : "Viewer failed";
  }
});

onBeforeUnmount(() => {
  stopOpened?.();
  stopFailed?.();
  stopCreated?.();
  viewer?.destroy();
  viewer = null;
});

async function enableTextAnnotation() {
  if (!viewer || !ready.value) return;
  const result = await viewer.tools.set({ action: "TEXT", enabled: true });
  status.value = result.success ? "Text tool active" : (result.error ?? "Text tool failed");
}
</script>

<template>
  <main class="app-shell">
    <p role="status">{{ status }}</p>
    <div ref="hostRef" class="viewer-host" />
    <button type="button" :disabled="!ready" @click="enableTextAnnotation">
      Add text annotation
    </button>
  </main>
</template>

<style>
.viewer-host { height: 640px; width: 100%; } /* A real height is required before mount(). */
</style>

3. Initialize And Open A Document

4. Work With Annotations

The example enables the verified TEXT annotation action after the document has opened. It clears the host tool state when the documented created event arrives.

Creating an annotation is not a persistence confirmation. When the host must save changes, use the result-backed save flow documented in Annotation API and Save annotations.