TanStack Start

Interfere uses TanStack Start’s Vite build and request middleware to capture browser sessions and server requests. The React provider connects browser capture to your route tree, while trace metadata connects browser and server work. The server integration requires Node.js. Start with a surface and keep your existing router options and deployment adapter as you follow the steps below.

Setup

Install and connect the build

npm install @interfere/vite @interfere/react

pnpm add @interfere/vite @interfere/react

yarn add @interfere/vite @interfere/react

bun add @interfere/vite @interfere/react

Add the Interfere plugin to vite.config.ts. Keep your existing plugins, aliases, and deployment adapter. TanStack Start must precede the React plugin:

vite.config.ts

import { interfere } from "@interfere/vite/plugin";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  build: { sourcemap: true },
  plugins: [tanstackStart(), react(), interfere()],
});

Set browser and server keys

Copy the keys from your surface into the build environment:

VITE_INTERFERE_PUBLIC_KEY=YOUR_SURFACE_PUBLIC_KEY
INTERFERE_PUBLIC_KEY=YOUR_SURFACE_PUBLIC_KEY
INTERFERE_API_KEY=YOUR_SURFACE_SECRET_KEY
INTERFERE_ENVIRONMENT=staging

Provide INTERFERE_PUBLIC_KEY and INTERFERE_ENVIRONMENT to the server runtime too. Use production for production deployments. Keep the secret key in the build environment.The server integration requires a Node.js runtime. The Cloudflare Workers deployment integration does not provide Node.js server instrumentation.

Initialize browser capture

Add init() to your router module, guarded so it runs only in the browser. Preserve your existing router options:

src/router.tsx

import { init } from "@interfere/vite/init";
import { createRouter } from "@tanstack/react-router";
import { routeTree } from "./routeTree.gen";

if (typeof window !== "undefined") {
  init();
}

export const getRouter = () => createRouter({ routeTree, scrollRestoration: true });

Capture server requests

Add these request middleware entries to src/start.ts. Initialization runs before Interfere opens a span for the request. Keep any existing middleware in the array:

src/start.ts

import { register } from "@interfere/vite/server";
import { interfereRequestMiddleware } from "@interfere/vite/tanstack-start";
import { createMiddleware, createStart } from "@tanstack/react-start";

const initializeInterfere = createMiddleware().server(async ({ next }) => {
  await register();
  return next();
});

export const startInstance = createStart(() => ({
  requestMiddleware: [initializeInterfere, interfereRequestMiddleware],
}));

Connect the root route

Add the provider around your root route’s content and include traceMeta() in the head metadata. Preserve your existing document shell, styles, providers, and error boundaries. The example below shows where these additions fit.

Root route example

src/routes/__root.tsx

import { InterfereProvider } from "@interfere/vite/provider";
import { traceMeta } from "@interfere/vite/tanstack-start";
import { HeadContent, Outlet, Scripts, createRootRoute } from "@tanstack/react-router";

export const Route = createRootRoute({
  head: () => ({
    meta: [
      { charSet: "utf-8" },
      { name: "viewport", content: "width=device-width, initial-scale=1" },
      ...traceMeta(),
    ],
  }),
  component: RootComponent,
});

function RootComponent() {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <InterfereProvider>
          <Outlet />
        </InterfereProvider>
        <Scripts />
      </body>
    </html>
  );
}

Set consent at browser initialization and review replay masking before recording customer sessions.

Verify capture

Build and deploy to staging. Report a test error from an existing browser event handler, then from a server handler, to check both sides:

import { capture } from "@interfere/vite/init";

capture(new Error("Interfere browser setup test"));

import { captureError } from "@interfere/vite/server";

captureError(new Error("Interfere server setup test"));

Check the surface’s event chart for incoming traffic. Keep the server running long enough to send its telemetry, then remove the test calls.

Next steps

User tracking, review configuration, or follow the investigation walkthrough once a problem appears.

Getting started

Product

Settings

Compliance

SDKs

Developer tools

Setup

Verify capture

Next steps

​Setup

​Verify capture

​Next steps

Setup

Verify capture

Next steps