---
title: "React Router"
url: "https://spinetab.com/docs/setup/react-router/"
description: "Add Spinetab to React Router Framework Mode and share live updates from a route component."
---

# React Router

This guide uses React Router **Framework Mode** with its Vite plugin. For a standalone React app using Declarative or Data Mode, follow the [Vite guide](https://spinetab.com/docs/setup/vite.md) instead.

The examples display a queue value such as `{ "open": 12 }`. Choose the source that matches your backend in step 3. Use an existing endpoint or replace the URL and type with your API. Spinetab does not create the endpoint.

## 1\. Add the Vite plugin

```sh
pnpm add spinetab
```

Keep your existing plugins and add `spinetab()`:

**File: `vite.config.ts`**

```ts
import { reactRouter } from "@react-router/dev/vite";
import { spinetab } from "spinetab/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [reactRouter(), spinetab()],
  optimizeDeps: { entries: ["app/**/*.{ts,tsx}"] },
});
```

The plugin generates the worker from your adapter imports. Keep any existing path-alias or styling plugins too, and restart the dev server. The `entries` setting includes route files in Vite’s initial dependency scan, avoiding a dependency reload on the first visit. Preserve any other entries your app already scans.

## 2\. Create the client

**File: `app/live.ts`**

```ts
import { createSpinetab } from "spinetab";
import { bindClient } from "spinetab/react";

export const spinetab = createSpinetab();
export const { useLive } = bindClient(spinetab);
```

## 3\. Choose your source

Choose the format your server already serves. Save **one** of these as `queue-source.ts` alongside `live.ts`. Each example receives the complete queue value, `{ "open": 12 }`, so the component below stays the same.

### Polling

Read a JSON response from `GET /api/queue` every five seconds by default.

**File: `queue-source.ts`**

```ts
import { polling } from "spinetab/polling";

export const queueSource = polling<{ open: number }>("/api/queue");
```

[Polling options](https://spinetab.com/docs/transports/polling.md)

### SSE

Your endpoint serves `text/event-stream` with JSON in each `data:` field.

**File: `queue-source.ts`**

```ts
import { sse } from "spinetab/sse";

export const queueSource = sse<{ open: number }>("/api/queue/events");
```

[SSE options and named events](https://spinetab.com/docs/transports/sse.md)

### WebSocket

Your WebSocket endpoint sends a JSON queue value in each text frame. This is a raw WebSocket feed; GraphQL and Socket.IO need their own adapters.

**File: `queue-source.ts`**

```ts
import { websocket } from "spinetab/websocket";

export const queueSource = websocket<{ open: number }>("/ws/queue", {
  decoder: "json",
});
```

[WebSocket options and custom protocols](https://spinetab.com/docs/transports/websocket.md)

### Fetch stream

Your endpoint streams one JSON value per line (NDJSON). Only declare it repeatable when opening the request again is safe.

**File: `queue-source.ts`**

```ts
import { stream } from "spinetab/stream";

export const queueSource = stream<{ open: number }>("/api/queue/stream", {
  repeatable: true,
});
```

[Fetch stream options](https://spinetab.com/docs/transports/stream.md)

These URLs are examples, not routes created by the plugin. Replace them with your API. For GraphQL, Socket.IO or a client library, see [how sources and integrations fit together](https://spinetab.com/docs/choose-integration.md).

## 4\. Add a route component

**File: `app/routes/queue.tsx`**

```tsx
import { queueSource } from "../queue-source";
import { useLive } from "../live";

export default function Queue() {
  const { data, error } = useLive(queueSource, {
    reconcile: "latest",
  });

  if (error) return <p role="alert">Could not load the queue: {error.code}</p>;
  if (data === undefined) return <p role="status">Loading queue…</p>;

  return <p>{data.open} open</p>;
}
```

Register it in your [route config](https://reactrouter.com/start/framework/routing), keeping your existing routes:

**File: `app/routes.ts`**

```ts
import { type RouteConfig, route } from "@react-router/dev/routes";

export default [
  // Keep your existing routes here.
  route("queue", "routes/queue.tsx"),
] satisfies RouteConfig;
```

Your existing `app/root.tsx` should render an `<Outlet />` for its child routes.

The hook renders the loading state during SSR and starts the subscription when the route component mounts in the browser. Unmounting releases it. This standard Framework Mode setup does not need a `"use client"` directive or disabled SSR. Use Spinetab in the component, not in a server `loader` or `action`.

## Check it across tabs

Visit `/queue` in your running app. Navigate away in one tab: the subscription in the other tab continues.

Open the page in two tabs of the same browser profile. With SharedWorker available, matching subscriptions share the upstream feed or polling schedule. Each component keeps its own value. For polling, a new subscriber can trigger a fresh read; check ongoing requests rather than expecting exactly one initial request.

Polling reads every five seconds by default and pauses when no consumer is eligible, such as when all subscribing tabs are hidden. It reads again when a tab returns. If worker sharing is unavailable, each tab runs its own subscriptions; see [execution modes](https://spinetab.com/docs/concepts/modes.md).

`reconcile: "latest"` fits these full-state feeds. After a delivery gap, the next value restores the displayed state. Use a [refresh policy](https://spinetab.com/docs/concepts/continuity.md) for feeds of incremental changes.

## Next steps

-   Use [GraphQL, Socket.IO or a client library](https://spinetab.com/docs/choose-integration.md) with this setup.
-   Add [authentication and user scopes](https://spinetab.com/docs/concepts/credentials.md) for private data. Keep request-specific credentials out of server module singletons.
-   Read [continuity and recovery](https://spinetab.com/docs/concepts/continuity.md) before using an event stream: reconnecting alone cannot recover missed events.
-   Check [compatible versions and restrictions](https://spinetab.com/docs/compatibility.md) for your stack.

See [Vite framework configuration](https://spinetab.com/docs/bundlers.md#ssr-frameworks-using-vite) for build options and [React bindings](https://spinetab.com/docs/bindings.md#react) for hook APIs.

## More recipes

Choose a data library and connection for a complete example using this framework.

**Available recipes**

- [React Router · Component state · HTTP polling](https://spinetab.com/docs/recipes/react-router/direct/polling.md)
- [React Router · Component state · Server-sent events](https://spinetab.com/docs/recipes/react-router/direct/sse.md)
- [React Router · Component state · WebSocket](https://spinetab.com/docs/recipes/react-router/direct/websocket.md)
- [React Router · Component state · Fetch stream](https://spinetab.com/docs/recipes/react-router/direct/stream.md)
- [React Router · Component state · GraphQL over WebSocket](https://spinetab.com/docs/recipes/react-router/direct/graphql-ws.md)
- [React Router · Component state · GraphQL over SSE](https://spinetab.com/docs/recipes/react-router/direct/graphql-sse.md)
- [React Router · Component state · Socket.IO](https://spinetab.com/docs/recipes/react-router/direct/socket-io.md)
- [React Router · TanStack Query · HTTP polling](https://spinetab.com/docs/recipes/react-router/query/polling.md)
- [React Router · TanStack Query · Server-sent events](https://spinetab.com/docs/recipes/react-router/query/sse.md)
- [React Router · TanStack Query · WebSocket](https://spinetab.com/docs/recipes/react-router/query/websocket.md)
- [React Router · TanStack Query · Fetch stream](https://spinetab.com/docs/recipes/react-router/query/stream.md)
- [React Router · TanStack Query · GraphQL over WebSocket](https://spinetab.com/docs/recipes/react-router/query/graphql-ws.md)
- [React Router · TanStack Query · GraphQL over SSE](https://spinetab.com/docs/recipes/react-router/query/graphql-sse.md)
- [React Router · TanStack Query · Socket.IO](https://spinetab.com/docs/recipes/react-router/query/socket-io.md)
- [React Router · SWR · HTTP polling](https://spinetab.com/docs/recipes/react-router/swr/polling.md)
- [React Router · SWR · Server-sent events](https://spinetab.com/docs/recipes/react-router/swr/sse.md)
- [React Router · SWR · WebSocket](https://spinetab.com/docs/recipes/react-router/swr/websocket.md)
- [React Router · SWR · Fetch stream](https://spinetab.com/docs/recipes/react-router/swr/stream.md)
- [React Router · SWR · GraphQL over WebSocket](https://spinetab.com/docs/recipes/react-router/swr/graphql-ws.md)
- [React Router · SWR · GraphQL over SSE](https://spinetab.com/docs/recipes/react-router/swr/graphql-sse.md)
- [React Router · SWR · Socket.IO](https://spinetab.com/docs/recipes/react-router/swr/socket-io.md)
- [React Router · Apollo Client · GraphQL over WebSocket](https://spinetab.com/docs/recipes/react-router/apollo/graphql-ws.md)
- [React Router · Apollo Client · GraphQL over SSE](https://spinetab.com/docs/recipes/react-router/apollo/graphql-sse.md)
- [React Router · tRPC · tRPC over WebSocket](https://spinetab.com/docs/recipes/react-router/trpc/trpc-ws.md)
- [React Router · tRPC · tRPC over SSE](https://spinetab.com/docs/recipes/react-router/trpc/trpc-sse.md)
- [React Router · AI SDK · Resumable chat](https://spinetab.com/docs/recipes/react-router/ai/chat.md)
