Introduction

TraceKit provides framework-specific wrappers that add error boundaries, navigation breadcrumbs, and framework-aware error capture on top of the core @tracekit/browser SDK.

For the core API reference (init, captureException, captureMessage, setUser, setTag, setExtra, addBreadcrumb, getClient), see the Browser SDK documentation.

React

@tracekit/react provides an error boundary component, React 19 createRoot error hooks, and React Router breadcrumb tracking.

Installation

npm install @tracekit/react

Quick Start

import { init, TraceKitErrorBoundary } from '@tracekit/react';

init({ apiKey: 'your-api-key', release: '1.0.0' });

function App() {
  return (
    <TraceKitErrorBoundary fallback={<p>Something went wrong.</p>}>
      <MyApp />
    </TraceKitErrorBoundary>
  );
}

TraceKitErrorBoundary

A React error boundary that captures render errors with componentStack context and sends them to TraceKit. Renders a user-provided fallback on error. Does not re-throw -- swallows the error and shows the fallback UI.

When an error is caught, the boundary calls captureException with the error and componentStack context, marks it as handled: true with mechanism react.errorBoundary, then renders the fallback.

Props

The fallback render function receives three arguments:

// Fallback render function signature
(error: Error, componentStack: string, resetError: () => void) => ReactNode

// Example usage
<TraceKitErrorBoundary
  fallback={(error, componentStack, resetError) => (
    <div>
      <h2>Error: {error.message}</h2>
      <pre>{componentStack}</pre>
      <button onClick={resetError}>Try again</button>
    </div>
  )}
>
  <MyApp />
</TraceKitErrorBoundary>

traceKitCreateRootOptions

A function that returns React 19 createRoot error callbacks. These hooks capture errors that occur outside of error boundaries: uncaught errors, caught errors from error boundaries (with additional context), and recoverable hydration mismatches.

import { createRoot } from 'react-dom/client';
import { traceKitCreateRootOptions } from '@tracekit/react';

const root = createRoot(document.getElementById('root')!, {
  ...traceKitCreateRootOptions(),
});

root.render(<App />);

Returned Hooks

TraceKitRouterBreadcrumbs

An invisible component that records React Router navigation changes as breadcrumbs. Must be placed inside a BrowserRouter.

Props

import { BrowserRouter, Routes, Route } from 'react-router';
import { TraceKitRouterBreadcrumbs } from '@tracekit/react';

function App() {
  return (
    <BrowserRouter>
      <TraceKitRouterBreadcrumbs />
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/users/:id" element={<UserProfile />} />
      </Routes>
    </BrowserRouter>
  );
}

Re-exported Functions

@tracekit/react re-exports all public functions from @tracekit/browser for convenience:

// These are all available from @tracekit/react
import {
  init,
  captureException,
  captureMessage,
  setUser,
  setTag,
  setExtra,
  addBreadcrumb,
  getClient,
} from '@tracekit/react';

Types

React-specific types exported from @tracekit/react:

Complete Example

Full React setup with ErrorBoundary, createRoot hooks, and Router breadcrumbs.

// main.tsx
import { createRoot } from 'react-dom/client';
import { init, traceKitCreateRootOptions } from '@tracekit/react';
import App from './App';

// 1. Initialize the SDK
init({
  apiKey: process.env.REACT_APP_TRACEKIT_API_KEY!,
  release: process.env.REACT_APP_VERSION || '0.0.0',
  environment: process.env.NODE_ENV || 'production',
});

// 2. Create root with React 19 error hooks
const root = createRoot(document.getElementById('root')!, {
  ...traceKitCreateRootOptions(),
});

root.render(<App />);

// App.tsx
import { BrowserRouter, Routes, Route } from 'react-router';
import {
  TraceKitErrorBoundary,
  TraceKitRouterBreadcrumbs,
  setUser,
} from '@tracekit/react';
import { Home } from './pages/Home';
import { UserProfile } from './pages/UserProfile';
import { Settings } from './pages/Settings';

