Correlates matching frontend requests with Express-side events through response headers. No WebSocket or Redis service is required; configure CORS and tracing explicitly for your deployment.

📥 Installation

npm install @traceora/express

🔧 Quick Start

Two steps: add CORS headers, add the middleware.

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

const app = express();

// 1. MUST expose the custom header so the browser can read it
app.use(cors({ exposedHeaders: ['X-Traceora-Events'] }));

// 2. Add Traceora middleware BEFORE your routes
app.use(traceora());

// 3. Emit backend events anywhere — no need to pass `req` around
app.get('/api/users', async (req, res) => {
  emitTraceEvent({
    type: 'STATE_CHANGE',
    source: 'MySQL',
    metadata: {
      query: 'SELECT * FROM users WHERE active = 1',
      durationMs: 145,
    },
  });

  res.json({ success: true });
});

app.listen(4000);

⚙️ How It Works

React Frontend                       Express Backend
──────────────                       ───────────────
1. fetch('/api/users')
   + X-Traceora-TraceId header  →  2. Middleware reads TraceId
                                       Creates AsyncLocalStorage context

                                    3. emitTraceEvent() pushes events
                                       into the current request's store
                                       (works anywhere — controllers,
                                       services, deeply nested code)

                                    4. Before sending response, middleware
                                       serializes events into:
                                       X-Traceora-Events header

5. Frontend reads header       ←  
   Merges backend events into
   the same timeline under the
   same Trace ID

6. DevTools renders backend
   events inline with frontend

🗄️ Auto-Track Database Queries

No manual emitTraceEvent() needed for database operations:

import { PrismaClient } from '@prisma/client';
import { traceoraPrismaExtension } from '@traceora/node';

const prisma = new PrismaClient().$extends(traceoraPrismaExtension());

import mongoose from 'mongoose';
import { traceoraMongoosePlugin } from '@traceora/node';

mongoose.plugin(traceoraMongoosePlugin);

📖 API Reference

traceora()

Returns the Express middleware function. Must be used after cors() and before your routes.

emitTraceEvent(event)

emitTraceEvent(event: Omit<TraceEvent, 'id' | 'traceId' | 'timestamp'>): void

Pushes an event into the current request's trace context. If called outside an active HTTP request (or the frontend didn't initiate a trace), it safely no-ops.

🔗 Related Packages

| Package | Role | |---|---| | @traceora/node | Shared backend primitives (used by this package) | | @traceora/react | Frontend counterpart that sends the Trace ID | | @traceora/core | The underlying event engine |