React hooks / Next.js TypeScript SDK v3

This page documents the deprecated v3 hook API, useInngestSubscription() from @inngest/realtime/hooks. For new work, use useRealtime from the v4 SDK.

In v3, the React subscription experience centered around useInngestSubscription(). The hook subscribed using a server-minted realtime token and returned accumulated message data for the selected channel and topics.

Typical v3 flow

Define your realtime channel and topics with @inngest/realtime.
Mint a token on the server with getSubscriptionToken().
Pass that token, or a refreshToken function, to useInngestSubscription().

app/actions.ts

"use server";

import { getSubscriptionToken, Realtime } from "@inngest/realtime";
import { getInngestApp } from "@/inngest";
import { helloChannel } from "@/inngest/channels";

export async function fetchSubscriptionToken(): Promise<
  Realtime.Token<typeof helloChannel, ["logs"]>
> {
  return getSubscriptionToken(getInngestApp(), {
    channel: helloChannel(),
    topics: ["logs"],
  });
}

app/page.tsx

"use client";

import { useInngestSubscription } from "@inngest/realtime/hooks";
import { fetchSubscriptionToken } from "./actions";

export default function Home() {
  const { data, latestData, freshData, error, state, clear } =
    useInngestSubscription({
      refreshToken: fetchSubscriptionToken,
      bufferInterval: 100,
    });

  return (
    <div>
      <p>State: {state}</p>
      {error && <p>{error.message}</p>}
      <p>Latest: {JSON.stringify(latestData?.data)}</p>
      <p>Fresh batch: {freshData.length}</p>
      <button onClick={() => clear()}>Clear</button>
      {data.map((message, i) => (
        <div key={i}>{JSON.stringify(message.data)}</div>
      ))}
    </div>
  );
}

v3 hook API

enabled?: boolean
bufferInterval?: number
token?: Realtime.Subscribe.Token
refreshToken?: () => Promise<Realtime.Subscribe.Token>

The hook returned:

data
latestData
freshData
error
state
clear()

In v4, this model was replaced with useRealtime, which exposes connectionStatus, runStatus, and messages.byTopic / messages.all instead of the v3 data / latestData shape.

See the v4 hook docs

Learn the new useRealtime flow for Next.js and React.

v3 realtime overview

Return to the archived v3 realtime concepts page.