# How to Integrate Web-Tracing with Vue 2 Applications: Complete Setup Guide

> Learn to integrate Web-Tracing with Vue 2 applications easily. This guide covers installation and setup for seamless error tracking and SDK initialization in your project.

- Repository: [m-cheng-web/web-tracing](https://github.com/m-cheng-web/web-tracing)
- Tags: tutorial
- Published: 2026-03-06

---

**To integrate Web-Tracing with Vue 2, install the `@web-tracing/vue2` package and register it as a Vue plugin via `Vue.use()`, which automatically wires error handling and initializes the core SDK with your configuration.**

Web-Tracing is a pure-JavaScript monitoring SDK that unifies tracking for click events, page views, performance metrics, errors, network requests, and screen recordings. For Vue 2 applications, the dedicated integration package `@web-tracing/vue2` provides a plugin-based architecture that intercepts Vue-specific errors and initializes the tracing core without requiring changes to existing component logic.

## Vue 2 Integration Architecture

The Vue 2 integration centers on the plugin entry point at [`packages/vue2/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/vue2/index.ts). This file exposes an `install` function that Vue invokes when you call `Vue.use()`. During installation, the plugin performs two critical operations:

1. **Error Handling Override** – The plugin replaces `Vue.config.errorHandler` with a wrapper that captures Vue rendering errors, normalizes them via `parseError()`, and forwards structured payloads to the core SDK using `traceError()`. Your original error handler, if defined, is preserved and called after the tracing logic.
2. **SDK Initialization** – The plugin invokes `init(options)` from `@web-tracing/core`, creating a reactive global options store and starting the event-dispatch loop for automatic page views, performance monitoring, and network interception.

The plugin re-exports core utilities such as `tracePerformance`, `traceCustomEvent`, `tracePageView`, and `destroyTracing` from `@web-tracing/core`, allowing you to import these pure functions directly into Vue components for manual instrumentation.

## Step-by-Step Implementation

### 1. Install the Vue 2 Package

Add the framework-specific package to your project using your preferred package manager:

```bash
pnpm install @web-tracing/vue2

# or

npm install @web-tracing/vue2

# or

yarn add @web-tracing/vue2

```

### 2. Register the Plugin in Your Entry File

In your [`main.js`](https://github.com/m-cheng-web/web-tracing/blob/main/main.js) (or [`main.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/main.ts)), import the plugin and register it with `Vue.use()`, passing a configuration object that defines your DSN, sampling rates, and feature toggles:

```javascript
// main.js
import Vue from 'vue'
import WebTracing from '@web-tracing/vue2'

Vue.use(WebTracing, {
  dsn: '/trackweb',              // Endpoint for sending telemetry data
  appName: 'my-vue2-app',
  debug: true,
  pv: true,                      // Enable automatic page-view tracking
  performance: true,             // Capture performance metrics
  error: true,                   // Enable error monitoring
  event: true,                   // Track click and custom events
  cacheMaxLength: 10,
  cacheWatingTime: 1000,
  userUuid: 'init_userUuid',
  scopeError: true,
  tracesSampleRate: 0.5,         // Sample 50% of traces
  ignoreErrors: ['111', /^promise/, /.*split is not .* function/],
  ignoreRequest: [/getAllTracingList/, /cleanTracingList/],

  // Optional lifecycle hooks for transforming or filtering data
  beforePushEventList(data) {
    // Modify event payload before it enters the send queue
    return data
  },
  beforeSendData(data) {
    // Return false to cancel the network request
    return data
  },
  afterSendData(data) {
    console.log('Telemetry sent:', data)
  }
})

```

