---
title: "Astro"
url: "https://spinetab.com/docs/setup/astro/"
description: "Add Spinetab to Astro and share live updates through a hydrated island."
---

# Astro

Add live updates to a hydrated Astro island. Choose your renderer and data library below for a complete recipe. The walkthrough on this page uses React.

The examples display a queue value such as `{ "open": 12 }`. Choose the source that matches your backend in step 3. Replace the URL and type with your API. A static Astro build does not create a live API endpoint: use an existing backend, with CORS configured if it is on a different origin.

## 1\. Add the integrations

```sh
pnpm add spinetab
```

Keep your existing integrations and add `spinetab()`. This example assumes [`@astrojs/react`](https://docs.astro.build/en/guides/integrations-guide/react/) is installed and configured for React components:

**File: `astro.config.mjs`**

```js
import react from "@astrojs/react";
import { defineConfig } from "astro/config";
import { spinetab } from "spinetab/astro";

export default defineConfig({
  integrations: [react(), spinetab()],
});
```

The Spinetab integration adds the worker build to Astro’s client build. Add it manually; `astro add spinetab` is not supported. Restart the dev server after changing the config.

## 2\. Create the client

**File: `src/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 live component

**File: `src/components/Queue.tsx`**

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

## 5\. Hydrate it on a page

**File: `src/pages/queue.astro`**

```astro
---
import { Queue } from "../components/Queue";
---

<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Queue</title>
  </head>
  <body>
    <h1>Queue</h1>
    <Queue client:load />
  </body>
</html>
```

[`client:load`](https://docs.astro.build/en/guides/framework-components/#hydrating-interactive-components) hydrates the component on page load. Without a `client:*` directive, Astro renders HTML only and the subscription never starts. Use `client:visible` if the feed should start only when its island becomes visible.

Server rendering produces the loading state without opening a connection. The React hook starts work when the island mounts and releases the subscription when it unmounts. You do not need `client:only` for this component.

## Check it across tabs

Visit `/queue` in your running app.

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 [Astro configuration](https://spinetab.com/docs/bundlers.md#astro) for plugin options.

## More recipes

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

**Available recipes**

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