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

jog1t · 2025-07-31T23:19:47Z

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?

Run the Next.js example:

cd examples/next-js
pnpm install
pnpm dev

Open http://localhost:3000 to see the counter example
Try incrementing the counter and changing the counter name
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.

claude · 2025-07-31T23:19:59Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

jog1t · 2025-07-31T23:20:05Z

feat(next-js): add support for next.js #1152 👈 (View in Graphite)
main

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

merge queue - adds this PR to the back of the merge queue
hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

_{An organization admin has enabled the Graphite Merge Queue in this repository.} _{Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.}

This stack of pull requests is managed by Graphite. Learn more about stacking.

packages/core/src/manager/router.ts

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

examples/next-js/src/actors/registry.ts

claude · 2025-07-31T23:53:30Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

claude · 2025-07-31T23:58:25Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

pkg-pr-new · 2025-08-01T00:00:04Z

More templates

@rivetkit/actor

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/actor@1152

@rivetkit/core

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/core@1152

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/db@1152

rivetkit

pnpm add https://pkg.pr.new/rivet-gg/rivetkit@1152

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/cloudflare-workers@1152

@rivetkit/redis

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/redis@1152

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/framework-base@1152

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/next-js@1152

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-gg/rivetkit/@rivetkit/react@1152

commit: 0f1201a

examples/next-js/src/lib/rivet-client.ts

claude · 2025-08-01T00:03:21Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

examples/next-js/package.json

examples/next-js/next.config.ts

linear · 2025-08-05T17:53:53Z

KIT-178 Add Next.js example to RivetKit

KIT-115 Next.js Support

claude · 2025-08-05T19:20:15Z

Claude finished @jog1t's task —— View job

PR Review: Next.js Integration

Comprehensive review of the Next.js integration PR for code quality, best practices, and potential issues.

Todo List:

Read project guidelines from CLAUDE.md
Review new @rivetkit/next-js package structure and implementation
Analyze the Next.js example application
Check for adherence to project conventions
Evaluate security considerations
Assess performance implications
Verify test coverage and documentation
Provide comprehensive feedback

✅ Overall Assessment

This is a solid implementation that follows most project conventions and provides a clean Next.js integration. The architecture is sound and the implementation is minimal yet functional.

🎯 Code Quality & Best Practices

Strengths:

Clean, minimal implementation with good separation of concerns
Proper TypeScript typing throughout
Follows RivetKit's naming conventions and package structure
Good use of Hono's Vercel adapter for Next.js integration
Client-side code properly marked with "use client" directive

🏗️ Architecture & Design

Package Structure:

✅ Follows monorepo conventions with proper packages/frameworks/next-js location
✅ Package exports are well-defined with separate client/server entrypoints
✅ Proper peer dependencies for React ecosystem
✅ Uses workspace dependencies correctly

Integration Approach:

✅ Smart use of hono/vercel handler for Next.js API routes
✅ Clean abstraction with toNextHandler function
✅ Proper basePath handling for Next.js routing

⚠️ Issues Found

Critical Issues:

Missing Example Scripts (examples/next-js/package.json:8)
- Missing required build and check-types scripts per CLAUDE.md guidelines
- Should include: "build": "next build" and "check-types": "tsc --noEmit"
Incorrect README Format (examples/next-js/README.md)
- Does not follow the required CLAUDE.md template structure
- Missing RivetKit branding, proper links, and project-specific sections
- Should follow the prescribed format with RivetKit links and proper description
Missing turbo.json (examples/next-js/)
- Examples must include the prescribed turbo.json configuration per CLAUDE.md
- Should contain: {"$schema": "https://turbo.build/schema.json", "extends": ["//"]}

Minor Issues:

Client URL Construction (examples/next-js/src/lib/rivet-client.ts:5)
- Already addressed by review comments - using window.location.origin is correct
- Good fix for the original window.location.href issue
Next.js Config File Extension (examples/next-js/next.config.ts)
- TypeScript config files work fine in modern Next.js, despite review comment suggesting otherwise
- This is actually correct and follows Next.js 13+ conventions
Package Structure Suggestion (From review comments)
- Reviewer suggested moving to src/rivet/registry.ts structure - this is already implemented correctly
- Client location in src/lib/ is appropriate for Next.js conventions

🔒 Security Considerations

✅ No hardcoded secrets or sensitive data exposed
✅ Proper use of client-side directives
✅ Auth placeholder in actor definition (good practice)
✅ No obvious security vulnerabilities

⚡ Performance Considerations

✅ Minimal bundle size impact with proper code splitting
✅ Server-sent events transport chosen for real-time updates
✅ React 19 compatibility ensures modern performance features
✅ Efficient actor state management pattern

🧪 Test Coverage

⚠️ No tests included for the new Next.js package
⚠️ No integration tests for the example application
Consider adding basic unit tests for toNextHandler function

