Quickstart

Next.js Quickstart

Get started with Rivet Actors in Next.js

Add Rivet Skill to Coding Agent (Optional)

If you’re using an AI coding assistant (like Claude Code, Cursor, Windsurf, etc.), add Rivet skills for enhanced development assistance:

npx skills add rivet-dev/skills

Command Line

Create a Next.js App

npx create-next-app@latest my-app
cd my-app

Command Line

Install RivetKit

npm install rivetkit @rivetkit/next-js

npm

pnpm add rivetkit @rivetkit/next-js

pnpm

yarn add rivetkit @rivetkit/next-js

yarn

bun add rivetkit @rivetkit/next-js

bun

Create an Actor

Create a file at src/rivet/registry.ts with a simple counter actor:

import { actor, setup } from "rivetkit";

export const counter = actor({
	state: { count: 0 },
	actions: {
		increment: (c, x: number) => {
			c.state.count += x;
			c.broadcast("newCount", c.state.count);
			return c.state.count;
		},
	},
});

export const registry = setup({
	use: { counter },
});

src/rivet/registry.ts

Setup Rivet API route

Create a file at src/app/api/rivet/[...all]/route.ts to setup the API routes:

import { toNextHandler } from "@rivetkit/next-js";
import { registry } from "@/rivet/registry";

export const maxDuration = 300;

export const { GET, POST, PUT, PATCH, HEAD, OPTIONS } = toNextHandler(registry);

TypeScript

Use the Actor in a component

Create a Counter component and add it to your page:

"use client";

import { createRivetKit } from "@rivetkit/next-js/client";
import type { registry } from "@/rivet/registry";
import { useState } from "react";

export const { useActor } = createRivetKit<typeof registry>(
	process.env.NEXT_RIVET_ENDPOINT ?? "http://localhost:3000/api/rivet",
);

export function Counter() {
	const [count, setCount] = useState(0);

	// Get or create a counter actor for the key "my-counter"
	const counter = useActor({
		name: "counter",
		key: ["my-counter"]
	});

	// Listen to realtime events
	counter.useEvent("newCount", (x: number) => setCount(x));

	const increment = async () => {
		// Call actions
		await counter.connection?.increment(1);
	};

	return (
		<div>
			<p>Count: {count}</p>
			<button onClick={increment}>Increment</button>
		</div>
	);
}

import { Counter } from "@/components/Counter";

export default function Home() {
	return (
		<main>
			<h1>My App</h1>
			<Counter />
		</main>
	);
}

For information about the Next.js client API, see the React Client API Reference.

Deploy to Vercel

See the Vercel deployment guide for detailed instructions on deploying your Rivet app to Vercel.