---
name: shadowjs-realtime
description: "Work with @shadow-js/realtime. Build typed channels, presence and reconnecting clients. Decide who can join, publish and read before a connection receives data. Use when adding this package to an app or changing its configuration or integration."
---

# @shadow-js/realtime

Version: 1.0.2.

`@shadow-js/realtime` is the layer above Dusk's WebSocket and server-sent event routes.

## Start with the task

Read [the guide](https://realtime.shadowjs.net/guides/realtime/index.md) for setup and the task map. Read only the relevant task pages, then the API entries needed by your change.

- **Define the channel.** Set message types, authorization rules and resource limits.
- **Connect the client.** Subscribe, publish and react to presence changes.
- **Handle reconnects.** Respond to resume, gap and reset signals in the UI.

## Install

```sh
npm install @shadow-js/realtime
```

This integration requires a running Dusk realtime endpoint. Follow the guide's account, endpoint and environment setup before running the example.

### Peer dependencies

| Package | Supported range |
| --- | --- |
| `@shadow-js/core` | `^1.0.2` |

## Application example

`src/components/chat.tsx`

```tsx
import { createRealtime } from "@shadow-js/realtime/client";
import { useChannel, useChannelPresence } from "@shadow-js/realtime/hooks";

type Schema = {
  [name: `chat:${string}`]: { events: { message: { text: string } }; presence: { name: string } };
};
const rt = createRealtime<Schema>({ url: "/rt" });

export function Chat(props: { room: string }) {
  const chat = useChannel(rt, `chat:${props.room}`);
  const [members, setPresence] = useChannelPresence(chat.channel);
  setPresence({ name: "Ann" });
  return (
    <section>
      <p>{() => members().length} here, connection {() => chat.status()}</p>
      <p>{() => chat.lastMessage()?.data.text}</p>
      <button type="button" onClick={() => chat.publish("message", { text: "hi" })}>
        Say hi
      </button>
    </section>
  );
}
```

## Public entry points

Import from the entry point that owns the API. Its Markdown index lists every export; each symbol page contains its signature, options and examples.

| Import path | Reference |
| --- | --- |
| `@shadow-js/realtime` | [21 exports](https://realtime.shadowjs.net/reference/realtime/index.md) |
| `@shadow-js/realtime/server` | [26 exports](https://realtime.shadowjs.net/reference/realtime-server/index.md) |
| `@shadow-js/realtime/client` | [18 exports](https://realtime.shadowjs.net/reference/realtime-client/index.md) |
| `@shadow-js/realtime/hooks` | [5 exports](https://realtime.shadowjs.net/reference/realtime-hooks/index.md) |
| `@shadow-js/realtime/redis` | [11 exports](https://realtime.shadowjs.net/reference/realtime-redis/index.md) |
| `@shadow-js/realtime/cloudflare` | [13 exports](https://realtime.shadowjs.net/reference/realtime-cloudflare/index.md) |

## Task references

- [The model](https://realtime.shadowjs.net/guides/realtime/the-model/index.md): Delivery guarantees, per channel: messages arrive in seq order, never twice, and a client that reconnects gets every message the channel still retains after its last…
- [The server](https://realtime.shadowjs.net/guides/realtime/the-server/index.md)
- [The client](https://realtime.shadowjs.net/guides/realtime/the-client/index.md)
- [Where it runs](https://realtime.shadowjs.net/guides/realtime/where-it-runs/index.md)
- [More than one server](https://realtime.shadowjs.net/guides/realtime/more-than-one-server/index.md)
- [Limits and abuse](https://realtime.shadowjs.net/guides/realtime/limits-and-abuse/index.md): Everything is bounded, and the defaults are in DEFAULT_HUB_LIMITS: 64 KiB per frame, 64 channels per connection, 20 publishes per second per connection (burst 40),…
- [Moving from Socket.io](https://realtime.shadowjs.net/guides/realtime/moving-from-socket-io/index.md): What is different on purpose: channels are closed until a rule opens them, payloads are JSON, there is no Socket.io wire compatibility (a Socket.io client cannot…

## Complete reference

The [agent index](https://realtime.shadowjs.net/agent-index.json) lists every current guide, task and API page with its Markdown URL. Use it to find options or behavior not covered here.

Match the installed package version to this reference. Use the public entry points above rather than importing source files.

## Reference discovery

This site documents ShadowJS 1.0.2. The [complete page index](https://realtime.shadowjs.net/agent-index.json) includes every task, API symbol and Markdown URL. Read the relevant pages as needed; avoid loading the full catalog into context.