Merge branch 'rivet-gg:main' into main

Author: miapolis

README.md

@@ -1,57 +1,177 @@
+<!-- 
+THIS FILE IS AUTO-GENERATED. DO NOT EDIT DIRECTLY.
+To update this README, run: npm run gen:readme in the github.com/rivet-gg/rivet repository
+Generated from: github.com/rivet-gg/rivet/site/scripts/generateReadme.mjs
+-->
+
 <div align="center">
   <a href="https://rivetkit.org">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="./.github/media/logo/dark.svg" alt="RivetKit">
-      <img src="./.github/media/logo/light.svg" alt="RivetKit" width="400">
+      <img src="./.github/media/logo/light.svg" alt="RivetKit" height="75">
     </picture>
   </a>
   <br/>
   <br/>
-  <p><b>Lightweight Libraries for Backends</b></p>
+  <p><b>The open-source alternative to Durable Objects</b></p>
   <p>
-    Install one package, scale to production.<br/>
-    <u>Just a library, no SaaS.</u><br/>
+    RivetKit is a library for long-lived processes with durable state, realtime, and scalability.<br/>
+	Easily <u>self-hostable</u> and works <u>with your infrastructure</u>.
   </p>
   <p>
-    <i>
-      Supports <a href="https://rivetkit.org/drivers/rivet">Rivet</a>, <a href="https://rivetkit.org/drivers/cloudflare-workers">Cloudflare</a>, <a href="https://rivetkit.org/actors/quickstart-backend">Node</a>, <a href="https://rivetkit.org/actors/quickstart-backend">Bun</a>, <a href="https://rivetkit.org/drivers/redis">Redis</a>, <a href="https://rivetkit.org/drivers/memory">memory</a>, <a href="https://rivetkit.org/drivers/file-system">file system</a>, <a href="https://rivetkit.org/clients/javascript">TypeScript</a>,<br/>
-      Rust, <a href="https://rivetkit.org/clients/react">React</a>, <a href="https://rivetkit.org/integrations/hono">Hono</a>, <a href="https://rivetkit.org/integrations/express">Express</a>, <a href="https://rivetkit.org/integrations/elysia">Elysia</a>, <a href="https://rivetkit.org/integrations/trpc">tRPC</a>, <a href="https://rivetkit.org/integrations/better-auth">Better Auth</a>, and <a href="https://rivetkit.org/general/testing">Vitest</a>.
-    </i>
+    <a href="https://rivet.gg/docs/actors/quickstart">Quickstart</a> •
+    <a href="https://rivet.gg/docs/actors">Documentation</a> •
+    <a href="https://rivet.gg/docs/general/self-hosting">Self-Hosting</a> •
+    <a href="https://rivet.gg/discord">Discord</a> •
+    <a href="https://x.com/rivet_gg">X</a> •
+    <a href="https://bsky.app/profile/rivet.gg">Bluesky</a>
   </p>
   <p>
-    <a href="https://rivetkit.org/">Documentation</a> •
-    <a href="https://discord.gg/rivet">Discord</a> •
-    <a href="https://x.com/RivetKit_org">X</a> •
-    <a href="https://bsky.app/">Bluesky</a>
+    <i>
+      Supports <a href="https://rivetkit.org/actors/quickstart-backend">Node.js</a>, <a href="https://rivetkit.org/actors/quickstart-backend">Bun</a>, <a href="https://rivetkit.org/drivers/redis">Redis</a>, <a href="https://rivetkit.org/drivers/cloudflare-workers">Cloudflare</a>,<br/>
+      <a href="https://rivetkit.org/clients/react">React</a>, <a href="https://rivetkit.org/clients/rust">Rust</a>, <a href="https://rivetkit.org/integrations/hono">Hono</a>, <a href="https://rivetkit.org/integrations/express">Express</a>, <a href="https://rivetkit.org/integrations/trpc">tRPC</a>, and <a href="https://rivetkit.org/integrations/better-auth">Better Auth</a>.
+    </i>
   </p>
-
 </div>
 
-## Quickstart
+## Projects
 
