---
title: "Next.js"
url: "https://spinetab.com/docs/setup/nextjs/"
description: "Use Spinetab in the Next.js App Router with a live Client Component, server rendering and automatic worker bundling."
---

# Next.js

This guide adds a shared live feed to an existing Next.js App Router app. It works with Turbopack and webpack. Your page can remain a Server Component; the component that subscribes uses `"use client"`.

The examples display a queue value such as `{ "open": 12 }`. Choose the source that matches your backend in step 3. Use an API endpoint that supports your chosen transport. Next.js route handlers can serve HTTP responses; a WebSocket feed needs a WebSocket-capable backend. The plugin does not create these endpoints.

## 1\. Wrap your Next.js config

```sh
pnpm add spinetab
```

Pass your existing config to `withSpinetab`:

**File: `next.config.ts`**

```ts
import type { NextConfig } from "next";
import { withSpinetab } from "spinetab/next";

const nextConfig: NextConfig = {
  // Keep your existing options here.
};

export default withSpinetab(nextConfig);
```

The plugin handles the worker build. Restart `next dev` after changing the config. You do not need `transpilePackages` or `dynamic(..., { ssr: false })` for Spinetab.

## 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, useSpinetabStatus } = bindClient(spinetab);
```

Import this module only from Client Components or other client modules. If your project uses `src/app/`, put these files there instead.

## 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 Client Component

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

```tsx
"use client";

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

export 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>;
}
```

The [`"use client"` directive](https://nextjs.org/docs/app/getting-started/server-and-client-components#using-client-components) puts this component and its imports, including `live.ts`, in the client module graph. Creating the client starts no connection during server rendering. The hook starts the subscription after the component mounts in the browser and releases it when the component unmounts.

## 5\. Render it from your page

**File: `app/page.tsx`**

```tsx
import { Queue } from "./queue";

export default function Page() {
  return (
    <main>
      <h1>Queue</h1>
      <Queue />
    </main>
  );
}
```

Keep hooks and the `live.ts` import in Client Components. Server Components can render `Queue` and pass it serialisable props; they cannot call Spinetab hooks.

## Check the result

Open the page in two tabs of the same browser profile. With SharedWorker available, matching subscriptions share the upstream feed or polling schedule. Navigate away from the component in one tab: the other tab keeps receiving updates.

The hook renders the loading state during prerendering and initial hydration. If you chose polling, it starts in the browser, reads every five seconds by default and pauses when no consumer is eligible. See [polling](https://spinetab.com/docs/transports/polling.md) for the schedule and [execution modes](https://spinetab.com/docs/concepts/modes.md) if the client falls back to running in each tab.

`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](https://spinetab.com/docs/concepts/credentials.md) in the client module. Keep server secrets out of browser code.
-   Decide how your app [recovers missed events](https://spinetab.com/docs/concepts/continuity.md).

Monorepo commands, `basePath` and CDN asset prefixes need additional configuration; see [Next.js configuration](https://spinetab.com/docs/bundlers.md#nextjs-app-router). The [binding reference](https://spinetab.com/docs/bindings.md#nextjs-app-router) covers server rendering and client boundaries in detail.

## More recipes

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

**Available recipes**

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