@routeflow/browser

Browser SDK for Routeflow - Frontend-to-backend correlation and external dependency tracking.

Installation

npm install @routeflow/browser

Quick Start

Basic Setup (Correlation Only)

Add correlation headers to all same-origin API calls with one line:

import { initRouteflow } from "@routeflow/browser";

initRouteflow();

That's it! Now all same-origin fetch() calls will automatically include:

• x-routeflow-trace-id - Unique session ID (persisted across page navigations)
• x-routeflow-frontend-route - Current frontend route (e.g., /checkout)

How It Works

Automatic Correlation Headers

The SDK patches window.fetch to inject correlation headers into same-origin requests only:

// Your code
fetch("/api/orders", { method: "POST" });

// SDK automatically adds headers:
// x-routeflow-trace-id: 550e8400-e29b-41d4-a716-446655440000
// x-routeflow-frontend-route: /checkout

• Trace ID: Generated once per browser tab session, stored in sessionStorage
• Frontend Route: Tracks location.pathname (no query strings) by monitoring history API
• Framework agnostic: Works with React, Vue, Next.js, vanilla JS, etc.
• No CORS issues: Headers only added to same-origin requests

External Dependency Tracking (Optional)

Track calls to external APIs (Stripe, S3, etc.) and correlate them with frontend behavior:

initRouteflow({
  ingestKey: "your-routeflow-ingest-key",
  trackExternal: true,
  externalAllowlist: [
    "api.stripe.com",
    "*.amazonaws.com",
    "api.example.com"
  ]
});

The SDK will:

1. Track timing and outcomes of cross-origin fetch() calls
2. Send telemetry events to Routeflow backend
3. Only track hosts in the allowlist (for privacy and performance)

Privacy guarantee: Only the hostname is captured (no URLs, paths, query strings, headers, or bodies).

Configuration Options

interface RouteflowInitOptions {
  // Optional ingest key for sending external spans
  ingestKey?: string;

  // Enable/disable SDK (default: true)
  enabled?: boolean;

  // Environment name (default: "production")
  environment?: "production" | "staging" | "preview" | "development";

  // Sample rate for events 0.0-1.0 (default: 1.0)
  sampleRate?: number;

  // Enable tracking of external dependency calls (default: false)
  trackExternal?: boolean;

  // Allowlist of hostnames for external tracking (default: [])
  // Supports wildcards: "*.amazonaws.com"
  externalAllowlist?: string[];

  // Flush interval in milliseconds (default: 1000)
  flushIntervalMs?: number;

  // Maximum queue size before dropping events (default: 5000)
  maxQueueSize?: number;
}

Examples

With Environment

initRouteflow({
  environment: process.env.NODE_ENV === "production" ? "production" : "development"
});

With Runtime Ingest Key

If you inject the key at build time or via a script tag:

<script>
  window.__ROUTEFLOW_INGEST_KEY__ = "your-ingest-key-from-server";
</script>
<script src="/app.js"></script>

// SDK will automatically use window.__ROUTEFLOW_INGEST_KEY__
initRouteflow({
  trackExternal: true,
  externalAllowlist: ["api.stripe.com"]
});

With Code Version

Track which version of your frontend code generated events:

<script>
  window.__ROUTEFLOW_CODE_VERSION__ = "abc123def"; // Git SHA
</script>

Sampling for High Traffic

Only track 10% of sessions:

initRouteflow({
  trackExternal: true,
  externalAllowlist: ["api.stripe.com"],
  sampleRate: 0.1
});

Stats and Debugging

Check SDK status:

import { getRouteflowStats } from "@routeflow/browser";

const stats = getRouteflowStats();
console.log(stats);
// {
//   enabled: true,
//   trace_id: "550e8400-e29b-41d4-a716-446655440000",
//   current_route: "/checkout",
//   events_queued: 0,
//   events_sent: 42,
//   events_dropped: 0,
//   events_failed: 0,
//   external_tracking_enabled: true,
//   has_ingest_key: true
// }

Privacy & Security

What We Collect

For correlation (always):

• Trace ID (random UUID, session-scoped)
• Frontend route pathname (no query strings)

For external spans (opt-in):

• Target hostname only (e.g., api.stripe.com)
• HTTP method (e.g., POST)
• Duration in milliseconds
• Outcome (success, failure, unknown)
• Status code (if available)

What We DON'T Collect

• ❌ Full URLs
• ❌ URL paths or query parameters
• ❌ Request/response headers
• ❌ Request/response bodies
• ❌ Cookies
• ❌ User IDs or personal information
• ❌ IP addresses

CORS Considerations

• Correlation headers are only added to same-origin requests
• External tracking never modifies cross-origin requests
• No risk of triggering CORS preflight checks

Requirements

• Modern browsers with fetch support
• TypeScript 5.0+ (for development)
• No runtime dependencies

Advanced: Custom Backend URL

The SDK is hardcoded to send events to:

https://routeflow-backend-production.up.railway.app/v1/ingest

This is intentional to simplify setup. Contact support if you need a custom backend URL.

License

MIT

routeflow-browser