Skip to content

The only tool you need to know what is happening and how to fix it.

7.6 KB
Raw Blame
# Plugin Setup

Configure the Traceway Vue plugin with `createTracewayPlugin`.

## Basic Setup

```javascript
import { createApp } from "vue";
import { createTracewayPlugin } from "@tracewayapp/vue";
import App from "./App.vue";

const app = createApp(App);

app.use(createTracewayPlugin({
  connectionString: "your-token@https://traceway.example.com/api/report",
}));

app.mount("#app");
```

## Plugin Options

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `connectionString` | `string` | Yes | Your Traceway connection string |
| `options` | `object` | No | SDK configuration options |

## SDK Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `debug` | `boolean` | `false` | Log events to console |
| `debounceMs` | `number` | `1500` | Batch delay in milliseconds |
| `retryDelayMs` | `number` | `10000` | Retry delay for failed uploads |
| `version` | `string` | `undefined` | Your application version |
| `ignoreErrors` | `Array<string \| RegExp>` | `DEFAULT_IGNORE_PATTERNS` | Error patterns to ignore. Pass `[]` to capture all errors. See [Error Filtering](/client/js-sdk/initialization#error-filtering) |
| `beforeCapture` | `(exception) => boolean` | `undefined` | Return `false` to suppress an error. See [Error Filtering](/client/js-sdk/initialization#error-filtering) |
| `sessionRecording` | `boolean` | `true` | Enable the rrweb session recorder |
| `sessionRecordingSegmentDuration` | `number` | `30000` | rrweb segment length in ms |
| `recordAllSessions` | `boolean` | `false` | Always-on session recording. See [Sessions](/learn/sessions) |
| `captureLogs` | `boolean` | `true` | Mirror `console.*` calls into the rolling log buffer |
| `captureNetwork` | `boolean` | `true` | Record `fetch` / `XHR` calls as network actions |
| `captureNavigation` | `boolean` | `true` | Record History API push / replace / pop transitions |

## Full Example

```javascript
import { createApp } from "vue";
import { createTracewayPlugin } from "@tracewayapp/vue";
import App from "./App.vue";

const app = createApp(App);

app.use(createTracewayPlugin({
  connectionString: "your-token@https://traceway.example.com/api/report",
  options: {
    debug: import.meta.env.DEV,
    version: import.meta.env.VITE_APP_VERSION,
    debounceMs: 1000,
  },
}));

app.mount("#app");
```

## Capture All Errors

By default, 4xx HTTP errors, network errors, and timeouts are ignored. To capture everything:

```javascript
app.use(createTracewayPlugin({
  connectionString: "your-token@https://traceway.example.com/api/report",
  options: {
    ignoreErrors: [],
  },
}));
```

## Automatic Error Handling

The plugin automatically installs `app.config.errorHandler` to capture:

- Component rendering errors
- Watcher errors
- Lifecycle hook errors

```javascript
// This is handled automatically by the plugin:
app.config.errorHandler = (err, instance, info) => {
  // Error is captured and sent to Traceway
};
```

Vue has a single `app.config.errorHandler` slot, and the plugin assigns it. If your app assigns its own handler after `app.use(createTracewayPlugin(...))`, it replaces Traceway's and component errors stop reaching the dashboard. To keep both, capture the error yourself inside your handler:

```javascript
import { captureException, captureMessage } from "@tracewayapp/vue";

app.use(createTracewayPlugin({
  connectionString: "your-token@https://traceway.example.com/api/report",
}));

app.config.errorHandler = (err, instance, info) => {
  if (err instanceof Error) {
    captureException(err);
  } else {
    captureMessage(String(err));
  }
  myOwnErrorReporter(err, info);
};
```

## Environment-Specific Configuration

```javascript
const connectionString = import.meta.env.PROD
  ? import.meta.env.VITE_TRACEWAY_PROD
  : import.meta.env.VITE_TRACEWAY_DEV;

app.use(createTracewayPlugin({
  connectionString,
  options: {
    debug: import.meta.env.DEV,
  },
}));
```

## Custom Attributes

Attach app-level identifiers (`userId`, `tenant`, feature flags, etc.) to every session and exception. The `useTracewayAttributes` composable is the Vue way to do it. Pass a getter and it tracks reactive state, pushes only the keys that changed, and removes the keys it owns when the component unmounts:

```vue
<script setup>
import { useTracewayAttributes } from "@tracewayapp/vue";
import { useUser } from "./auth";

const { user, org } = useUser();
useTracewayAttributes(() =>
  user.value && org.value
    ? { userId: user.value.id, tenant: org.value.id }
    : null
);
</script>
```

Return `null` when there is nothing to attach. The composable then removes the keys it had set.

There is a declarative wrapper for the same thing. It renders nothing and removes its keys on unmount:

```vue
<script setup>
import { TracewayAttributes } from "@tracewayapp/vue";
import { useUser } from "./auth";

const { user, org } = useUser();
</script>

<template>
  <TracewayAttributes
    v-if="user && org"
    :attributes="{ userId: user.id, tenant: org.id }"
  />
</template>
```

Treat every key you pass to the composable or the component as owned by it. Do not set the same key with `setAttribute` elsewhere, because the unmount cleanup will remove it.

You can also drive the scope imperatively from `watchEffect`:

```vue
<script setup>
import { watchEffect } from "vue";
import { setAttributes, removeAttribute } from "@tracewayapp/vue";
import { useUser } from "./auth";

const { user, org } = useUser();
watchEffect(() => {
  if (user.value && org.value) {
    setAttributes({ userId: user.value.id, tenant: org.value.id });
  } else {
    removeAttribute("userId");
    removeAttribute("tenant");
  }
});
</script>
```

Use `removeAttribute` per key here rather than `clearAttributes()`. `clearAttributes()` empties the whole global scope, so it also drops keys set by other parts of the app.

The full API (`setAttribute`, `setAttributes`, `removeAttribute`, `clearAttributes`) is re-exported from `@tracewayapp/vue`. Layering on each event: **defaults < global scope < per-call**. See [Sessions](/learn/sessions) for the full attribute model.

## Manual Injection

For advanced use cases, you can use the injection key directly:

```vue
<script setup>
import { inject } from "vue";
import { TracewayKey } from "@tracewayapp/vue";

const traceway = inject(TracewayKey);
traceway.captureException(new Error("Manual capture"));
</script>
```

However, the `useTraceway` composable is preferred for most use cases.

## Vite Configuration

Add your connection string to `.env`:

```
VITE_TRACEWAY_CONNECTION=your-token@https://traceway.example.com/api/report
```

Use in your app:

```javascript
app.use(createTracewayPlugin({
  connectionString: import.meta.env.VITE_TRACEWAY_CONNECTION,
}));
```

## Nuxt Integration

For Nuxt 3, create a plugin:

```javascript
// plugins/traceway.ts
import { createTracewayPlugin } from "@tracewayapp/vue";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(createTracewayPlugin({
    connectionString: useRuntimeConfig().public.tracewayConnection,
  }));
});
```

Name the file `traceway.ts`, not `traceway.client.ts`. A `.client` plugin never runs during SSR, so the injection key is missing on the server and the first component calling `useTraceway()` fails the render with `useTraceway must be used within a Vue app that has installed the Traceway plugin` (HTTP 500). The plugin is safe to run universally: it only installs the browser handlers and the recorder when `window` exists, so the server pass just provides the injection key.

Add to `nuxt.config.ts`:

```typescript
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      tracewayConnection: process.env.TRACEWAY_CONNECTION,
    },
  },
});
```