Handle SanityLive connection events

Turn off or replace the default SanityLive event handlers in next-sanity, and learn when an "attempting to reconnect" console error needs attention.

The <SanityLive> component that defineLive returns keeps a connection open to the Live Content API and reacts to the events it receives. Each connection event has a default handler: some log to the browser console, and others refresh the route.

This guide shows how to turn off the default handlers, replace them with your own, and decide when a reconnect message needs attention.

Prerequisites:

• next-sanity v13 or later in a Next.js App Router project. Earlier versions don't have the onWelcome, onReconnect, and onRestart props, and onGoAway has a different signature.
• <SanityLive> set up with defineLive. See Add live content to your application.

<SanityLive> accepts one prop per connection event. When you leave a prop unset, its default handler runs:

• onWelcome: runs when the connection is established. Logs a console.info message such as <SanityLive> is connected and listening for live events to published content..
• onReconnect: runs when the connection drops and a reconnect attempt is scheduled. Logs <SanityLive> is attempting to reconnect with console.error.
• onRestart: runs when the Live Content API restarts the event stream. Calls router.refresh() so Server Components render with fresh data.
• onGoAway: runs when the API closes the connection and won't deliver live events, for example when connection limits are reached. Logs a console.warn message and refreshes the route every 30 seconds instead.
• onError: runs on connection, parsing, and event-processing errors. Logs the error with console.error. When the error is caused by the site's origin missing from the project's CORS origins, it logs a console.warn message with a link to add the origin.

When <SanityLive> includes drafts, the default connection, reconnect, and goaway messages start with <SanityLive includeDrafts> instead.

The default onReconnect handler logs with console.error, so <SanityLive> is attempting to reconnect appears as an error in the browser console. On its own, it doesn't mean live updates are broken.

A reconnect happens when the connection drops for a reason that's expected to be temporary: a network interruption, a server error (5xx), a request timeout (408), or rate limiting (429). The client reconnects automatically. A successful reconnect fires the welcome event again, so with the default handlers the connected message follows the reconnect message.

If the server rejects the connection with any other 4xx status, such as for an expired or invalid token, the client doesn't reconnect. The error goes to onError instead.

Investigate when reconnect messages repeat with no connected message in between, or when onError reports errors. To keep routine reconnects out of the error log, turn off onReconnect or replace it with a handler that logs a warning.

Pass false to a handler prop to turn off its default behavior. This example turns off the connection and reconnect logs:

import {SanityLive} from '@/sanity/lib/live'

export default function RootLayout({children}: {children: React.ReactNode}) {
  return (
    <html lang="en">
      <body>
        {children}
        <SanityLive onWelcome={false} onReconnect={false} />
      </body>
    </html>
  )
}

Turning off onRestart or onGoAway changes more than logging:

• onRestart={false}: the route no longer refreshes when the Live Content API restarts the event stream.
• onGoAway={false}: there's no fallback polling. When the API closes the connection, <SanityLive> passes the error Sanity Live connection closed, automatic revalidation is disabled, the server gave this reason: REASON to onError, and content stops updating.

onError doesn't accept false. To change how errors are handled, replace it with your own handler.

<SanityLive> from defineLive renders as a Server Component and passes your handlers to a Client Component. Define your handlers in a module marked with 'use client' so they run in the browser, then import them into your layout.

This example logs reconnects as warnings and, when the API closes the connection, refreshes the route once a minute instead of every 30 seconds:

'use client'

import type {SanityLiveOnGoaway, SanityLiveOnReconnect} from 'next-sanity/live'

export const onReconnect: SanityLiveOnReconnect = (_event, {includeDrafts}) => {
  console.warn(`<SanityLive${includeDrafts ? ' includeDrafts' : ''}> lost its connection and is reconnecting`)
}

export const onGoAway: SanityLiveOnGoaway = (event, _context, setPollingInterval) => {
  console.warn('Sanity Live connection closed:', event.reason)
  setPollingInterval(60_000)
}

import {SanityLive} from '@/sanity/lib/live'
import {onGoAway, onReconnect} from './sanity-live-handlers'

export default function RootLayout({children}: {children: React.ReactNode}) {
  return (
    <html lang="en">
      <body>
        {children}
        <SanityLive onReconnect={onReconnect} onGoAway={onGoAway} />
      </body>
    </html>
  )
}

Each handler receives the event and a context object. The context has includeDrafts and waitFor, which describe the current connection. Import the handler types from next-sanity/live:

• onWelcome: SanityLiveOnWelcome.
• onReconnect: SanityLiveOnReconnect.
• onRestart: SanityLiveOnRestart. Return 'refresh' from your handler to also refresh the route. Passing the string 'refresh' instead of a function is the default behavior.
• onGoAway: SanityLiveOnGoaway. Receives a third argument, setPollingInterval(ms), which refreshes the route on that interval. If your handler doesn't call it, content stops updating after the connection closes.
• onError: SanityLiveOnError. Receives the error and the context. Pass the string 'throw' instead of a function to throw the error during render, so the nearest error boundary handles it.

• Add live content to your application: set up defineLive and <SanityLive>.
• Sanity Live with Next.js Cache Components: configure <SanityLive> for cacheComponents: true.
• Live Content API: how the event stream works.