📚 Documentation

Package Documentation:

⚠️ Package README is too brief and doesn't follow CLAUDE.md template exactly
Should include more detailed usage examples and API documentation

Example Documentation:

❌ Example README doesn't follow prescribed format
Missing proper RivetKit branding and links

🔧 Additional Recommendations

Add TypeScript strict mode to the Next.js example (already present - good!)
Consider adding error boundaries in the React components for better error handling
Add development vs production environment handling in the client configuration
Consider adding a basic test setup for the package

📝 Required Changes

High Priority:

Fix examples/next-js/package.json to include missing scripts
Update examples/next-js/README.md to follow CLAUDE.md template
Add examples/next-js/turbo.json with required configuration

Medium Priority:

Expand package README with usage examples
Consider adding basic tests for the Next.js integration

✨ Excellent Work

Clean, production-ready integration
Follows project conventions well
Good separation of client/server concerns
Proper TypeScript usage throughout
Minimal API surface that's easy to understand

This PR successfully adds Next.js support to RivetKit with a working example. The implementation is solid and follows most project conventions. The identified issues are primarily related to missing configuration files and documentation formatting rather than code quality problems.

graphite-app · 2025-08-05T19:20:34Z

Merge activity

Aug 5, 7:20 PM UTC: Graphite rebased this pull request, because this pull request is set to merge when ready.
Aug 5, 7:20 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
Aug 5, 7:21 PM UTC: CI is running for this pull request on a draft pull request (#1156) due to your merge queue CI optimization settings.
Aug 5, 7:22 PM UTC: Merged by the Graphite merge queue via draft PR: #1156.

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.

jog1t self-assigned this Jul 31, 2025

jog1t requested a review from NathanFlurry July 31, 2025 23:20

jog1t marked this pull request as ready for review July 31, 2025 23:20

NathanFlurry suggested changes Jul 31, 2025

View reviewed changes

packages/core/src/manager/router.ts Outdated Show resolved Hide resolved

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

examples/next-js/src/actors/registry.ts Show resolved Hide resolved

jog1t force-pushed the 08-01-feat_next-js_add_support_for_next.js branch from 941ce99 to 1e5b6d5 Compare July 31, 2025 23:53

jog1t requested a review from NathanFlurry July 31, 2025 23:54

jog1t force-pushed the 08-01-feat_next-js_add_support_for_next.js branch from 1e5b6d5 to 69ab8ec Compare July 31, 2025 23:58

graphite-app bot reviewed Aug 1, 2025

View reviewed changes

examples/next-js/src/lib/rivet-client.ts Outdated Show resolved Hide resolved

graphite-app bot reviewed Aug 1, 2025

View reviewed changes

examples/next-js/package.json Show resolved Hide resolved

examples/next-js/next.config.ts Show resolved Hide resolved

NathanFlurry approved these changes Aug 5, 2025

View reviewed changes

jog1t added 2 commits August 5, 2025 19:20

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

05ed9dd

Update rivet-client.ts

0f1201a

NathanFlurry force-pushed the 08-01-feat_next-js_add_support_for_next.js branch from 1eb2b3e to 0f1201a Compare August 5, 2025 19:20

graphite-app bot closed this Aug 5, 2025

graphite-app bot deleted the 08-01-feat_next-js_add_support_for_next.js branch August 5, 2025 19:22

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

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

Uh oh!

Conversation

jog1t commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TL;DR

What changed?

How to test?

Why make this change?

Uh oh!

claude bot commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jog1t commented Jul 31, 2025

How to use the Graphite Merge Queue

Uh oh!

Uh oh!

Uh oh!

Uh oh!

claude bot commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude bot commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

claude bot commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

linear bot commented Aug 5, 2025

Uh oh!

claude bot commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: Next.js Integration

Todo List:

✅ Overall Assessment

🎯 Code Quality & Best Practices

🏗️ Architecture & Design

⚠️ Issues Found

Critical Issues:

Minor Issues:

🔒 Security Considerations

⚡ Performance Considerations

🧪 Test Coverage

📚 Documentation

🔧 Additional Recommendations

📝 Required Changes

✨ Excellent Work

Uh oh!

graphite-app bot commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jog1t commented Jul 31, 2025 •

edited

Loading

claude bot commented Jul 31, 2025 •

edited

Loading

claude bot commented Jul 31, 2025 •

edited

Loading

claude bot commented Jul 31, 2025 •

edited

Loading

pkg-pr-new bot commented Aug 1, 2025 •

edited

Loading

claude bot commented Aug 1, 2025 •

edited

Loading

claude bot commented Aug 5, 2025 •

edited

Loading

graphite-app bot commented Aug 5, 2025 •

edited

Loading