website/src/content/posts/2025-07-01-introducing-rivetkit-backend-libraries-that-replace-saas/page.mdx
import oldway from "./oldway.png"; import newway from "./newway.png";
Every API call to a cloud provider is a dependency you can't control.
When we built Rivet Actors – an open-source alternative to Cloudflare Durable Objects – we set out to provide a portable foundation for the novel "stateful serverless" architecture that is gaining traction. However, we felt that we weren't doing enough by just being an open-source alternative – we knew we needed to take a step further to make this ubiquitous.
That's why today, we're introducing RivetKit — a port of our core Rivet Actors service exposed as a portable TypeScript library that runs anywhere & can easily be added to your existing backend.
Instead of needing to sign up for a service or run a Docker container to run Rivet Actors, now it runs natively as a lightweight TypeScript library within your codebase & integrates with your existing infrastructure (e.g. Redis).
Our decision to launch RivetKit as a library was underpinned by the following constraints that we kept hearing developers voice:
As a library, RivetKit can run anywhere your infrastructure runs. Currently, RivetKit supports Redis, filesystem, Rivet Cloud, and Cloudflare Workers. Drivers for more platforms such as Postgres, Vercel, and more are trivial to add.
At its core, RivetKit provides Rivet Actors: long-running tasks with persistence & realtime. Rivet Actors provide a simple primitive that provides the same benefits that would usually require many other external services: RPC, realtime, persistence, and long-running tasks.
Rivet Actors excel at:
A simple Rivet actor that combines persistence & realtime looks like this:
import { actor } from "rivetkit";
const chatRoom = actor({
// FEATURE: Durable state
state: { messages: [] as Array<{text: string, userId: string}> },
// FEATURE: RPC
actions: {
sendMessage: (c, userId: string, text: string) => {
const message = { text, userId };
c.state.messages.push(message);
// FEATURE: Realtime
c.broadcast("newMessage", message);
return message;
},
getMessages: (c) => c.state.messages
}
});
And this can be called from your client of choice. For example, JavaScript:
const client = /* ... */;
// Connect to actor
const room = client.chatRoom.getOrCreate("random").connect();
// Listen for events
room.on("newMessage", () => /* ... */);
// RPC
await room.getMessages();
RivetKit is massive rearchitecture of its predecessor, ActorCore. In the process, ActorCore was rebuilt from the ground up to be a library instead of a framework.
Previously, ActorCore required running as a standalone framework. To setup your actors, you'd write:
import { actor, setup } from "actor-core";
const myActor = actor(/* ... */);
export const app = setup({ actors: { myActor } });
Then run the ActorCore framework with:
npx @actor-core/cli dev
Now, RivetKit is a lightweight library that can be integrated in to your existing backend like this:
import { actor, setup } from "rivetkit";
// Setup actors
const myActor = actor(/* ... */);
export const registry = setup({ use: { myActor } });
// NEW: Setup RivetKit server
const { client, serve } = registry.createServer();
// Your existing backend
const app = new Hono();
app.route("/foo", c => {
// NEW: Communicate with your actors
const res = client.myActor.getOrCreate().foo();
return c.text(res);
});
serve(app);
And run with vanilla Node.js:
npx tsx server.ts
Previously, ActorCore v0.8 required communicating over HTTP with your actors. To talk to actors from your backend, you needed to make a separate HTTP request to the actor manager server.
Now, RivetKit provides an "inline client" that can communicate with actors directly within your backend. For example:
import { registry } from "./registry";
import { Hono } from "hono";
// Start RivetKit with memory driver (for development)
const { client, serve } = registry.createServer();
// Setup Hono app
const app = new Hono();
// Example API endpoint
app.post("/increment/:name", async (c) => {
const name = c.req.param("name");
// Get or create actor and call action
const counter = client.counter.getOrCreate(name);
const newCount = await counter.increment(1);
return c.json({ count: newCount });
});
// Start server with RivetKit
serve(app);
The new onAuth lifecycle hook provides a way to handle authentication to actors based on intent.
onAuth runs on the edge server before reaching the actor itself – meaning it doesn't require any compute to run on the actor & is safe from denial of service attacks.
For example:
import { actor, Unauthorized } from "rivetkit";
const chatRoom = actor({
// NEW: Auth hook
onAuth: async (opts) => {
const { req, params, intents } = opts;
// Extract token from params or headers
const token = params.authToken || req.headers.get("Authorization");
if (!token) throw new Unauthorized();
// Validate token and return user data
const user = await validateJWT(token);
return {
userId: user.id,
role: user.role,
permissions: user.permissions
};
},
state: { messages: [] },
actions: {
sendMessage: (c, text: string) => {
// NEW: Access auth data via c.conn.auth
const { userId, role } = c.conn.auth;
if (role !== "member") {
throw new UserError("Insufficient permissions");
}
const message = {
id: crypto.randomUUID(),
userId,
text,
timestamp: Date.now(),
};
c.state.messages.push(message);
c.broadcast("newMessage", message);
return message;
}
}
})
See the authentication documentation for more details.
See the RivetKit + Better Auth integration.
Actors can now communicate with each other by using the client in the context. For example:
import { actor } from "rivetkit";
import type { registry } from "./registry";
export const orderProcessor = actor({
state: { orders: [] },
actions: {
processOrder: async (c, order: Order) => {
// NEW: Get the client
const client = c.client<typeof registry>();
// Call another actor to check inventory
const inventory = client.inventory.getOrCreate(order.productId);
const available = await inventory.reserveStock(order.quantity);
if (!available) throw new UserError("Insufficient stock");
// Process payment through payment actor
const payment = client.payment.getOrCreate(order.customerId);
const result = await payment.processPayment(order.amount);
// Update order state
c.state.orders.push({
...order,
status: "processed",
paymentId: result.paymentId,
});
return { success: true, orderId: order.id };
}
}
});
When using the React integration for Rivet Actors, calling useActor will share the same underlying WebSocket or SSE connection when communicating with actors & will automatically dispose of the connection when no longer in use.
This means you can call useActor liberally inside your components without complex connection handling logic.
Previously, ActorCore v0.8 used a system of key-value tags to organize actors. This turned to be overkill in practice and added unnecessary complexity under the hood.
This has been replaced with compound keys. Compound keys are either a simple string or an array of strings. The array of strings allows actor keys to inject user-provided strings without having to worry about injection attacks.
For example:
const chatThread = client.chatThread.getOrCreate([roomId, threadId]);
See the new actor handles documentation.
Initializing actors with custom state on what they're responsible for is a common pattern. For example, define an actor like this:
const game = actor({
actions: {
getRoomInfo: (c) => {
return `Room: ${opts.input.gameMode} with players ${opts.input.maxPlayers}`
},
},
// ...etc...
});
And create it like this:
// Create new actor
const newGame = await client.game.create(["game-456"], {
input: { gameMode: "classic", maxPlayers: 4 }
});
Read more about creating actors.
Actors now default to using HTTP connections unless explicitly calling .connect() to upgrade to a WebSocket or SSE connection. This allows for faster passing of messages without compromising on enabling high performance WebSocket- & SSE-based connections.
For example:
const counter = client.counter.getOrCreate("live-counter");
// NEW: Connect to the counter
const connection = counter.connect();
// Listen for events
connection.on("countChanged", (newCount: number) => {
console.log("Count updated:", newCount);
});
// Call actions through the connection
const result = await connection.increment(1);
// Clean up when done
await connection.dispose();
Read the new connections documentation.
Parameters & input data to actors are now end-to-end encrypted securely. Previously, they were passed as a query parameter which is frequently leaked in logs. Now, they're passed a secure header.
RivetKit now provides an OpenAPI spec to integrate your own clients. See the full openapi.json.
RivetKit will be a collection of powerful lightweight libraries directly into your codebase for better performance, control, and cost efficiency. No SaaS fees or API dependencies.
Ready to replace your SaaS dependencies with portable libraries? Get started with RivetKit today.