Traceora docs / v0.4.8

Build software that
explains itself.

Traceora connects the dots between a user interaction and everything it sets in motion. This guide gets you from install to your first full-stack trace.

Quick start View examples

live trace / checkout-flowstreaming

button.click

cart.addItem

checkout.open

POST /api/cart

db.query

200 OK · 184ms

6 events linked→ zero context switching

01 / Installation

Add Traceora to your app

Install the core packages with your preferred package manager. The Vite plugin handles instrumentation at build time, so your components stay clean.

terminal

npm install @traceora/core @traceora/react @traceora/vite-plugin

02 / Configure Vite

Babel AST Instrumentation

Add the plugin before React in your Vite config. This will automatically inject performance and click tracking into all of your JSX elements.

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { traceoraPlugin } from '@traceora/vite-plugin'

export default defineConfig({
  plugins: [traceoraPlugin(), react()],
})

03 / React Providers

Add the DevTools UI

Wrap your application in TraceoraProvider and mount the floating TraceoraDevtools inside your entry point.

main.tsx

import { TraceoraProvider, TraceoraDevtools } from '@traceora/react';

createRoot(document.getElementById('root')!).render(
  <TraceoraProvider>
    <App />
    <TraceoraDevtools />
  </TraceoraProvider>
);

04 / Backend (Optional)

Connect your Express API

Install @traceora/express and add the middleware to seamlessly inject database logs and backend errors directly into your frontend timeline via HTTP headers. Note: If your frontend and backend run on different ports, you MUST allow the X-Traceora-TraceId header in your CORS config to prevent browser preflight blocks.

server.ts

import { traceora } from '@traceora/express';
import { emitTraceEvent } from '@traceora/node';
import cors from 'cors';

// MUST expose and allow custom headers for Traceora to work across CORS!
app.use(cors({ 
  allowedHeaders: ["Content-Type", "Authorization", "X-Traceora-TraceId"],
  exposedHeaders: ["X-Traceora-Events"] 
}));

app.use(traceora());

app.get('/api', (req, res) => {
  emitTraceEvent({
    type: "STATE_CHANGE",
    source: "MySQL",
    metadata: { query: "SELECT * FROM users" }
  });
  res.json({ ok: true });
});

05 / Next.js (Optional)

Full-Stack Next.js App Router

Using Next.js instead? Just install @traceora/next. Wrap your layout in TraceoraNextProvider, wrap your Server Actions in traceAction, and let Traceora do the rest.

app/api/users/route.ts

import { NextResponse } from "next/server";
import { withTraceora } from "@traceora/next";
import { traceoraPrismaExtension } from "@traceora/node";
import { PrismaClient } from "@prisma/client";

// Auto-tracks all database queries!
const prisma = new PrismaClient().$extends(traceoraPrismaExtension());

export const GET = withTraceora(async (req: Request) => {
  const users = await prisma.user.findMany();
  return NextResponse.json({ users });
});

Ready to see your first trace?

Run your app, open the Traceora panel in the bottom right, and click any button. Watch the timeline magically populate across your stack.

View GitHub Repository