chore(nextjs): migrate to using spawned engine

[NathanFlurry]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
rivetkit-serverless	Ready	Preview	Comment	Oct 5, 2025 9:53pm

[claude]

Claude finished @NathanFlurry's task —— View job

---

Code Review for PR #1357: chore(nextjs): migrate to using spawned engine

Reviewing the migration from embedded to spawned engine architecture...

Todo List

• Read project guidelines from CLAUDE.md
• Analyze deleted files to understand what functionality was removed
• Review modified files for code quality and best practices
• Check for potential bugs and security issues
• Evaluate performance implications of the migration
• Assess test coverage impact
• Provide comprehensive feedback

Analysis Summary

This PR migrates the Next.js integration from an embedded engine approach to a spawned engine architecture. The key changes involve:

Removed Components:

• rivet-server.ts - Previously handled global registry caching for development
• counter.ts - Example counter implementation using global state
• api/counter/route.ts - Direct API route for counter functionality

Modified Components:

• packages/next-js/src/mod.ts - Core integration logic
• examples/next-js/src/app/api/rivet/[...all]/route.ts - Simplified to direct registry usage
• examples/next-js/src/lib/rivet-client.ts - Simplified client configuration

Code Quality & Best Practices ✅

Positives:

• Clean simplification of the architecture
• Proper removal of global state caching patterns that are no longer needed
• Adheres to project conventions from CLAUDE.md (camelCase, proper imports)
• Good separation of concerns with serverless auto-configuration

Minor Issues:

• Missing JSDoc comments for the public toNextHandler API (CLAUDE.md guideline)
• The TODO comment in rivet-client.ts:5 should be addressed or have a tracking issue

Potential Bugs & Issues ⚠️

1. URL Construction Logic (packages/next-js/src/mod.ts:11-14):

   const publicUrl =
     process.env.NEXT_PUBLIC_SITE_URL ??
     process.env.NEXT_PUBLIC_VERCEL_URL ??
     `http://127.0.0.1:${process.env.PORT ?? 8080}`;

   • Missing https:// prefix for NEXT_PUBLIC_VERCEL_URL environment variable
   • Vercel URLs should use HTTPS in production

2. Client Configuration Simplification (examples/next-js/src/lib/rivet-client.ts):

   • The previous version had explicit endpoint and transport configuration
   • Current version relies on defaults - ensure this works across all deployment environments

3. Missing Error Handling:

   • No error handling in fetchWrapper function for URL construction or fetch operations
   • Should follow CLAUDE.md guidelines to use ActorError base classes

Performance Considerations 🚀

Improvements:

• Spawned Engine: Better resource isolation and scaling capabilities
• Serverless Auto-Configuration: Automatic setup reduces cold start overhead
• Simplified Client: Reduced bundle size by removing custom endpoint logic

Potential Concerns:

• Cold Start Impact: Spawned engine may have different cold start characteristics
• Memory Usage: Need to verify memory efficiency compared to embedded approach

Security Considerations 🔒

Good Practices:

• Proper environment variable usage for URL configuration
• No sensitive data exposure in client code

Recommendations:

• Add input validation for environment variables
• Consider adding rate limiting configuration for the serverless setup

Test Coverage Impact 📋

Missing Tests:

• No existing test files found for the Next.js example
• Migration changes core functionality without test coverage
• Recommendation: Add integration tests to verify:
  • Counter actor functionality still works
  • Client-server communication
  • Environment variable handling
  • Error scenarios

Architecture Assessment 🏗️

Migration Benefits:

• Better Scalability: Spawned engine allows independent scaling
• Cleaner Separation: Removes development-specific global caching
• Serverless-First: Auto-configuration optimizes for serverless deployments

Breaking Changes:

• Developers can no longer use the direct /api/counter endpoint pattern
• Must use actor-based approach through /api/rivet/... routes

Recommendations

1. Fix URL Construction:

   const publicUrl =
     process.env.NEXT_PUBLIC_SITE_URL ??
     (process.env.NEXT_PUBLIC_VERCEL_URL ? `https://${process.env.NEXT_PUBLIC_VERCEL_URL}` : null) ??
     `http://127.0.0.1:${process.env.PORT ?? 8080}`;

2. Add JSDoc Documentation:

   /**
    * Creates Next.js route handlers for RivetKit registry with spawned engine support.
    * Automatically configures serverless mode and URL routing.
    */
   export const toNextHandler = (/* ... */) => {

3. Add Error Handling:

   const fetchWrapper = async (request: Request, { params }: { params: Promise<{ all: string[] }> }) => {
     try {
       const { all } = await params;
       // ... existing logic
     } catch (error) {
       throw new InternalError("Failed to process request", { cause: error });
     }
   };

4. Add Integration Tests: Create test coverage for the new spawned engine approach

5. Address TODO: Resolve the auto-trigger comment or create a tracking issue

Overall Assessment ✨

This is a well-executed architectural migration that simplifies the codebase while improving scalability. The changes align with modern serverless patterns and remove complexity from the development experience. The main concerns are around missing error handling, test coverage, and the URL construction bug.

Recommendation: Approve with minor fixes - particularly the HTTPS URL prefix issue.

---

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• chore(nextjs): migrate to using spawned engine #1357 👈 (View in Graphite)
• chore(core): add support for auto-configuring serverless #1356 : 1 other dependent PR (#1352 )
• chore(core): add build:fast script #1355
• feat(core): support running engine #1353
• fix(example-deno): fix check-types #1351
• chore(core): simplify config #1350
• 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.