export default function App() {
  return (
    <TraceKitErrorBoundary
      fallback={(error, componentStack, resetError) => (
        <div className="error-page">
          <h1>Something went wrong</h1>
          <p>{error.message}</p>
          <button onClick={resetError}>Try again</button>
        </div>
      )}
      onError={(error, componentStack) => {
        console.error('Caught by ErrorBoundary:', error.message);
      }}
    >
      <BrowserRouter>
        <TraceKitRouterBreadcrumbs />
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/users/:id" element={<UserProfile />} />
          <Route path="/settings" element={<Settings />} />
        </Routes>
      </BrowserRouter>
    </TraceKitErrorBoundary>
  );
}

Vue

@tracekit/vue provides a Vue plugin that auto-initializes the SDK, sets up Vue error handler chaining, and optionally captures Vue Router navigation breadcrumbs.

Installation

npm install @tracekit/vue

Quick Start

import { createApp } from 'vue';
import { TraceKitPlugin } from '@tracekit/vue';
import App from './App.vue';

const app = createApp(App);
app.use(TraceKitPlugin, {
  apiKey: 'your-api-key',
  release: '1.0.0',
});
app.mount('#app');

TraceKitPlugin

A Vue plugin that handles SDK initialization, error handler setup, and optional router breadcrumbs in a single app.use() call.

TraceKitVueOptions

Extends TracekitBrowserConfig (see Browser SDK configuration) with two additional options:

setupErrorHandler(app)

Manually set up the Vue error handler. The plugin calls this automatically, but you can call it directly if you need more control.

The error handler chains to the previous handler rather than overwriting it. If another library has already set app.config.errorHandler, TraceKit captures the error first, then re-calls the previous handler.

import { createApp } from 'vue';
import { init } from '@tracekit/browser';
import { setupErrorHandler } from '@tracekit/vue';

const app = createApp(App);

// Manual initialization if you need finer control
init({ apiKey: 'your-api-key' });
setupErrorHandler(app);

app.mount('#app');

setupRouterBreadcrumbs(router, parameterized?)

Manually set up Vue Router breadcrumbs. The plugin calls this automatically when a router is provided in options.

Uses router.afterEach to capture navigation events with from/to paths.

import { createRouter, createWebHistory } from 'vue-router';
import { setupRouterBreadcrumbs } from '@tracekit/vue';

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: Home },
    { path: '/users/:id', component: UserProfile },
  ],
});

// Capture navigation breadcrumbs
setupRouterBreadcrumbs(router);

// Or with actual URLs instead of parameterized patterns
setupRouterBreadcrumbs(router, false);

Re-exported Functions

@tracekit/vue re-exports core SDK functions for convenience:

import {
  captureException,
  captureMessage,
  setUser,
  setTag,
  setExtra,
  addBreadcrumb,
  getClient,
} from '@tracekit/vue';

Types

Vue-specific types exported from @tracekit/vue:

Complete Example

Full Vue setup with plugin, router, and user context.

// main.ts
import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import { TraceKitPlugin, setUser } from '@tracekit/vue';
import App from './App.vue';
import Home from './views/Home.vue';
import UserProfile from './views/UserProfile.vue';
import Settings from './views/Settings.vue';

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: Home },
    { path: '/users/:id', component: UserProfile },
    { path: '/settings', component: Settings },
  ],
});

const app = createApp(App);

// Install TraceKit with router breadcrumbs
app.use(TraceKitPlugin, {
  apiKey: import.meta.env.VITE_TRACEKIT_API_KEY,
  release: import.meta.env.VITE_APP_VERSION || '0.0.0',
  environment: import.meta.env.MODE,
  router,
  parameterizedRoutes: true,
});

app.use(router);
app.mount('#app');