-- <img src=".github/media/clients/javascript.svg" height="16" alt="Node.js" />&nbsp;&nbsp;[Node.js & Bun](https://rivetkit.org/actors/quickstart-backend)
-- <img src=".github/media/clients/react.svg" height="16" alt="React" />&nbsp;&nbsp;[React](https://rivetkit.org/actors/quickstart-react)
+Public-facing projects:
 
-## Examples
+- **RivetKit** (you are here): Lightweight TypeScript library for building Rivet Actors
+- **[Rivet Engine](https://github.com/rivet-gg/rivet)** : Engine that powers Rivet Actors at scale — completely optional
+- **[Rivet Studio](https://github.com/rivet-gg/rivet/tree/main/frontend/apps/studio)**: Like Postman, but for Rivet Actors
+- **[Rivet Documentation](https://github.com/rivet-gg/rivet/tree/main/site/src/content/docs)**
+
+## Get Started
+
+### Guides
+
+Get started with Rivet by following a quickstart guide:
+
+- [Node.js & Bun](https://www.rivet.gg/docs/actors/quickstart/backend/)
+- [React](https://www.rivet.gg/docs/actors/quickstart/react/)
+
+
+### Quickstart
+
+**Step 1**: Install RivetKit
+
+```sh
+npm install @rivetkit/actor
+```
+
+**Step 2**: Create an actor
+
+```typescript
+// registry.ts
+import { actor, setup } from "@rivetkit/actor";
+
+export const counter = actor({
+	state: { count: 0 },
+	actions: {
+		increment: (c, amount: number = 1) => {
+			// State changes are durable & automatically persisted
+			c.state.count += amount;
+			// Broadcast realtime events
+			c.broadcast("countChanged", c.state.count);
+			// Return data to client
+			return c.state.count;
+		},
+		getCount: (c) => c.state.count,
+	},
+});
+
+export const registry = setup({
+	use: { counter },
+});
+```
+
+Read more about [state](https://www.rivet.gg/docs/actors/state/), [actions](https://www.rivet.gg/docs/actors/actions/), and [events](https://www.rivet.gg/docs/actors/events/).
+
+**Step 2**: Setup server
+
+_Alternatively, see the [React](https://www.rivet.gg/docs/actors/quickstart/react/) guide which does not require a server._
+
+```typescript
+// server.ts
+import { registry } from "./registry";
+import { Hono } from "hono";
 
-Browse snippets for how to use RivetKit with different use cases.
+// Start with file system driver for development
+const { client, serve } = registry.createServer();
 
-| Example | Actor (JavaScript) | Actor (SQLite) | Frontend (React) |
-|---------|------------|--------|-------|
-| AI Agent | [actor.ts](/examples/snippets/ai-agent/actor-json.ts) | [actor.ts](/examples/snippets/ai-agent/actor-sqlite.ts) | [App.tsx](/examples/snippets/ai-agent/App.tsx) |
-| Collaborative Document (CRDT) | [actor.ts](/examples/snippets/crdt/actor-json.ts) | [actor.ts](/examples/snippets/crdt/actor-sqlite.ts) | [App.tsx](/examples/snippets/crdt/App.tsx) |
-| Chat Room | [actor.ts](/examples/snippets/chat-room/actor-json.ts) | [actor.ts](/examples/snippets/chat-room/actor-sqlite.ts) | [App.tsx](/examples/snippets/chat-room/App.tsx) |
-| Per-User Databases | [actor.ts](/examples/snippets/database/actor-json.ts) | [actor.ts](/examples/snippets/database/actor-sqlite.ts) | [App.tsx](/examples/snippets/database/App.tsx) |
-| Rate Limiter | [actor.ts](/examples/snippets/rate/actor-json.ts) | [actor.ts](/examples/snippets/rate/actor-sqlite.ts) | [App.tsx](/examples/snippets/rate/App.tsx) |
-| Stream Processing | [actor.ts](/examples/snippets/stream/actor-json.ts) | [actor.ts](/examples/snippets/stream/actor-sqlite.ts) | [App.tsx](/examples/snippets/stream/App.tsx) |
-| Multiplayer Game | [actor.ts](/examples/snippets/game/actor-json.ts) | [actor.ts](/examples/snippets/game/actor-sqlite.ts) | [App.tsx](/examples/snippets/game/App.tsx) |
-| Local-First Sync | [actor.ts](/examples/snippets/sync/actor-json.ts) | [actor.ts](/examples/snippets/sync/actor-sqlite.ts) | [App.tsx](/examples/snippets/sync/App.tsx) |
+// Setup your server
+const app = new Hono();
 
-_SQLite available in July._
+app.post("/increment/:name", async (c) => {
+	const name = c.req.param("name");
 
-## Runs On Your Stack
+	// Get or create actor with key `name`
+	const counter = client.counter.getOrCreate(name);
 
-Deploy RivetKit anywhere - from serverless platforms to your own infrastructure. Don't see the runtime you want? [Add your own](https://rivetkit.org/drivers/build).
+	// Call an action
+	const newCount = await counter.increment(1);
+
+	return c.json({ count: newCount });
+});
+
+// Start server with Rivet
+serve(app);
+```
+
+Start the server with:
+
+```typescript
+npx tsx server.ts
+// or
+bun server.ts
+```
+
+Read more about [clients](https://www.rivet.gg/docs/actors/clients/).
+
+You can connect to your server with:
+
+```typescript
+// client.ts
+const response = await fetch("http://localhost:8080/increment/my-counter", { method: "POST" });
+const result = await response.json();
+console.log("Count:", result.count); // 1
+```
+
+**Step 3**: Deploy
+
+To scale Rivet in production, follow a guide to deploy to a hosting provider or integrate a driver:
+
+- [Redis](https://www.rivet.gg/docs/drivers/redis/)
+- [Cloudflare Workers](https://www.rivet.gg/docs/hosting-providers/cloudflare-workers/)
+
+## Features
+
+RivetKit provides everything you need to build fast, scalable, and real-time applications without the complexity.
+
+- **Long-Lived, Stateful Compute**: Like AWS Lambda but with memory and no timeouts
+- **Blazing-Fast Reads & Writes**: State stored on same machine as compute  
+- **Realtime, Made Simple**: Built-in WebSockets and SSE support
+- **Store Data Near Your Users**: Deploy to the edge for low-latency access
+- **Infinitely Scalable**: Auto-scale from zero to millions without configuration
+- **Fault Tolerant**: Automatic error handling and recovery built-in
+
+## Examples
+
+- AI Agent — [GitHub](https://github.com/rivet-gg/rivetkit/tree/main/examples/ai-agent) · [StackBlitz](https://stackblitz.com/github/rivet-gg/rivetkit/tree/main/examples/ai-agent)
+- Chat Room — [GitHub](https://github.com/rivet-gg/rivetkit/tree/main/examples/chat-room) · [StackBlitz](https://stackblitz.com/github/rivet-gg/rivetkit/tree/main/examples/chat-room)
+- Collab (Yjs) — [GitHub](https://github.com/rivet-gg/rivetkit/tree/main/examples/crdt) · [StackBlitz](https://stackblitz.com/github/rivet-gg/rivetkit/tree/main/examples/crdt)
+- Multiplayer Game — [GitHub](https://github.com/rivet-gg/rivetkit/tree/main/examples/game) · [StackBlitz](https://stackblitz.com/github/rivet-gg/rivetkit/tree/main/examples/game)
+- Local-First Sync — [GitHub](https://github.com/rivet-gg/rivetkit/tree/main/examples/sync) · [StackBlitz](https://stackblitz.com/github/rivet-gg/rivetkit/tree/main/examples/sync)
+- Rate Limiter — [GitHub](https://github.com/rivet-gg/rivetkit/tree/main/examples/rate) · [StackBlitz](https://stackblitz.com/github/rivet-gg/rivetkit/tree/main/examples/rate)
+- Per-User DB — [GitHub](https://github.com/rivet-gg/rivetkit/tree/main/examples/database) · [StackBlitz](https://stackblitz.com/github/rivet-gg/rivetkit/tree/main/examples/database)
+- Multi-Tenant SaaS — [GitHub](https://github.com/rivet-gg/rivetkit/tree/main/examples/tenant) · [StackBlitz](https://stackblitz.com/github/rivet-gg/rivetkit/tree/main/examples/tenant)
+- Stream Processing — [GitHub](https://github.com/rivet-gg/rivetkit/tree/main/examples/stream) · [StackBlitz](https://stackblitz.com/github/rivet-gg/rivetkit/tree/main/examples/stream)
+
+## Runs Anywhere
+
+Deploy RivetKit anywhere - from serverless platforms to your own infrastructure with RivetKit's flexible runtime options. Don't see the runtime you want? [Add your own](https://rivetkit.org/drivers/build).
 
 ### All-In-One
 - <img src=".github/media/platforms/rivet-white.svg" height="16" alt="Rivet" />&nbsp;&nbsp;[Rivet](https://rivetkit.org/drivers/rivet)
@@ -97,19 +217,32 @@ Seamlessly integrate RivetKit with your favorite frameworks, languages, and tool
 - <img src=".github/media/integrations/tinybase.svg" height="16" alt="TinyBase" />&nbsp;&nbsp;[TinyBase](https://github.com/rivet-gg/rivetkit/issues/910) *(Help Wanted)*
 - <img src=".github/media/integrations/yjs.svg" height="16" alt="Yjs" />&nbsp;&nbsp;[Yjs](https://github.com/rivet-gg/rivetkit/issues/911) *(Help Wanted)*
 
-## Join the Community
+## Local Development with the Studio
+
+Rivet Studio is like like Postman, but for all of your stateful serverless needs:
+
+- **Live State Inspection**: View and edit your actor state in real-time as messages are sent and processed
+- **REPL**: Debug your actor in real-time - call actions, subscribe to events, and interact directly with your code
+- **Connection Inspection**: Monitor active connections with state and parameters for each client
+- **Hot Reload Code Changes**: See code changes instantly without restarting - modify and test on the fly
+
+[Visit the Studio →](https://studio.rivet.gg)
+
+![Rivet Studio](.github/media/screenshots/studio/simple.png)
+
+## Community & Support
 
-Help make RivetKit the universal way to build & scale stateful serverless applications.
+Join thousands of developers building with RivetKit today:
 
-- [Discord](https://rivet.gg/discord)
-- [X](https://x.com/RivetKit_org)
-- [Bluesky](https://bsky.app/profile/rivet.gg)
-- [Discussions](https://github.com/rivet-gg/rivetkit/discussions)
-- [Issues](https://github.com/rivet-gg/rivetkit/issues)
+- [Discord](https://rivet.gg/discord) - Chat with the community
+- [X/Twitter](https://x.com/rivet_gg) - Follow for updates
+- [Bluesky](https://bsky.app/profile/rivet.gg) - Follow for updates
+- [GitHub Discussions](https://github.com/rivet-gg/rivetkit/discussions) - Ask questions and share ideas
+- [GitHub Issues](https://github.com/rivet-gg/rivetkit/issues) - Report bugs and request features
+- [Talk to an engineer](https://rivet.gg/talk-to-an-engineer) - Discuss your technical needs, current stack, and how Rivet can help with your infrastructure challenges
 
 ## License
 
-Apache 2.0
+[Apache 2.0](LICENSE)
 
-_Performance in every act - thanks to Rivet Actors._
 

clients/openapi/openapi.json

@@ -1,7 +1,7 @@
 {
   "openapi": "3.0.0",
   "info": {
-    "version": "0.9.3",
+    "version": "0.9.5",
     "title": "RivetKit API"
   },
   "components": {

examples/ai-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-ai-agent",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "private": true,
   "type": "module",
   "scripts": {

examples/better-auth-external-db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-better-auth-external-db",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "private": true,
   "type": "module",
   "scripts": {

examples/chat-room/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chat-room",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "private": true,
   "type": "module",
   "scripts": {

examples/cloudflare-workers-hono/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-cloudflare-workers-hono",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "private": true,
   "type": "module",
   "scripts": {

examples/cloudflare-workers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-cloudflare-workers",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "private": true,
   "type": "module",
   "scripts": {

examples/counter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counter",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "private": true,
   "type": "module",
   "scripts": {
@@ -9,8 +9,8 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "^22.13.9",
     "@rivetkit/actor": "workspace:*",
+    "@types/node": "^22.13.9",
     "tsx": "^3.12.7",
     "typescript": "^5.7.3",
     "vitest": "^3.1.1"

examples/counter/scripts/connect.ts

@@ -1,13 +1,12 @@
-/// <reference types="node" />
 import { createClient } from "@rivetkit/actor/client";
-import type { Registry } from "../src/actors/registry";
+import type { Registry } from "../src/registry";
 
 async function main() {
 	const client = createClient<Registry>(
 		process.env.ENDPOINT ?? "http://127.0.0.1:8080",
 	);
 
-	const counter = (await client.counter.getOrCreate()).connect();
+	const counter = await client.counter.getOrCreate().connect();
 
 	counter.on("newCount", (count: number) => console.log("Event:", count));
 
@@ -18,6 +17,7 @@ async function main() {
 		await new Promise((resolve) => setTimeout(resolve, 1000));
 	}
 
+	await new Promise((resolve) => setTimeout(resolve, 10000));
 	await counter.dispose();
 }
 

examples/counter/src/registry.ts

@@ -1,7 +1,12 @@
 import { actor, setup } from "@rivetkit/actor";
 
 const counter = actor({
-	state: { count: 0 },
+	state: {
+		count: 0,
+	},
+	onAuth: () => {
+		return true;
+	},
 	actions: {
 		increment: (c, x: number) => {
 			c.state.count += x;
@@ -17,3 +22,5 @@ const counter = actor({
 export const registry = setup({
 	use: { counter },
 });
+
+export type Registry = typeof registry;