Vue

Integrate the General Wisdom Provider SDK in a Vue 3 application using <script setup> and the Composition API lifecycle hooks.

Prerequisites

• Node.js 20+
• A Vue 3 + Vite project (or create one below)
• Your Application ID and API Key from the Provider Dashboard

Quick Setup

npm create vite@latest my-gw-app -- --template vue-ts
cd my-gw-app
npm install @mission_sciences/provider-sdk
npm run dev

Complete Example

Entry Point

src/main.ts

import { createApp } from 'vue';
import App from './App.vue';

createApp(App).mount('#app');

App Component

src/App.vue

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue';
import { MarketplaceSDK } from '@mission_sciences/provider-sdk';

const APP_ID = 'YOUR_APP_ID';
const API_KEY = 'YOUR_API_KEY';

let sdk: MarketplaceSDK | null = null;

onMounted(() => {
  sdk = new MarketplaceSDK({
    applicationId:            APP_ID,
    apiKey:                   API_KEY,
    environment:              'production',   // 'demo' | 'production'
    autoStart:                true,
    themeMode:                'auto',         // 'light' | 'dark' | 'auto'
    warningThresholdSeconds:  300,            // warn user 5 min before expiry
    enableHeartbeat:          false,          // keep-alive ping
    heartbeatIntervalSeconds: 30,
    debug:                    false,
  });
  sdk.initialize().catch(console.error);
});

onUnmounted(() => {
  sdk?.destroy();
});
</script>

<template>
  <div>
    <!-- Your application content -->
  </div>
</template>

Replace placeholders

Swap YOUR_APP_ID and YOUR_API_KEY with the credentials from your Provider Dashboard.

Pattern Breakdown

Why onMounted / onUnmounted?

The SDK manages a stateful connection to the General Wisdom platform. Vue's lifecycle hooks provide the correct timing:

Hook	Purpose
onMounted	DOM is ready; safe to initialize browser-dependent SDK features.
onUnmounted	Component is being torn down; release SDK resources to avoid leaks.

Why let sdk instead of ref()?

The SDK instance is an imperative side-effect, not reactive state. Wrapping it in ref() or reactive() would trigger Vue's reactivity system unnecessarily and can cause proxy-related issues with the SDK's internal state.

Composable Pattern (Optional)

For reuse across multiple components, extract the SDK logic into a composable:

src/composables/useMarketplaceSDK.ts

import { onMounted, onUnmounted } from 'vue';
import { MarketplaceSDK } from '@mission_sciences/provider-sdk';

interface SDKOptions {
  applicationId: string;
  apiKey: string;
  environment?: 'demo' | 'production';
  themeMode?: 'light' | 'dark' | 'auto';
}

export function useMarketplaceSDK(options: SDKOptions) {
  let sdk: MarketplaceSDK | null = null;

  onMounted(() => {
    sdk = new MarketplaceSDK({
      autoStart:                true,
      warningThresholdSeconds:  300,
      enableHeartbeat:          false,
      heartbeatIntervalSeconds: 30,
      debug:                    false,
      ...options,
    });
    sdk.initialize().catch(console.error);
  });

  onUnmounted(() => {
    sdk?.destroy();
  });
}

src/App.vue

<script setup lang="ts">
import { useMarketplaceSDK } from './composables/useMarketplaceSDK';

useMarketplaceSDK({
  applicationId: 'YOUR_APP_ID',
  apiKey:        'YOUR_API_KEY',
  environment:   'production',
});
</script>

<template>
  <div>
    <!-- Your application content -->
  </div>
</template>

Configuration Options

Option	Type	Default	Description
applicationId	string	—	Your registered application ID
apiKey	string	—	Your API key
environment	'demo' | 'production'	'production'	Target environment
autoStart	boolean	true	Start session automatically on init
themeMode	'light' | 'dark' | 'auto'	'auto'	UI theme preference
warningThresholdSeconds	number	300	Seconds before expiry to show warning
enableHeartbeat	boolean	false	Enable keep-alive pings
heartbeatIntervalSeconds	number	30	Interval between heartbeat pings
debug	boolean	false	Enable verbose console logging

Common Gotchas

Using reactive() for the SDK instance

Vue's reactive() wraps objects in a Proxy. The SDK does not expect to be proxied and may behave unpredictably. Always use a plain let variable.

Forgetting onUnmounted

Without the cleanup hook, navigating away from the component leaves the SDK connection open. This leaks memory and can cause duplicate session warnings.

Environment variables

In Vite, prefix env vars with VITE_:

.env

VITE_GW_APP_ID=app_abc123
VITE_GW_API_KEY=key_xyz789

const APP_ID = import.meta.env.VITE_GW_APP_ID;
const API_KEY = import.meta.env.VITE_GW_API_KEY;

Next Steps

• Session Lifecycle — understand session states and transitions
• React Guide — compare with the React integration
• Playground — experiment with SDK options interactively