// Set user context after authentication
router.beforeEach(async (to) => {
  const user = await authStore.getUser();
  if (user) {
    setUser({ id: user.id, email: user.email, username: user.name });
  }
});

Angular

@tracekit/angular supports both standalone applications (Angular 15+) and NgModule-based applications. It replaces Angular's default ErrorHandler with one that captures errors via TraceKit.

Installation

npm install @tracekit/angular

Quick Start (Standalone)

import { bootstrapApplication } from '@angular/platform-browser';
import { provideTraceKit } from '@tracekit/angular';
import { AppComponent } from './app.component';

bootstrapApplication(AppComponent, {
  providers: [
    ...provideTraceKit({
      apiKey: 'your-api-key',
      release: '1.0.0',
    }),
  ],
});

Standalone API (Angular 15+)

provideTraceKit(config)

Initializes the @tracekit/browser SDK and returns a Provider[] array that replaces Angular's default ErrorHandler with TraceKitErrorHandler. Use the spread operator to merge into your providers array.

TraceKitAngularConfig

Extends TracekitBrowserConfig (see Browser SDK configuration) with one additional option:

provideTraceKitRouter(parameterized?)

Returns a Provider[] array that sets up router breadcrumbs via APP_INITIALIZER. The router is lazily resolved from Angular's injector to avoid circular dependency issues.

import { provideRouter } from '@angular/router';
import { provideTraceKit, provideTraceKitRouter } from '@tracekit/angular';

bootstrapApplication(AppComponent, {
  providers: [
    ...provideTraceKit({ apiKey: 'your-api-key' }),
    provideRouter(routes),
    ...provideTraceKitRouter(),
  ],
});

NgModule API

TraceKitModule.forRoot(config)

For NgModule-based applications. Returns a module with providers that initializes the SDK and replaces the default ErrorHandler. Accepts the same TraceKitAngularConfig as provideTraceKit.

TraceKitErrorHandler

An Angular ErrorHandler implementation. Both provideTraceKit and TraceKitModule.forRoot register it automatically.

// TraceKitErrorHandler implements Angular's ErrorHandler interface.
// It captures errors via captureException and preserves Angular's
// default console.error output.
//
// Angular wraps errors in various ways. TraceKitErrorHandler
// automatically extracts the original error from:
//   - error.originalError (template errors)
//   - error.rejection (unhandled promise rejections)
//
// No @Injectable() decorator is used. TraceKit's Angular SDK is built
// with tsup/esbuild which cannot process Angular decorators. The class
// is registered via { provide: ErrorHandler, useClass: TraceKitErrorHandler }
// which works with plain constructors.

You do not need to import or register TraceKitErrorHandler directly -- it is registered by provideTraceKit() and TraceKitModule.forRoot().

setupAngularRouterBreadcrumbs(router, parameterized?)

Low-level function to manually subscribe to Angular Router events and capture navigation breadcrumbs. Most applications should use provideTraceKitRouter() instead, which handles this automatically via APP_INITIALIZER.

Subscribes to router.events and captures NavigationEnd events as breadcrumbs. NavigationEnd is detected by constructor name and duck-typing to avoid a direct import of the class from Angular Router.

Re-exported Functions

@tracekit/angular re-exports core SDK functions for convenience:

import {
  captureException,
  captureMessage,
  setUser,
  setTag,
  setExtra,
  addBreadcrumb,
  getClient,
} from '@tracekit/angular';

Types

Complete Examples

Standalone Application

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideRouter } from '@angular/router';
import { provideTraceKit, provideTraceKitRouter } from '@tracekit/angular';
import { AppComponent } from './app.component';

const routes = [
  { path: '', loadComponent: () => import('./home.component') },
  { path: 'users/:id', loadComponent: () => import('./user.component') },
];

bootstrapApplication(AppComponent, {
  providers: [
    ...provideTraceKit({
      apiKey: 'your-api-key',
      release: '1.0.0',
      environment: 'production',
    }),
    provideRouter(routes),
    ...provideTraceKitRouter(),
  ],
});

