vue-spur-monocle

Note: This is not an official package. For the official Monocle documentation, please visit: https://docs.spur.us/monocle

A Vue 3 integration for the Monocle SDK (spur-monocle-manager), enabling dynamic script loading and easy interaction with the Monocle API.

Features

• Automatic injection and management of the Monocle script
• Server-Side Rendering (SSR) support (no-op on server)
• Unified API for both Composition API and Options API
• Custom events: assessment, error, load

Table of Contents

• Installation
• Requirements
• Usage
  • 1. Options API
  • 2. Composition API
• API Reference
  • MonoclePlugin(opts: MonocleOptions): Plugin
  • useMonocle()
• Server-Side Rendering (SSR)
• Tests & CI
• Contributing
• License

Installation

npm install vue-spur-monocle
# or
yarn add vue-spur-monocle

Requirements

• Vue 3
• Node.js >= 22

Usage

1. Options API

In your main entry file (e.g., main.ts):

import { createApp } from 'vue'
import MonoclePlugin from 'vue-spur-monocle'
import App from './App.vue'

const app = createApp(App)

app.use(MonoclePlugin, {
  token: process.env.VUE_APP_MONOCLE_TOKEN!
})

app.mount('#app')

Inside your components:

<template>
  <button @click="loadAssessment">Load Assessment</button>
</template>

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  methods: {
    async loadAssessment() {
      try {
        await this.$monocle.init()
        const data = await this.$monocle.getAssessment()
        console.log('Assessment data:', data)
      } catch (error) {
        console.error('Monocle error:', error)
      }
    }
  }
})
</script>

2. Composition API

In your main entry file:

import { createApp } from 'vue'
import MonoclePlugin from 'vue-spur-monocle'
import App from './App.vue'

const app = createApp(App)
app.use(MonoclePlugin, {
  token: import.meta.env.VITE_MONOCLE_TOKEN!
})
app.mount('#app')

In a <script setup> component:

<template>
  <button @click="fetchAssessment">Fetch Assessment</button>
</template>

<script lang="ts" setup>
import { onMounted } from 'vue'
import { useMonocle } from 'vue-spur-monocle'

const { init, getAssessment, on, off } = useMonocle()

onMounted(async () => {
  await init()
})

function fetchAssessment() {
  getAssessment()
    .then(data => console.log('Assessment data:', data))
    .catch(err => console.error('Error:', err))
}

// Example event subscription
on('assessment', payload => console.log('Success event:', payload))
// To remove an event listener
off('assessment', /* yourHandler */)
</script>

API Reference

MonoclePlugin(opts: MonocleOptions): Plugin

Install the plugin and injects the Monocle instance:

• opts.token: string — Your Monocle API token.
• opts.initTimeout: number — Timeout for the script to load (default: 5000 ms).
• opts.debug: boolean — Enable debug mode (default: false).
• Adds $monocle to app.config.globalProperties (Options API).
• Provides the instance under MonocleKey (Composition API).

useMonocle()

Returns an object with methods to interact with Monocle:

• init(): Promise<void> — Load/inject the Monocle script.
• getAssessment(): Promise<string> — Refresh and retrieve the Monocle data assessment.
• on(event: MonocleEvents, handler: (detail: any) => void): void — Listen to events.
• off(event: MonocleEvents, handler: (detail: any) => void): void — Remove an event listener.

Types exported:

• MonocleEvents — 'assessment' | 'error' | 'load'
• MonocleOptions — { token: string }
• MonocleKey — Injection key symbol (for advanced usage)

Server-Side Rendering (SSR)

This plugin detects SSR and performs no operations on the server. Both init() and getAssessment() will throw an error if called on the server. The Monocle script should be only loaded on the client side.

Tests & CI

• Unit tests & coverage via Vitest
• Linting & type-checking using ESLint + TypeScript
• Automated releases via GitHub Actions + Semantic Release

Contributing

Please see CONTRIBUTING.md for contribution guidelines.

Donate

If you appreciate the work that went into this App Extension, please consider donating to Vue.js.

License

MIT