@m-tracker/vue-plugin

Vue 3 plugin for automatic error tracking. Captures Vue errors, unhandled rejections, and runtime exceptions, then sends them to your M-Tracker BFF backend.

Installation

npm install @m-tracker/vue-plugin
# or
pnpm add @m-tracker/vue-plugin
# or
yarn add @m-tracker/vue-plugin

Quick Start

import { createApp } from 'vue'
import App from './App.vue'
import MTracker from '@m-tracker/vue-plugin'

const app = createApp(App)

app.use(MTracker, {
  apiKey: 'mt_a1b2c3d4e5f67890abcdef1234567890abcdef12',
  dsn: 'https://your-m-tracker-server.com/api/errors',
})

app.mount('#app')

That's it — all errors are automatically captured and sent to your backend.

Options

interface PluginOptions {
  apiKey: string
  dsn: string
  capture?: {
    unhandled?: boolean      // default: true
    vueErrors?: boolean      // default: true
    consoleErrors?: boolean  // default: false
  }
  beforeSend?: (error: ErrorPayload) => ErrorPayload | null
}

| Option | Required | Default | Description | |--------|----------|---------|-------------| | apiKey | Yes | — | Project API key from your M-Tracker backend | | dsn | Yes | — | Backend endpoint URL (e.g. https://your-server.com/api/errors) | | capture.unhandled | No | true | Capture window.onerror and unhandledrejection events | | capture.vueErrors | No | true | Capture Vue component errors via app.config.errorHandler | | capture.consoleErrors | No | false | Capture console.error calls | | beforeSend | No | — | Hook to modify or suppress an error before it is sent |

Examples

With environment variables

app.use(MTracker, {
  apiKey: import.meta.env.VITE_MT_API_KEY,
  dsn: import.meta.env.VITE_MT_DSN,
})

Enrich errors with metadata

app.use(MTracker, {
  apiKey: import.meta.env.VITE_MT_API_KEY,
  dsn: import.meta.env.VITE_MT_DSN,
  beforeSend: (error) => {
    error.metadata = {
      ...error.metadata,
      appVersion: import.meta.env.VITE_APP_VERSION,
      environment: import.meta.env.MODE,
      userId: currentUser?.id ?? 'anonymous',
    }
    return error
  },
})

Filter out noisy errors

app.use(MTracker, {
  apiKey: '...',
  dsn: '...',
  beforeSend: (error) => {
    if (error.message.includes('ResizeObserver loop')) {
      return null // suppress — not sent
    }
    return error
  },
})

Disable specific capture channels

app.use(MTracker, {
  apiKey: '...',
  dsn: '...',
  capture: {
    unhandled: true,
    vueErrors: false,    // disable Vue error handler
  },
})

How It Works

The plugin registers up to three error handlers depending on your capture config:

| Handler | Errors captured | Extra metadata | |---------|----------------|----------------| | window.addEventListener('error') | JS runtime errors | lineno, colno | | window.addEventListener('unhandledrejection') | Unhandled promise rejections | — | | app.config.errorHandler | Vue component errors | lifecycle info string |

Each error is serialized into an ErrorPayload and sent via POST to your DSN with the x-api-key header.

interface ErrorPayload {
  message: string
  stack?: string
  url?: string
  userAgent?: string
  metadata?: Record<string, unknown>
}

Getting an API Key

1. Start your M-Tracker BFF server
2. Create a project:

curl -X POST https://your-server.com/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "slug": "my-app"}'

3. Copy the apiKey from the response and use it in the plugin options.

Manual Error Capture

Use captureError to send an error manually — useful for testing your integration or capturing errors in non-Vue code (e.g. API calls, utility functions).

import MTracker, { captureError } from '@m-tracker/vue-plugin'

// Install the plugin first
app.use(MTracker, { apiKey: '...', dsn: '...' })

// Then call captureError anywhere in your app
captureError(new Error('Payment failed'))

// Or pass a string
captureError('Payment failed')

// Attach extra metadata
captureError('Payment failed', {
  orderId: '123',
  userId: currentUser.id,
})

Signature

function captureError(
  error: Error | string,
  metadata?: Record<string, unknown>
): void

Note: captureError must be called after app.use(MTrackerPlugin). Calling it before installation logs a warning and does nothing.

Testing your integration

A quick way to verify errors are reaching your backend:

// In your browser console or a test component
import { captureError } from '@m-tracker/vue-plugin'

captureError('test — integration check', { source: 'manual' })

Then check your M-Tracker dashboard to confirm the event arrived.

TypeScript

The plugin ships with full TypeScript declarations. You can import types directly:

import type { PluginOptions, ErrorPayload } from '@m-tracker/vue-plugin'

License

MIT