# Vue Integration

Add **analytics to your Vue Figma plugin** with the `useTode` composable. This guide shows you how to track user actions in Vue-based Figma plugins and widgets.

Starting from zero? `npm create @tode-sdk@latest my-plugin -- --framework vue` gives you all of this already in place; see [Start from a template](https://docs.usetode.dev/template).

## Installation

Install the core SDK and Vue adapter:

```bash
npm install @tode-sdk/core @tode-sdk/figma-vue
```

## Setup

### Initialize in Plugin Controller

Set up Tode in your plugin's main code file:

`code.ts`:

```typescript
import { tode } from '@tode-sdk/core';

// Show your Vue UI
figma.showUI(__html__, { width: 400, height: 600 });

// Initialize Tode for Figma plugin analytics
await tode.init({ apiKey: 'your-api-key' });

// Optional: Track plugin open from controller
tode.trackAction('plugin_opened');
```

### Configure Network Access

Add Tode's URLs to your plugin's `manifest.json` to enable analytics requests, and the `currentuser` permission so the SDK can read `figma.currentUser.id`. Without that permission events still arrive, but they are anonymous and the dashboard cannot count unique users. [Learn more about network access](https://developers.figma.com/docs/plugins/making-network-requests/).

```json title="manifest.json"
{
"name": "Your Plugin",
"id": "your-plugin-id",
"api": "1.0.0",
"main": "code.js",
"ui": "index.html",
"permissions": ["currentuser"],
"networkAccess": {
"allowedDomains": [
  "https://processing.usetode.dev",
  "wss://processing.usetode.dev"
]
}
}
```

### Use the Composable in Your Vue UI

Use `useTode` in your Vue components:

`App.vue`:

```vue
<script setup lang="ts">
import { useTode } from '@tode-sdk/figma-vue';

const { isReady, trackAction } = useTode();

const handleExport = (): void => {
  if (isReady.value) {
    trackAction('export_clicked');
  }
};
</script>

<template>
  <button @click="handleExport" :disabled="!isReady">
    Export Design
  </button>
  <p>Analytics: {{ isReady ? 'Connected' : 'Connecting...' }}</p>
</template>
```

## Composable Reference

### useTode()

Returns an object with the following properties and methods:

| Property/Method | Type | Description |
|-----------------|------|-------------|
| `tode` | `Tode` | The Tode instance for direct access (not a ref) |
| `isReady` | `Readonly<Ref<boolean>>` | Whether Tode is initialized ([`tode.isReady`](https://docs.usetode.dev/api#todeisready)) |
| `wsState` | `Readonly<Ref<WebSocketState>>` | Session connection state: `disconnected`, `connecting`, `connected` or `error` |
| `trackAction(name, options?)` | `function` | Track a simple action ([API](https://docs.usetode.dev/api#todetrackactionactionname)) |
| `trackActionWithMetric(name, value, options?)` | `function` | Track action with numeric value ([API](https://docs.usetode.dev/api#todetrackactionwithmetricactionname-value)) |

`useTode()` takes an optional object: `debug` (log adapter activity), `pingInterval` (keepalive in ms, default `5000`) and `onWebSocketStateChange` (called on every `wsState` change).

The session connection is shared: however many components use Tode, the plugin UI opens one WebSocket and counts as one session. It closes when the last of them is gone.

## Examples

### Basic Tracking

`ToolButton.vue`:

```vue
<script setup lang="ts">
import { useTode } from '@tode-sdk/figma-vue';

const props = defineProps<{ tool: string }>();
const { isReady, trackAction } = useTode();

const handleClick = (): void => {
  // Track which tool was selected in your Figma plugin
  if (isReady.value) {
    trackAction(`tool_selected_${props.tool}`);
  }
};
</script>

<template>
  <button @click="handleClick">{{ tool }}</button>
</template>
```

### Track with Metrics

`ExportPanel.vue`:

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { useTode } from '@tode-sdk/figma-vue';

const { isReady, trackActionWithMetric } = useTode();
const selectedItems = ref<any[]>([]);

const handleExport = async (): Promise<void> => {
  // Perform export logic...

  // Track export with item count for Figma widget analytics
  if (isReady.value) {
    trackActionWithMetric('items_exported', selectedItems.value.length);
  }
};
</script>

<template>
  <button @click="handleExport">
    Export {{ selectedItems.length }} Items
  </button>
</template>
```

### Track Feature Views

`FeatureView.vue`:

```vue
<script setup lang="ts">
import { watch, ref } from 'vue';
import { useTode } from '@tode-sdk/figma-vue';

const { isReady, trackAction } = useTode();
const hasTrackedView = ref(false);

// Track feature view once when component mounts and Tode is ready
watch(isReady, (ready: boolean) => {
  if (ready && !hasTrackedView.value) {
    trackAction('feature_viewed');
    hasTrackedView.value = true;
  }
}, { immediate: true });
</script>

<template>
  <div>Feature Content</div>
</template>
```

### Options API

`ClassicComponent.vue`:

```vue
<script lang="ts">
import { defineComponent } from 'vue';
import { useTode } from '@tode-sdk/figma-vue';

export default defineComponent({
  setup() {
    const { isReady, trackAction, trackActionWithMetric } = useTode();
    return { isReady, trackAction, trackActionWithMetric };
  },
  methods: {
    handleClick(): void {
      if (this.isReady) {
        this.trackAction('button_clicked');
      }
    }
  }
});
</script>

<template>
  <button @click="handleClick" :disabled="!isReady">
    Track Action
  </button>
</template>
```

## Best Practices

### 1. Track Without Waiting for `isReady`

Events tracked before Tode is ready are held and sent once it is, so the check is optional:

```vue
<script setup>
const { isReady, trackAction } = useTode();

// Works during setup too
trackAction('plugin_opened');
</script>

<template>
  <!-- isReady is for UI state -->
  <button :disabled="!isReady">Export</button>
</template>
```

### 2. Use Computed Properties

```vue
<script setup>
import { computed } from 'vue';

const { isReady, trackAction } = useTode();

// Good - reactive computed
const canTrack = computed(() => isReady.value && !isLoading.value);
</script>

<template>
  <button :disabled="!canTrack" @click="trackAction('click')">
    Track
  </button>
</template>
```

### 3. Use Descriptive Action Names

```vue
<script setup>
const { trackAction } = useTode();

// Good - clear and descriptive
trackAction('export_to_png');
trackAction('layer_renamed');

// Bad - too vague
trackAction('click');
trackAction('action1');
</script>
```

### 4. Watch for Ready State Changes

```vue
<script setup>
import { watch } from 'vue';

const { isReady, trackAction } = useTode();

// Track when analytics becomes ready
watch(isReady, (ready) => {
  if (ready) {
    trackAction('analytics_connected');
  }
});
</script>
```

## Next Steps

- Learn about the [API Reference](https://docs.usetode.dev/api) for all available methods
- See other framework guides: [React](https://docs.usetode.dev/react), [Angular](https://docs.usetode.dev/angular), [Svelte](https://docs.usetode.dev/svelte)

Source: https://docs.usetode.dev/vue