NgModule Application

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouterModule, Routes } from '@angular/router';
import { TraceKitModule } from '@tracekit/angular';
import { AppComponent } from './app.component';
import { HomeComponent } from './home.component';
import { UsersComponent } from './users.component';

const routes: Routes = [
  { path: '', component: HomeComponent },
  { path: 'users/:id', component: UsersComponent },
];

@NgModule({
  declarations: [AppComponent, HomeComponent, UsersComponent],
  imports: [
    BrowserModule,
    RouterModule.forRoot(routes),
    TraceKitModule.forRoot({
      apiKey: 'your-api-key',
      release: '1.0.0',
      environment: 'production',
    }),
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

Using TraceKit in a Component

// user.component.ts
import { Component, OnInit } from '@angular/core';
import { ActivatedRoute } from '@angular/router';
import { captureException, setUser } from '@tracekit/angular';

@Component({
  selector: 'app-user',
  template: '
{{ user?.name }}
',
})
export class UserComponent implements OnInit {
  user: any;

  constructor(private route: ActivatedRoute) {}

  ngOnInit() {
    const id = this.route.snapshot.paramMap.get('id');
    this.loadUser(id!);
  }

  async loadUser(id: string) {
    try {
      const res = await fetch('/api/users/' + id);
      this.user = await res.json();
      setUser({ id: this.user.id, email: this.user.email });
    } catch (err) {
      captureException(err as Error, { userId: id });
    }
  }
}

Next.js

@tracekit/nextjs supports Next.js multi-runtime architecture with separate initialization for client-side (browser) and server-side (Node.js/Edge). It provides error boundary components for both App Router and Pages Router.

Installation

npm install @tracekit/nextjs

Quick Start

// instrumentation-client.ts
import { initClient, onRouterTransitionStart } from '@tracekit/nextjs';

initClient({
  apiKey: process.env.NEXT_PUBLIC_TRACEKIT_API_KEY!,
  release: process.env.NEXT_PUBLIC_APP_VERSION,
});

export { onRouterTransitionStart };

// instrumentation.ts
import { initServer } from '@tracekit/nextjs';

export function register() {
  initServer({
    apiKey: process.env.TRACEKIT_API_KEY!,
    release: process.env.APP_VERSION,
  });
}

Multi-Runtime Architecture

Next.js runs code in two separate runtimes: the browser (client) and Node.js/Edge (server). Each runtime requires its own initialization.

initClient(config: TraceKitNextConfig)

Client-side initialization. Accepts the same options as TracekitBrowserConfig (see Browser SDK configuration). Call this in instrumentation-client.ts.

initServer(config: TraceKitServerConfig)

Server-side initialization. Stores configuration for use by captureRequestError. Call this inside the register() function in instrumentation.ts.

TraceKitServerConfig

onRouterTransitionStart

Next.js 15.3+ navigation hook that captures client-side route transitions as breadcrumbs. Export this from instrumentation-client.ts.

Signature

function onRouterTransitionStart(
  url: string,
  navigationType: 'push' | 'replace' | 'traverse'
): void

// instrumentation-client.ts
export { onRouterTransitionStart } from '@tracekit/nextjs';

Records breadcrumbs with from/to URLs and navigation type (push, replace, or traverse). Page loads do not trigger this hook -- they are captured by the base navigation integration from @tracekit/browser.

Breadcrumb Data

captureRequestError

Server-side request error capture. Matches Next.js onRequestError signature. Sends error payload to TraceKit via HTTP POST. Fire-and-forget -- never throws.

// instrumentation.ts
import { initServer, captureRequestError } from '@tracekit/nextjs';

export function register() {
  initServer({ apiKey: process.env.TRACEKIT_API_KEY! });
}

export const onRequestError = captureRequestError;

RequestErrorContext

Context provided by Next.js with each server error:

GlobalError

App Router global error component. Captures errors via captureException and renders a resettable error UI. Use as the default export in app/global-error.tsx.

// app/global-error.tsx
// Default export captures errors and renders a resettable error UI.
// In development, the error message is displayed for debugging.
export { GlobalError as default } from '@tracekit/nextjs';

// Or customize the error UI:
'use client';

import { useEffect } from 'react';
import { captureException } from '@tracekit/nextjs';

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    captureException(error);
  }, [error]);

  return (
    
      
        
Something went wrong!
        Try again
      
    
  );
}

