@watchupltd/vue

Vue 3 integration for incident tracking with plugin system and composables.

Installation

npm install @watchupltd/vue

Quick Start

// main.ts
import { createApp } from 'vue';
import { IncidentPlugin } from '@watchupltd/vue';
import App from './App.vue';

const app = createApp(App);

app.use(IncidentPlugin, {
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  environment: 'production',
  captureConsoleErrors: true
});

app.mount('#app');

Usage in Components

Composition API

<script setup lang="ts">
import { useIncident } from '@watchupltd/vue';

const incident = useIncident();

const handleClick = async () => {
  try {
    await fetchData();
  } catch (error) {
    incident.captureError(error, {
      tags: { component: 'DataFetcher' }
    });
  }
};

const handleSuccess = () => {
  incident.captureMessage('Data loaded successfully', 'info');
};
</script>

<template>
  <button @click="handleClick">Load Data</button>
</template>

Options API

<script>
export default {
  methods: {
    async loadData() {
      try {
        await this.fetchData();
      } catch (error) {
        this.$incident.captureError(error);
      }
    }
  }
};
</script>

What It Tracks

Automatic Tracking

• Vue Component Errors: Via app.config.errorHandler
• Global JavaScript Errors: Via window.onerror
• Unhandled Promise Rejections: Via window.onunhandledrejection
• Console Errors: Optional via captureConsoleErrors config

Manual Tracking

• Custom errors via captureError()
• Log messages via captureMessage()
• User context via setUser()
• Tags via setTag() / setTags()
• Breadcrumbs via addBreadcrumb()

Configuration

interface VueIncidentConfig {
  apiKey: string;                    // Required: Your API key
  projectId: string;                 // Required: Your project ID
  endpoint?: string;                 // Optional: Custom API endpoint
  environment?: string;              // Optional: Environment (default: 'production')
  batchInterval?: number;            // Optional: Batch interval in ms (default: 5000)
  maxBatchSize?: number;             // Optional: Max events per batch (default: 10)
  maxRetries?: number;               // Optional: Max retry attempts (default: 3)
  enabled?: boolean;                 // Optional: Enable/disable SDK (default: true)
  captureConsoleErrors?: boolean;    // Optional: Capture console.error (default: false)
}

API Reference

useIncident()

Returns an IncidentClient instance with the following methods:

captureError(error: Error, context?: EventContext): Promise<string | null>

try {
  await riskyOperation();
} catch (error) {
  incident.captureError(error, {
    tags: { operation: 'data-fetch' },
    extra: { userId: '123' }
  });
}

captureMessage(message: string, level?: SeverityLevel, context?: EventContext): Promise<string | null>

incident.captureMessage('User completed onboarding', 'info', {
  tags: { flow: 'onboarding' }
});

addBreadcrumb(breadcrumb: Breadcrumb): void

incident.addBreadcrumb({
  message: 'User clicked submit button',
  category: 'user-action',
  level: 'info'
});

setUser(user: User | null): void

incident.setUser({
  id: 'user-123',
  email: '[email protected]',
  username: 'john_doe'
});

setTag(key: string, value: string): void

incident.setTag('version', '1.2.3');

setTags(tags: Record<string, string>): void

incident.setTags({
  browser: 'chrome',
  os: 'macos'
});

Examples

Track User Login

<script setup lang="ts">
import { useIncident } from '@watchupltd/vue';

const incident = useIncident();

const handleLogin = async (credentials) => {
  incident.addBreadcrumb({
    message: 'User attempting login',
    category: 'auth'
  });

  try {
    const user = await login(credentials);
    
    incident.setUser({
      id: user.id,
      email: user.email,
      username: user.username
    });

    incident.captureMessage('User logged in successfully', 'info');
  } catch (error) {
    incident.captureError(error, {
      tags: { flow: 'authentication' }
    });
  }
};
</script>

Track API Calls

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { useIncident } from '@watchupltd/vue';

const incident = useIncident();
const data = ref(null);

onMounted(async () => {
  incident.addBreadcrumb({
    message: 'Fetching user data',
    category: 'api'
  });

  try {
    data.value = await fetchUserData();
  } catch (error) {
    incident.captureError(error, {
      tags: { api: 'users', endpoint: '/api/users' }
    });
  }
});
</script>

Track Form Validation Errors

<script setup lang="ts">
import { useIncident } from '@watchupltd/vue';

const incident = useIncident();

const validateForm = (formData) => {
  const errors = [];
  
  if (!formData.email) {
    errors.push('Email is required');
  }
  
  if (errors.length > 0) {
    incident.captureMessage(`Form validation failed: ${errors.join(', ')}`, 'warning', {
      tags: { form: 'contact' },
      extra: { errors }
    });
  }
  
  return errors.length === 0;
};
</script>

Global Error Handler

The plugin automatically sets up a global error handler:

// This is done automatically by the plugin
app.config.errorHandler = (err, instance, info) => {
  incident.captureError(err, {
    extra: {
      componentName: instance?.$options.name,
      info
    },
    tags: {
      vue: 'true'
    }
  });
};

Options API Support

Access the client via this.$incident:

<script>
export default {
  name: 'MyComponent',
  methods: {
    async loadData() {
      try {
        const data = await fetchData();
        this.$incident.captureMessage('Data loaded', 'info');
        return data;
      } catch (error) {
        this.$incident.captureError(error);
      }
    },
    
    handleUserLogin(user) {
      this.$incident.setUser({
        id: user.id,
        email: user.email
      });
    }
  }
};
</script>

TypeScript Support

Full TypeScript support with type definitions included.

import type { VueIncidentConfig, IncidentClient } from '@watchupltd/vue';

const config: VueIncidentConfig = {
  apiKey: 'your-api-key',
  projectId: 'your-project-id'
};

Vue 2 Support

This package is designed for Vue 3. For Vue 2, use @watchupltd/browser instead.

Data Models

Event Model

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "proj_abc123",
  "fingerprint": "a1b2c3d4e5f6...",
  "title": "Error",
  "message": "Something went wrong",
  "stack_trace": "Error: Something went wrong\n    at Component (App.vue:10:5)",
  "service": "frontend",
  "environment": "production",
  "severity": "error",
  "timestamp": 1678901234567,
  "platform": "javascript",
  "release": "1.2.3",
  "metadata": {
    "vue": {
      "component": "MyComponent",
      "info": "render function"
    }
  },
  "user": {
    "id": "user-123",
    "email": "[email protected]",
    "username": "john_doe"
  },
  "tags": {
    "component": "MyComponent",
    "version": "1.2.3"
  },
  "breadcrumbs": [
    {
      "timestamp": 1678901230000,
      "message": "Component mounted",
      "category": "vue",
      "level": "info",
      "data": {"component": "MyComponent"}
    }
  ],
  "context": {
    "vue": {
      "version": "3.3.0"
    }
  }
}

User Model

{
  "id": "user-123",
  "email": "[email protected]",
  "username": "john_doe",
  "ip_address": "192.168.1.1"
}

Breadcrumb Model

{
  "timestamp": 1678901234567,
  "message": "User action description",
  "category": "user-action | navigation | http | database | console",
  "level": "fatal | error | warning | info | debug",
  "data": {
    "key": "value"
  }
}

License

MIT