*Source: Implementation based on [`packages/vue2/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/vue2/index.ts) and configuration patterns from [`docs/guide/starting.md`](https://github.com/m-cheng-web/web-tracing/blob/main/docs/guide/starting.md).*

### 3. Implement Manual Tracing in Components

While the plugin automatically captures Vue errors and page views, you can manually track custom events or update global settings by importing functions from `@web-tracing/core`:

```vue
<template>
  <button @click="trackClick">Track Interaction</button>
</template>

<script>
import { traceCustomEvent, options } from '@web-tracing/core'

export default {
  methods: {
    trackClick() {
      // Emit a structured custom event with arbitrary metadata
      traceCustomEvent({
        eventType: 'click',
        eventName: 'purchase_button_clicked',
        extra: { productId: 'SKU-123', price: 99.99 }
      })
    }
  },
  mounted() {
    // Dynamically enable screen recording at runtime
    options.value.recordScreen = true
  }
}
</script>

```

*Source: Component usage patterns demonstrated in [`examples/vue2/src/views/event/index.vue`](https://github.com/m-cheng-web/web-tracing/blob/main/examples/vue2/src/views/event/index.vue).*

## Configuration Reference

The `InitOptions` interface (defined in `@web-tracing/core` types) accepts the following key parameters:

- **`dsn`** – The HTTP endpoint where telemetry payloads are sent.
- **`appName`** – Identifier for your application in the monitoring dashboard.
- **`tracesSampleRate`** – Number between 0 and 1 controlling the percentage of traces to capture.
- **`ignoreErrors`** – Array of strings or regular expressions for error messages to suppress.
- **`ignoreRequest`** – Array of URL patterns for network requests to exclude from tracing.

Lifecycle hooks allow you to intercept the data pipeline:

- **`beforePushEventList(data)`** – Transform or filter events before they enter the in-memory cache.
- **`beforeSendData(data)`** – Inspect or cancel the network request by returning `false`.
- **`afterSendData(data)`** – Execute logic after successful transmission.

## Running the Official Example

To see a fully configured Vue 2 application with Web-Tracing, examine the source in [`examples/vue2/src/main.js`](https://github.com/m-cheng-web/web-tracing/blob/main/examples/vue2/src/main.js) within the main repository, or clone the standalone demonstration project:

```bash
git clone https://github.com/m-cheng-web/web-tracing-examples-vue2.git
cd web-tracing-examples-vue2
pnpm install
pnpm dev   # Starts Vite development server

```

This demo illustrates plugin registration, component-level error boundaries, and manual `traceCustomEvent` calls in a real-world routing context.

## Summary

- Install `@web-tracing/vue2` via npm, pnpm, or yarn to add the Vue-specific plugin wrapper.
- Register the plugin with `Vue.use()` in your entry file to automatically capture Vue errors and initialize the core SDK.
- Configure tracing behavior—including sampling rates, filtering rules, and HTTP endpoints—via the options object passed during installation.
- Import `traceCustomEvent` and other utilities from `@web-tracing/core` for manual instrumentation inside Vue components.
- Access the reactive `options.value` object to toggle features like screen recording at runtime without reloading the application.

## Frequently Asked Questions

### Does the Vue 2 plugin capture all application errors automatically?

Yes. The plugin overrides `Vue.config.errorHandler` in [`packages/vue2/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/vue2/index.ts) to intercept component rendering errors and lifecycle exceptions. It normalizes the error object using `parseError()` and forwards it to the core SDK via `traceError()`, ensuring Vue-specific stack traces are preserved while maintaining any previously defined error handler.

### Can I use Web-Tracing with Vue 2 without the plugin?

While technically possible by manually calling `init()` from `@web-tracing/core`, the plugin is strongly recommended. Without it, you would need to manually wire `Vue.config.errorHandler` to capture Vue-specific error contexts and normalize component stack traces, which the plugin handles automatically in [`packages/vue2/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/vue2/index.ts).

### How do I dynamically change tracing options after initialization?

Import the `options` object from `@web-tracing/core` and mutate its `value` property (e.g., `options.value.recordScreen = true`). This reactive store is created when the plugin calls `init()` and can be updated from any Vue component to adjust sampling rates, enable screen recording, or modify the DSN at runtime.

### Where can I find the complete source code for the Vue 2 integration?

The plugin implementation resides in [`packages/vue2/index.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/vue2/index.ts), which contains the `install` function and error handler wrapper. For usage examples, see [`examples/vue2/src/main.js`](https://github.com/m-cheng-web/web-tracing/blob/main/examples/vue2/src/main.js) for plugin registration and [`examples/vue2/src/views/event/index.vue`](https://github.com/m-cheng-web/web-tracing/blob/main/examples/vue2/src/views/event/index.vue) for component-level tracing implementations. Documentation is available in [`docs/guide/starting.md`](https://github.com/m-cheng-web/web-tracing/blob/main/docs/guide/starting.md).