withTraceKitErrorPage(Page)

Pages Router higher-order component. Wraps your custom error page to capture errors via captureException.

// pages/_error.tsx
import { withTraceKitErrorPage } from '@tracekit/nextjs';

function CustomErrorPage({ statusCode }: { statusCode?: number }) {
  return (
    

      
{statusCode ? statusCode + ' - Server Error' : 'Client Error'}
      
An unexpected error occurred.
    
  );
}

CustomErrorPage.getInitialProps = ({ res, err }: any) => {
  const statusCode = res ? res.statusCode : err ? err.statusCode : 404;
  return { statusCode, err };
};

export default withTraceKitErrorPage(CustomErrorPage);

Re-exported Functions

@tracekit/nextjs re-exports core SDK functions from @tracekit/browser for client-side use:

import {
  captureException,
  captureMessage,
  setUser,
  setTag,
  setExtra,
  addBreadcrumb,
  getClient,
} from '@tracekit/nextjs';

Types

Complete Example

All files needed for a full Next.js App Router setup.

// .env.local
NEXT_PUBLIC_TRACEKIT_API_KEY=your-client-api-key
TRACEKIT_API_KEY=your-server-api-key
APP_VERSION=1.0.0
NEXT_PUBLIC_APP_VERSION=1.0.0

// instrumentation-client.ts
import { initClient, onRouterTransitionStart } from '@tracekit/nextjs';

initClient({
  apiKey: process.env.NEXT_PUBLIC_TRACEKIT_API_KEY!,
  release: process.env.NEXT_PUBLIC_APP_VERSION,
  environment: process.env.NODE_ENV,
  tracePropagationTargets: [
    process.env.NEXT_PUBLIC_API_URL || 'https://api.example.com',
  ],
});

export { onRouterTransitionStart };

// instrumentation.ts
import { initServer, captureRequestError } from '@tracekit/nextjs';

export function register() {
  initServer({
    apiKey: process.env.TRACEKIT_API_KEY!,
    release: process.env.APP_VERSION,
    environment: process.env.NODE_ENV,
  });
}

export const onRequestError = captureRequestError;

// app/global-error.tsx
export { GlobalError as default } from '@tracekit/nextjs';

Nuxt

@tracekit/nuxt provides a Nuxt plugin factory and a composable for accessing TraceKit functions within components.

Installation

npm install @tracekit/nuxt

Quick Start

// plugins/tracekit.client.ts
import { defineNuxtPlugin } from '#imports';
import { createTraceKitPlugin } from '@tracekit/nuxt';

export default defineNuxtPlugin(createTraceKitPlugin({
  apiKey: 'your-api-key',
  release: '1.0.0',
}));

createTraceKitPlugin(config)

Creates a Nuxt plugin function that initializes the @tracekit/browser SDK, hooks into vue:error for component error capture, and provides composable functions via useNuxtApp().$tracekit.

TraceKitNuxtConfig

Extends TracekitBrowserConfig (see Browser SDK configuration) with one additional option:

useTraceKit()

A composable that returns TraceKit error capture functions. Works inside any Nuxt component setup since the SDK is already initialized by the plugin.

TraceKitComposable

<script setup lang="ts">
import { useTraceKit } from '@tracekit/nuxt';

const { captureException, setUser } = useTraceKit();

