Devtools
The Chat SDK 3.0 Devtools — a read-only overlay that shows, for every open conversation, its window in the message store, the change log, sends, local storage, the realtime connection and the latest store events. Its own entry, not in your bundle unless you import it.
Devtools
Devtools is a read-only panel floating over the page, for developing and testing an SDK integration. When a message goes missing, shows up twice, lands out of order, or does not come back after a reconnect, open it and you see what the message store thinks right now, without adding logs or reproducing the bug a second time. The idea is the same as React Query Devtools: a separate entry, and you decide in which environments it is imported and how it opens.
What it is
- One entry in the SDK. The panel ships with
@openmaxai/chat-sdk, under the@openmaxai/chat-sdk/devtoolsentry. Import it only from there; there is nothing else to install. - Not in your bundle unless you import it. No other
@openmaxai/chat-sdkentry references it; if your code does not import@openmaxai/chat-sdk/devtools, your bundle contains none of the panel's code. - You pick the environments and how it opens. The panel does not look at
NODE_ENVand does not decide whether it is running in production: which environments import it, and which shortcut or URL parameter opens it, is decided in your host. - Read-only. The panel reads only through the store's public inspection API: it never writes to the store, sends no requests and does not touch local storage, so mounting, opening or closing it changes nothing about how chat behaves. See Read-only guarantee.
Install and import
The panel comes with @openmaxai/chat-sdk; there is nothing else to install. Put ChatDevtools anywhere inside ChatProvider. It reads the store and the realtime connection of that provider's host:
app.tsx
import { ChatDevtools } from "@openmaxai/chat-sdk/devtools";
import { ChatProvider } from "@openmaxai/chat-sdk/react";
export function App() {
return (
<ChatProvider host={host}>
<Chat />
<ChatDevtools />
</ChatProvider>
);
}
Written like this, the panel ends up in the bundle of every environment. To have it only outside production, see Enable it outside production only below.
Once mounted, ChatDevtools starts closed: it only adds a keyboard listener to the page and draws nothing.
Enable it outside production only
Use a dynamic import() behind a constant that is known at build time. When the constant is false the bundler drops the whole branch, import() included, so the production bundle has none of the panel's code, and the URL parameter and the shortcut do nothing.
chat-devtools-slot.tsx
import { lazy, Suspense } from "react";
// Build-time constant: the literal false in production builds, so the branch below is removed.
const devtoolsEnabled = process.env.NODE_ENV !== "production";
const ChatDevtools = devtoolsEnabled
? lazy(() =>
import("@openmaxai/chat-sdk/devtools").then((m) => ({ default: m.ChatDevtools })),
)
: null;
export function ChatDevtoolsSlot() {
if (!ChatDevtools) return null;
return (
<Suspense fallback={null}>
<ChatDevtools shortcut="Alt+Shift+D" urlParam="chat-devtools" />
</Suspense>
);
}
app.tsx
<ChatProvider host={host}>
<Chat />
<ChatDevtoolsSlot />
</ChatProvider>
Use a constant your build tool replaces at build time (NEXT_PUBLIC_* in Next.js, import.meta.env.* in Vite). A value known only at run time (say, a flag read from your API) works too, but then the panel's code stays in your bundle, as a chunk split off by import() and loaded on demand.
How to open it
| How | Default | Notes |
|---|---|---|
| Shortcut | Alt+Shift+D |
Press once to open, again to close. Change it with shortcut, turn it off with false. Works while focus is in an input too |
| URL parameter | chat-devtools |
When the page URL has ?chat-devtools=1, the panel opens on load. Rename it with urlParam, turn it off with false. Read once, at load |
| You control it | — | Pass open and onOpenChange and decide when it opens (say, a switch on a settings page). The shortcut and the URL parameter then call onOpenChange |
Once open, the panel floats in a corner of the page, does not block clicks on the chat, and can be collapsed to a small button.
What it shows
At the top is a conversation picker: it lists the open conversations right now (the ones gap-fill follows) and selects the most recently opened one. You can also pick a conversation the store loaded and has since closed (only its watermark is left then). Below, sections show the state of the selected conversation, then the global storage, the realtime connection and the event log. The panel refreshes when the data changes, at most once per frame.
Window
The conversation's loaded range in memory.
| Shows | Notes |
|---|---|
seq range |
The first and last seq the range covers, and whether there is older / newer |
| Count | Server messages in the range, and the limit (500). Local messages do not count; they are under Sends |
| Watermark | The highest seq received without a gap |
| Gaps | seq stretches the store knows it does not have: between the end of the range and the watermark (a late window, or the message at the watermark was deleted), or after the watermark, from a push that arrived but could not be attached. "None" when there are none |
| Gap-fill | Running now (and whether another run is queued after it); the last gap-fill's trigger, outcome (caughtUp, reloaded and so on), number of rounds and how long ago |
Change log
Progress of catching up on changes from the change log.
| Shows | Notes |
|---|---|
| Local change watermark | The last change applied in this conversation |
| Server head | The latest change number last read from the server. Higher than the local change watermark means changes are still missing |
| Early numbers | Change numbers that arrived ahead of a jump in the pushes, waiting for the ones before them |
| Last catch-up | Outcome, how many change-log rounds, how many messages were fetched by id, how many were gone, and whether the server said "too old" (tooOld; the latest window was swapped in, or the local segment dropped) |
Sends
| Shows | Notes |
|---|---|
| Local messages | Messages that are sending, failed, blocked, or confirmed but not yet matched with the server's copy: client_msg_id, state, and the server message id once matched |
| Changes in flight | Messages with your own reaction, edit or recall still pending, and those whose request succeeded and are waiting for the server's copy to bring the new content |
Local storage
| Shows | Notes |
|---|---|
| Storage | IndexedDB, memory, or a ChatStorage of your own; when IndexedDB is configured but memory is in use, the reason (another tab holds the lock, the browser has no Web Locks, IndexedDB would not open) |
| Tab lock | Whether this tab holds the lock on local data |
| Encryption | Whether encryption at rest is on |
| Approximate size | The browser's estimate of storage used by the site and its quota (the whole site, not only chat), read when the panel opens and refreshable by hand |
| Writes | Writes queued and not done yet, the reason and time of the last failed write, how many conversations were evicted for quota |
| This conversation | Whether the range is being written locally, and the seq range of the local segment |
Realtime
| Shows | Notes |
|---|---|
| Connection state | What the SDK sees of the connection: idle (no chat view has subscribed yet, so the adapter has not been asked to connect), started (the adapter was asked to connect; it does not report whether it is connected right now or reconnecting), closed (the host was disposed), or off (the adapter has no realtime channel) |
| Connection status (later) | The same value as useConnectionStatus (connected, reconnecting and so on) and whether gap-fill keeps failing, once that hook exists Planned |
| Last frame | When the adapter last handed the SDK an inbound signal. Heartbeats are not signals, so on a quiet conversation this ages even while the connection is fine |
| Last signal | The last realtime signal the gap-fill scheduler got (new messages, reconnected, a jump in change numbers) and which conversation it was for |
Event log
The latest 50 store events, newest first. Each is one dispatch (type, conversation, the message ids and seq involved, and who sent it: your code, gap-fill, the thread loader or a read-back from local data) with the change it made to the range; gap-fill starting and ending, local data being opened, cleared, or failing to write are in it too. You can filter by conversation.
The Copy button copies the 50 entries to the clipboard as JSON, ready to paste into an issue. By default it leaves out message text and attachment names and keeps fields like ids, seq and states; pass includeMessageContent to include the text. Recording starts when the panel mounts and goes on while it is closed, so when you open it you see what happened before.
Read-only guarantee
- Reads only the store's public inspection API. Everything the panel gets is a copy of a snapshot. It does not call
dispatch, the gap-fill scheduler or the thread loader, calls noChatStoragemethod, and makes no network request. - Does not change how chat behaves. Mounting, opening, closing or unmounting the panel leaves messages, gap-fill, local storage and the realtime connection behaving exactly as without it. The inspection API's own guarantees: Inspection API · Guarantees.
- Leaves nothing behind. The panel writes nothing to
localStorage,sessionStorage, IndexedDB or cookies, and is closed again after a reload (unless the URL parameter is there). - Copy goes to the clipboard only. The panel uploads nothing.
Hosts without the SDK
A host that uses @openmaxai/chat-store directly, without ChatProvider, imports ChatDevtoolsPanel from @openmaxai/chat-sdk/devtools and passes the store in. For the realtime section pass connection; without it the section is hidden:
store-devtools.tsx
import { ChatDevtoolsPanel } from "@openmaxai/chat-sdk/devtools";
<ChatDevtoolsPanel
store={store}
connection={() => ({ status: socket.status, lastFrameAt: socket.lastFrameAt })}
/>;
API
ChatDevtools
Import from @openmaxai/chat-sdk/devtools; must be inside ChatProvider.
| Prop | Type | Default | Description |
|---|---|---|---|
shortcut |
string | false |
"Alt+Shift+D" |
Shortcut to open and close, keys joined with +; modifiers are Ctrl, Alt, Shift, Meta, and Mod is Meta on macOS and Ctrl elsewhere. Keys are matched by physical position (event.code), so input methods and keyboard layouts do not matter. false adds no listener |
urlParam |
string | false |
"chat-devtools" |
Opens on load when the URL has this parameter (with the value 1 or true). false does not read it |
defaultOpen |
boolean |
false |
Uncontrolled: whether it starts open |
open |
boolean |
— | Controlled: whether it is open |
onOpenChange |
(open: boolean) => void |
— | Called when the shortcut, the URL parameter or the panel's close button wants to change whether it is open |
position |
"bottom-right" | "bottom-left" | "top-right" | "top-left" |
"bottom-right" |
Which corner it floats in |
includeMessageContent |
boolean |
false |
Show and copy message text and attachment names in the event log |
ChatDevtoolsPanel
Import from @openmaxai/chat-sdk/devtools; needs no ChatProvider. Takes every prop of ChatDevtools, plus:
| Prop | Type | Description |
|---|---|---|
store |
ChatStore |
Required. A store made by createChatStore |
connection |
() => { status: string; lastFrameAt?: number } |
Optional. Reads the realtime connection's state and the time of its last frame (a millisecond timestamp). Called whenever the panel refreshes, so it must be cheap and free of side effects |
Entry and package
| Entry | What is in it | Depends on |
|---|---|---|
@openmaxai/chat-sdk/devtools |
ChatDevtools, which takes the store and the connection from ChatProvider; ChatDevtoolsPanel, which takes the store you pass in |
Reads the store only through @openmaxai/chat-store/inspect; peer react 19 |
The panel's styles ship with the entry and apply only inside the panel's own root element. There is no CSS to import, and your theme variables do not affect it.
FAQ
What happens when a user presses the shortcut in production? With the pattern in Enable it outside production only, the production bundle has no panel code and nothing happens. With a plain static import, anyone who presses the shortcut can open it; the panel is read-only, but it shows message ids and conversation ids.
Does the panel slow chat down? While closed, it appends one entry to a 50-entry ring buffer per store event and redraws nothing. While open, it redraws at most once per frame. The cost on the store's side: Inspection API · Guarantees.
Can it see another tab's data? No. It shows the store in this tab; when another tab holds the lock on local data, this one shows "memory (another tab holds the lock)".
