Quickstart

Next.js Quickstart

Get started with Rivet Actors in Next.js

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);

src/app/api/rivet/[...all]/route.ts

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>
	);
}

src/components/Counter.tsx

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

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

src/app/page.tsx

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.