async function loadData() {
  try {
    const data = await $fetch('/api/dashboard');
    // ...
  } catch (err) {
    captureException(err as Error, { component: 'Dashboard' });
  }
}

// Set user context after authentication
onMounted(async () => {
  const { data: user } = await useFetch('/api/auth/me');
  if (user.value) {
    setUser({ id: user.value.id, email: user.value.email });
  }
});
</script>

setupRouterBreadcrumbs(router, parameterized?)

Manually set up router breadcrumb capture via afterEach guard. Nuxt uses Vue Router under the hood, so this works with useRouter().

// plugins/tracekit.client.ts
import { defineNuxtPlugin, useRouter } from '#imports';
import { createTraceKitPlugin, setupRouterBreadcrumbs } from '@tracekit/nuxt';

export default defineNuxtPlugin((nuxtApp) => {
  // Initialize TraceKit
  const provided = createTraceKitPlugin({
    apiKey: 'your-api-key',
    release: '1.0.0',
  })(nuxtApp);

  // Set up router breadcrumbs
  const router = useRouter();
  setupRouterBreadcrumbs(router);

  return provided;
});

setupTraceKitPlugin(nuxtApp, config)

Convenience function for inline setup inside an existing defineNuxtPlugin. Use this if you need to combine TraceKit initialization with other plugin logic.

// plugins/tracekit.client.ts
import { defineNuxtPlugin } from '#imports';
import { setupTraceKitPlugin } from '@tracekit/nuxt';

export default defineNuxtPlugin((nuxtApp) => {
  const provided = setupTraceKitPlugin(nuxtApp, {
    apiKey: 'your-api-key',
    release: '1.0.0',
  });

  // Additional plugin setup...
  console.log('TraceKit initialized');

  return provided;
});

Re-exported Functions

@tracekit/nuxt re-exports core SDK functions for convenience:

import {
  init,
  captureException,
  captureMessage,
  setUser,
  setTag,
  setExtra,
  addBreadcrumb,
  getClient,
} from '@tracekit/nuxt';

Types

Complete Example

Full Nuxt setup with plugin and component usage.

// plugins/tracekit.client.ts
import { defineNuxtPlugin, useRouter } from '#imports';
import { createTraceKitPlugin, setupRouterBreadcrumbs } from '@tracekit/nuxt';

export default defineNuxtPlugin((nuxtApp) => {
  const provided = createTraceKitPlugin({
    apiKey: useRuntimeConfig().public.tracekitApiKey as string,
    release: useRuntimeConfig().public.appVersion as string,
    environment: process.env.NODE_ENV,
    parameterizedRoutes: true,
  })(nuxtApp);

  // Optional: manual router breadcrumbs for more control
  const router = useRouter();
  setupRouterBreadcrumbs(router);

  return provided;
});

<!-- pages/users/[id].vue -->
<script setup lang="ts">
import { useTraceKit } from '@tracekit/nuxt';

const route = useRoute();
const { captureException, captureMessage, setUser } = useTraceKit();

const { data: user, error } = await useFetch(`/api/users/${route.params.id}`);

if (error.value) {
  captureException(new Error(error.value.message), {
    userId: route.params.id,
  });
}

// Track successful page views
captureMessage('User profile viewed', 'info');
</script>

<template>
  <div v-if="user">
    <h1>{{ user.name }}</h1>
    <p>{{ user.email }}</p>
  </div>
  <div v-else>
    <p>User not found</p>
  </div>
</template>

Troubleshooting

// Correct order: TraceKit first, then router
app.use(TraceKitPlugin, { apiKey: '...', router });
app.use(router);
app.mount('#app');

// These are equivalent:
import { captureException } from '@tracekit/browser';
import { captureException } from '@tracekit/react';
import { captureException } from '@tracekit/vue';
// Use whichever package you have installed

// Any framework wrapper init
init({
  apiKey: 'your-api-key',
  debug: process.env.NODE_ENV === 'development',
});