feat(next-js): add support for next.js (#1152)

Closes KIT-178, KIT-115

### TL;DR

Add Next.js framework support with a working example and update documentation links.

### What changed?

- Added a new `@rivetkit/next-js` package with Next.js integration
- Created a complete Next.js example application in `examples/next-js`
- Updated the GitHub workflow to include templates from examples directory
- Fixed the basePath handling in the core router to support custom API paths
- Updated documentation links throughout the README to point to rivet.gg domain
- Added a pkg.pr.new badge to the README for easy testing

### How to test?

1. Run the Next.js example:
```bash
cd examples/next-js
pnpm install
pnpm dev
```

2. Open http://localhost:3000 to see the counter example
3. Try incrementing the counter and changing the counter name
4. Verify the API routes work correctly at `/api/registry`

### Why make this change?

Next.js is one of the most popular React frameworks, and this integration allows RivetKit to be easily used in Next.js applications. The example demonstrates how to set up actors, create API routes, and use the React hooks in a Next.js environment. This expands RivetKit's framework support and makes it more accessible to developers using Next.js.

Author: jog1t

.github/workflows/pkg-pr-new.yaml

@@ -10,4 +10,4 @@ jobs:
       - uses: actions/setup-node@v4
       - run: pnpm install
       - run: pnpm build
-      - run: pnpm dlx pkg-pr-new publish 'packages/*' 'packages/**/platforms/*' 'packages/frameworks/*' 'packages/drivers/*' --packageManager pnpm
+      - run: pnpm dlx pkg-pr-new publish 'packages/*' 'packages/**/platforms/*' 'packages/frameworks/*' 'packages/drivers/*' --packageManager pnpm --template './examples/*'

README.md

@@ -28,10 +28,15 @@ Generated from: github.com/rivet-gg/rivet/site/scripts/generateReadme.mjs
   </p>
   <p>
     <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>.
+      Supports <a href="https://rivet.gg/docs/actors/quickstart/backend/">Node.js</a>, <a href="https://rivet.gg/docs/actors/quickstart/backend/">Bun</a>, <a href="https://rivet.gg/docs/drivers/redis/">Redis</a>, <a href="https://rivet.gg/docs/hosting-providers/cloudflare-workers/">Cloudflare</a>,<br/>
+      <a href="https://rivet.gg/docs/clients/react/">React</a>, <a href="https://rivet.gg/docs/clients/rust/">Rust</a>, <a href="https://rivet.gg/docs/integrations/hono/">Hono</a>, <a href="https://rivet.gg/docs/integrations/express/">Express</a>, <a href="https://rivet.gg/docs/integrations/trpc/">tRPC</a>, and <a href="https://rivet.gg/docs/integrations/better-auth/">Better Auth</a>.
     </i>
   </p>
+  <p>
+   <a href="https://pkg.pr.new/~/rivet-gg/rivetkit">
+      <img src="https://pkg.pr.new/badge/rivet-gg/rivetkit" alt="RivetKit on pkg.pr.new" />
+    </a>
+  </p>
 </div>
 
 ## Projects
@@ -87,11 +92,11 @@ export const registry = setup({
 });
 ```
 
-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/).
+Read more about [state](https://rivet.gg/docs/actors/state/), [actions](https://rivet.gg/docs/actors/actions/), and [events](https://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._
+_Alternatively, see the [React](https://rivet.gg/docs/actors/quickstart/react/) guide which does not require a server._
 
 ```typescript
 // server.ts
@@ -110,7 +115,7 @@ app.post("/increment/:name", async (c) => {
 	// Get or create actor with key `name`
 	const counter = client.counter.getOrCreate(name);
 
-	// Call an action
+	// Call an action (with full type safety)
 	const newCount = await counter.increment(1);
 
 	return c.json({ count: newCount });
@@ -128,7 +133,7 @@ npx tsx server.ts
 bun server.ts
 ```
 
-Read more about [clients](https://www.rivet.gg/docs/actors/clients/).
+Read more about [clients](https://rivet.gg/docs/actors/clients/).
 
 You can connect to your server with:
 
@@ -143,8 +148,8 @@ console.log("Count:", result.count); // 1
 
 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/)
+- [Redis](https://rivet.gg/docs/drivers/redis/)
+- [Cloudflare Workers](https://rivet.gg/docs/hosting-providers/cloudflare-workers/)
 
 ## Features
 
@@ -171,63 +176,61 @@ RivetKit provides everything you need to build fast, scalable, and real-time app
 
 ## 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).
+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://rivet.gg/docs/drivers/build-your-own/).
 
 ### All-In-One
-- <img src=".github/media/platforms/rivet-white.svg" height="16" alt="Rivet" />&nbsp;&nbsp;[Rivet](https://rivetkit.org/drivers/rivet)
-- <img src=".github/media/platforms/cloudflare-workers.svg" height="16" alt="Cloudflare Workers" />&nbsp;&nbsp;[Cloudflare Workers](https://rivetkit.org/drivers/cloudflare-workers)
+- <img src=".github/media/platforms/rivet-white.svg" height="16" alt="Rivet" />&nbsp;&nbsp;[Rivet](https://rivet.gg/docs/hosting-providers/rivet-cloud/)
+- <img src=".github/media/platforms/cloudflare-workers.svg" height="16" alt="Cloudflare Workers" />&nbsp;&nbsp;[Cloudflare Workers](https://rivet.gg/docs/hosting-providers/cloudflare-workers/)
 
 ### Compute
 - <img src=".github/media/platforms/vercel.svg" height="16" alt="Vercel" />&nbsp;&nbsp;[Vercel](https://github.com/rivet-gg/rivetkit/issues/897) *(On The Roadmap)*
 - <img src=".github/media/platforms/aws-lambda.svg" height="16" alt="AWS Lambda" />&nbsp;&nbsp;[AWS Lambda](https://github.com/rivet-gg/rivetkit/issues/898) *(On The Roadmap)*
 - <img src=".github/media/platforms/supabase.svg" height="16" alt="Supabase" />&nbsp;&nbsp;[Supabase](https://github.com/rivet-gg/rivetkit/issues/905) *(Help Wanted)*
-- <img src=".github/media/platforms/bun.svg" height="16" alt="Bun" />&nbsp;&nbsp;[Bun](https://rivetkit.org/actors/quickstart-backend)
-- <img src=".github/media/platforms/nodejs.svg" height="16" alt="Node.js" />&nbsp;&nbsp;[Node.js](https://rivetkit.org/actors/quickstart-backend)
+- <img src=".github/media/platforms/bun.svg" height="16" alt="Bun" />&nbsp;&nbsp;[Bun](https://rivet.gg/docs/actors/quickstart/backend/)
+- <img src=".github/media/platforms/nodejs.svg" height="16" alt="Node.js" />&nbsp;&nbsp;[Node.js](https://rivet.gg/docs/actors/quickstart/backend/)
 
 ### Storage
-- <img src=".github/media/platforms/redis.svg" height="16" alt="Redis" />&nbsp;&nbsp;[Redis](https://rivetkit.org/drivers/redis)
+- <img src=".github/media/platforms/redis.svg" height="16" alt="Redis" />&nbsp;&nbsp;[Redis](https://rivet.gg/docs/drivers/redis/)
 - <img src=".github/media/platforms/postgres.svg" height="16" alt="Postgres" />&nbsp;&nbsp;[Postgres](https://github.com/rivet-gg/rivetkit/issues/899) *(Help Wanted)*
-- <img src=".github/media/platforms/file-system.svg" height="16" alt="File System" />&nbsp;&nbsp;[File System](https://rivetkit.org/drivers/file-system)
-- <img src=".github/media/platforms/memory.svg" height="16" alt="Memory" />&nbsp;&nbsp;[Memory](https://rivetkit.org/drivers/memory)
+- <img src=".github/media/platforms/file-system.svg" height="16" alt="File System" />&nbsp;&nbsp;[File System](https://rivet.gg/docs/drivers/file-system/)
+- <img src=".github/media/platforms/memory.svg" height="16" alt="Memory" />&nbsp;&nbsp;[Memory](https://rivet.gg/docs/drivers/memory/)
 
 ## Works With Your Tools
 
 Seamlessly integrate RivetKit with your favorite frameworks, languages, and tools. Don't see what you need? [Request an integration](https://github.com/rivet-gg/rivetkit/issues/new).
 
 ### Frameworks
-- <img src=".github/media/clients/react.svg" height="16" alt="React" />&nbsp;&nbsp;[React](https://rivetkit.org/clients/react)
-- <img src=".github/media/clients/nextjs.svg" height="16" alt="Next.js" />&nbsp;&nbsp;[Next.js](https://github.com/rivet-gg/rivetkit/issues/904) *(Help Wanted)*
+- <img src=".github/media/clients/react.svg" height="16" alt="React" />&nbsp;&nbsp;[React](https://rivet.gg/docs/clients/react/)
+- <img src=".github/media/clients/nextjs.svg" height="16" alt="Next.js" />&nbsp;&nbsp;[Next.js](https://rivet.gg/docs/clients/nextjs/)
 - <img src=".github/media/clients/vue.svg" height="16" alt="Vue" />&nbsp;&nbsp;[Vue](https://github.com/rivet-gg/rivetkit/issues/903) *(Help Wanted)*
 
 ### Clients
-- <img src=".github/media/clients/javascript.svg" height="16" alt="JavaScript" />&nbsp;&nbsp;[JavaScript](https://rivetkit.org/clients/javascript)
-- <img src=".github/media/clients/typescript.svg" height="16" alt="TypeScript" />&nbsp;&nbsp;[TypeScript](https://rivetkit.org/clients/javascript)
+- <img src=".github/media/clients/javascript.svg" height="16" alt="JavaScript" />&nbsp;&nbsp;[JavaScript](https://rivet.gg/docs/clients/javascript/)
+- <img src=".github/media/clients/typescript.svg" height="16" alt="TypeScript" />&nbsp;&nbsp;[TypeScript](https://rivet.gg/docs/clients/javascript/)
 - <img src=".github/media/clients/python.svg" height="16" alt="Python" />&nbsp;&nbsp;[Python](https://github.com/rivet-gg/rivetkit/issues/902) *(Help Wanted)*
-- <img src=".github/media/clients/rust.svg" height="16" alt="Rust" />&nbsp;&nbsp;[Rust](https://github.com/rivet-gg/rivetkit/issues/901) *(Help Wanted)*
+- <img src=".github/media/clients/rust.svg" height="16" alt="Rust" />&nbsp;&nbsp;[Rust](https://rivet.gg/docs/clients/rust/)
 
 ### Integrations
-- <img src=".github/media/integrations/hono.svg" height="16" alt="Hono" />&nbsp;&nbsp;[Hono](https://rivetkit.org/integrations/hono)
-- <img src=".github/media/integrations/vitest.svg" height="16" alt="Vitest" />&nbsp;&nbsp;[Vitest](https://rivetkit.org/general/testing)
-- <img src=".github/media/integrations/better-auth.svg" height="16" alt="Better Auth" />&nbsp;&nbsp;[Better Auth](https://rivetkit.org/integrations/better-auth)
+- <img src=".github/media/integrations/hono.svg" height="16" alt="Hono" />&nbsp;&nbsp;[Hono](https://rivet.gg/docs/integrations/hono/)
+- <img src=".github/media/integrations/vitest.svg" height="16" alt="Vitest" />&nbsp;&nbsp;[Vitest](https://rivet.gg/docs/integrations/vitest/)
+- <img src=".github/media/integrations/better-auth.svg" height="16" alt="Better Auth" />&nbsp;&nbsp;[Better Auth](https://rivet.gg/docs/integrations/better-auth/)
 - <img src=".github/media/platforms/vercel.svg" height="16" alt="AI SDK" />&nbsp;&nbsp;[AI SDK](https://github.com/rivet-gg/rivetkit/issues/907) *(On The Roadmap)*
 
 ### Local-First Sync
-- <img src=".github/media/integrations/livestore.svg" height="16" alt="LiveStore" />&nbsp;&nbsp;[LiveStore](https://github.com/rivet-gg/rivetkit/issues/908) *(Available In July)*
+- <img src=".github/media/integrations/livestore.svg" height="16" alt="LiveStore" />&nbsp;&nbsp;[LiveStore](https://github.com/rivet-gg/rivetkit/issues/908) *(Available In August)*
 - <img src=".github/media/integrations/zerosync.svg" height="16" alt="ZeroSync" />&nbsp;&nbsp;[ZeroSync](https://github.com/rivet-gg/rivetkit/issues/909) *(Help Wanted)*
 - <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)*
 
 ## Local Development with the Studio
 
-Rivet Studio is like like Postman, but for all of your stateful serverless needs:
+Rivet Studio is like like Postman, but for all of your stateful serverless needs. [Visit the Studio →](https://studio.rivet.gg)
 
 - **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

examples/next-js/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

examples/next-js/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

examples/next-js/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+	/* config options here */
+};
+
+export default nextConfig;

examples/next-js/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "example-next-js",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "next": "15.4.5",
+    "@rivetkit/next-js": "workspace:*",
+    "@rivetkit/actor": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19"
+  }
+}

examples/next-js/src/app/api/registry/[...all]/route.ts

@@ -0,0 +1,15 @@
+import { toNextHandler } from "@rivetkit/next-js";
+import { registry } from "@/rivet/registry";
+
+const server = registry.createServer({
+	// This is important for Next.js to route the API calls correctly
+	// It should match the path in your Next.js API route
+	// For example, if your API route is at /api/registry/[...all], this should be "/api/registry"
+	basePath: "/api/registry",
+	studio: {
+		// Tell RivetKit Studio where to find RivetKit Registry
+		defaultEndpoint: "http://localhost:3000/api/registry",
+	},
+});
+
+export const { GET, POST, HEAD, PATCH, OPTIONS } = toNextHandler(server);

examples/next-js/src/app/favicon.ico

@@ -0,0 +1,42 @@
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+  }
+}
+
+html,
+body {
+  max-width: 100vw;
+  overflow-x: hidden;
+}
+
+body {
+  color: var(--foreground);
+  background: var(--background);
+  font-family: Arial, Helvetica, sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+* {
+  box-sizing: border-box;
+  padding: 0;
+  margin: 0;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+@media (prefers-color-scheme: dark) {
+  html {
+    color-scheme: dark;
+  }
+}

examples/next-js/src/app/globals.css

@@ -0,0 +1,32 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+
+const geistSans = Geist({
+	variable: "--font-geist-sans",
+	subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+	variable: "--font-geist-mono",
+	subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+	title: "Create Next App",
+	description: "Generated by create next app",
+};
+
+export default function RootLayout({
+	children,
+}: Readonly<{
+	children: React.ReactNode;
+}>) {
+	return (
+		<html lang="en">
+			<body className={`${geistSans.variable} ${geistMono.variable}`}>
+				{children}
+			</body>
+		</html>
+	);
+}