@surfjs/react

Name: Surf
Author: Surf

React SDK for Surf Live — real-time state sync hooks and components.

@surfjs/react

React SDK for Surf Live — connect your React app to a Surf WebSocket server and receive real-time state updates from AI agents.

Installation#

bash

npm install @surfjs/react

Peer dependencies: react ^18.0.0 || ^19.0.0

SurfProvider#

Wrap your app with SurfProvider to establish a WebSocket connection:

tsx

import { SurfProvider } from '@surfjs/react'
 
function App() {
  return (
    <SurfProvider
      url="wss://myapp.com/surf/ws"
      auth="your-auth-token"
      channels={['project-123']}
    >
      <MyComponent />
    </SurfProvider>
  )
}

Props

| Prop | Type | Description | |------|------|-------------| | url | string | WebSocket URL to connect to | | auth | string? | Auth token sent on connect | | channels | string[]? | Channels to subscribe to on connect |

Auto-Reconnect

The provider automatically reconnects with exponential backoff: 1s → 2s → 4s → 8s → max 30s.

Channel subscriptions are restored on reconnect.

useSurf#

Access the core Surf context — execute commands and check connection status:

tsx

import { useSurf } from '@surfjs/react'
 
function Controls() {
  const { execute, connected, status } = useSurf()
 
  const addClip = async () => {
    const result = await execute('video.addClip', { url: 'clip.mp4' })
    if (result.ok) console.log('Added:', result.result)
  }
 
  return (
    <button onClick={addClip} disabled={!connected}>
      Add Clip
    </button>
  )
}

Returns

| Property | Type | Description | |----------|------|-------------| | execute | (command, params?) => Promise<SurfResult> | Execute a Surf command | | connected | boolean | Whether WebSocket is connected | | status | ConnectionStatus | 'connecting' \| 'connected' \| 'disconnected' \| 'reconnecting' | | sessionId | string? | Current session ID |

useSurfEvent#

Subscribe to real-time events. Automatically cleans up on unmount:

tsx

import { useSurfEvent } from '@surfjs/react'
 
function Timeline() {
  const [clips, setClips] = useState([])
 
  useSurfEvent('timeline.updated', (data) => {
    setClips(data.clips)
  })
 
  return <ClipList clips={clips} />
}

useSurfState#

Synced state that auto-updates from Surf Live broadcast events:

tsx

import { useSurfState } from '@surfjs/react'
 
function Editor() {
  const [state, setState] = useSurfState('project-123', {
    timeline: { clips: [], playhead: 0 },
    selectedClip: null,
  })
 
  // `state` updates automatically when the server calls:
  // surf.live.setState('project-123', newState)
  // surf.live.patchState('project-123', partialUpdate)
 
  return (
    <div>
      <p>Playhead: {state.timeline.playhead}s</p>
      <p>Clips: {state.timeline.clips.length}</p>
    </div>
  )
}

useSurfState handles both full state updates (surf:state) and patches (surf:patch). It uses version numbers to prevent stale updates.

useSurfChannel#

Dynamically manage channel subscriptions:

tsx

import { useSurfChannel } from '@surfjs/react'
 
function ProjectSwitcher({ projectId }) {
  const { subscribe, unsubscribe, channels } = useSurfChannel()
 
  useEffect(() => {
    subscribe(projectId)
    return () => unsubscribe(projectId)
  }, [projectId])
 
  return <p>Subscribed to: {[...channels].join(', ')}</p>
}

Connection Status#

tsx

import { useSurf } from '@surfjs/react'
 
function StatusIndicator() {
  const { status } = useSurf()
 
  const colors = {
    connecting: 'yellow',
    connected: 'green',
    disconnected: 'red',
    reconnecting: 'orange',
  }
 
  return (
    <span style={{ color: colors[status] }}>
      {status}
    </span>
  )
}

TypeScript#

All hooks and components are fully typed. The SurfResult type:

typescript

interface SurfResult {
  ok: boolean
  result?: unknown
  error?: { code: string; message: string }
  state?: Record<string, unknown>
}

Edit this page on GitHub

PreviousEdge Runtime Next CLI