vue-spur-monocle
Version:
> **Note:** This is **not** an official package. For the official Monocle documentation, please visit: [https://docs.spur.us/monocle](https://docs.spur.us/monocle)
187 lines (134 loc) • 5.25 kB
Markdown
# vue-spur-monocle
> **Note:** This is **not** an official package. For the official Monocle documentation, please visit: [https://docs.spur.us/monocle](https://docs.spur.us/monocle)
[](https://github.com/Xavier4492/vue-spur-monocle/actions/workflows/ci.yml)
[](https://github.com/Xavier4492/vue-spur-monocle/actions/workflows/release.yml)
[](https://www.npmjs.com/package/vue-spur-monocle)
[](LICENSE)
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](#installation)
* [Requirements](#requirements)
* [Usage](#usage)
* [1. Options API](#1-options-api)
* [2. Composition API](#2-composition-api)
* [API Reference](#api-reference)
* [`MonoclePlugin(opts: MonocleOptions): Plugin`](#monoclepluginopts-monocleoptions-plugin)
* [`useMonocle()`](#usemonocle)
* [Server-Side Rendering (SSR)](#server-side-rendering-ssr)
* [Tests & CI](#tests--ci)
* [Contributing](#contributing)
* [License](#license)
## Installation
```bash
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`):
```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:
```vue
<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:
```ts
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:
```vue
<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](https://vitest.dev/)
* Linting & type-checking using ESLint + TypeScript
* Automated releases via GitHub Actions + [Semantic Release](https://semantic-release.gitbook.io/)
## Contributing
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
## Donate
If you appreciate the work that went into this App Extension, please consider [donating to Vue.js](https://vuejs.org/support-vuejs/).
## License
MIT