114 lines
2.9 KiB
Markdown
114 lines
2.9 KiB
Markdown
---
|
|
name: "rivetkit-client-react"
|
|
description: "RivetKit React client guidance. Use for React apps that connect to Rivet Actors with @rivetkit/react, create hooks with createRivetKit, or manage realtime state with useActor."
|
|
---
|
|
|
|
# RivetKit React Client
|
|
|
|
Use this skill when building React apps that connect to Rivet Actors with `@rivetkit/react`.
|
|
|
|
## First Steps
|
|
|
|
1. Install the React client (latest: 2.3.4)
|
|
```bash
|
|
npm install @rivetkit/react@2.3.4
|
|
```
|
|
2. Create hooks with `createRivetKit()` and connect with `useActor()`.
|
|
|
|
## Error Handling Policy
|
|
|
|
- Prefer fail-fast behavior by default.
|
|
- Avoid `try/catch` unless absolutely needed.
|
|
- If a `catch` is used, handle the error explicitly, at minimum by logging it.
|
|
|
|
## Getting Started
|
|
|
|
See the [React quickstart guide](/docs/actors/quickstart/react) for getting started.
|
|
|
|
## Install
|
|
|
|
## Minimal Client
|
|
|
|
## Stateless vs Stateful
|
|
|
|
## Getting Actors
|
|
|
|
## Connection Parameters
|
|
|
|
## Subscribing to Events
|
|
|
|
## Connection Lifecycle
|
|
|
|
## Low-Level HTTP & WebSocket
|
|
|
|
Use the JavaScript client for raw HTTP and WebSocket access:
|
|
|
|
```tsx @nocheck
|
|
import { createClient } from "rivetkit/client";
|
|
|
|
const client = createClient();
|
|
const handle = client.chatRoom.getOrCreate(["general"]);
|
|
|
|
const response = await handle.fetch("history");
|
|
const history = await response.json();
|
|
|
|
const ws = await handle.webSocket("stream");
|
|
ws.addEventListener("message", (event) => {
|
|
console.log("message:", event.data);
|
|
});
|
|
ws.send("hello");
|
|
```
|
|
|
|
## Calling from Backend
|
|
|
|
Use the JavaScript client on your backend (Node.js/Bun). See the [JavaScript client docs](/docs/clients/javascript).
|
|
|
|
## Error Handling
|
|
|
|
## Concepts
|
|
|
|
### Keys
|
|
|
|
Keys uniquely identify actor instances. Use compound keys (arrays) for hierarchical addressing:
|
|
|
|
Don't build keys with string interpolation like `"org:${userId}"` when `userId` contains user data. Use arrays instead to prevent key injection attacks.
|
|
|
|
### Environment Variables
|
|
|
|
`createRivetKit()` (and the underlying `createClient()` instance) automatically read:
|
|
|
|
- `RIVET_ENDPOINT`
|
|
- `RIVET_NAMESPACE`
|
|
- `RIVET_TOKEN`
|
|
- `RIVET_RUNNER`
|
|
|
|
Defaults to `http://localhost:6420` when unset. RivetKit runs on port 6420 by default.
|
|
|
|
### Endpoint Format
|
|
|
|
Endpoints support URL auth syntax:
|
|
|
|
```
|
|
https://namespace:token@api.rivet.dev
|
|
```
|
|
|
|
You can also pass the endpoint without auth and provide `RIVET_NAMESPACE` and `RIVET_TOKEN` separately. For serverless deployments, use your app's `/api/rivet` URL. See [Endpoints](/docs/general/endpoints#url-auth-syntax) for details.
|
|
|
|
## API Reference
|
|
|
|
**Package:** [@rivetkit/react](https://www.npmjs.com/package/@rivetkit/react)
|
|
|
|
- [`createRivetKit`](/docs/clients/react) - Create hooks for React
|
|
- [`useActor`](/docs/clients/react) - Hook for actor instances
|
|
|
|
## Need More Than the Client?
|
|
|
|
If you need more about Rivet Actors, registries, or server-side RivetKit, add the main skill:
|
|
|
|
```bash
|
|
npx skills add rivet-dev/skills
|
|
```
|
|
|
|
Then use the `rivetkit` skill for backend guidance.
|
|
|