rivetkit-client-react_skill

Overview

This skill provides practical guidance for using RivetKit in React apps to connect to Rivet Actors with @rivetkit/react. It explains how to create hooks with createRivetKit, manage realtime actor state with useActor, and combine client calls for server or stateless use. Content focuses on concrete examples, connection parameters, event subscriptions, and error handling patterns.

How this skill works

createRivetKit builds typed React hooks wired to a Rivet client instance. useActor returns connection state, a live connection object for calling actor actions, and helpers for subscribing to actor events and lifecycle errors. For one-off or server calls, the plain JavaScript client (createClient) offers HTTP and WebSocket access and actor handle management (get/getOrCreate/getForId).

When to use it

• Building interactive React components that need realtime actor state and actions.
• Subscribing to actor events inside components (messages, broadcasts).
• Making one-off or server-side actor calls with createClient (SSR, backend jobs).
• Passing connection parameters like auth tokens per actor instance.
• Managing actor lifecycle and handling connection errors in UI.

Best practices

• Use createRivetKit at app root to provide typed hooks and environment config.
• Identify actors with array keys (compound keys) instead of interpolated strings to avoid key injection.
• Prefer useActor for realtime UI and createClient for stateless or backend calls.
• Pass auth or custom params via the params option on useActor instead of embedding credentials in the UI.
• Handle ActorError explicitly to inspect error.code and metadata for user-friendly messages.

Example use cases

• Realtime counter button that calls connection.increment(1) after useActor connects.
• Chat room component subscribing to "message" events via chat.useEvent to append messages to state.
• Server-side job that uses createClient to getOrCreate an actor and call actions without a WebSocket.
• Protected room connection that supplies an authToken in params when calling useActor.
• Fetching actor history with handle.fetch("history") and low-level WebSocket streaming with handle.webSocket("stream").