feat: new onboarding experience

[jog1t]

No description provided.

[vercel]

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

Project	Deployment	Review	Updated (UTC)
rivet-cloud	Ready	Preview, Comment	Jan 9, 2026 8:12pm
rivet-inspector	Ready	Preview, Comment	Jan 9, 2026 8:12pm
rivet-site	Error		Jan 9, 2026 8:12pm
rivetkit-serverless	Error		Jan 9, 2026 8:12pm

[jog1t]

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

• feat: new onboarding experience #3561 👈 (View in Graphite)
• feat(dashboard): provide ns when querying kv #3831 : 1 other dependent PR (#3803 )
• chore: update sdks #3830
• refactor: performance improvements for inspector #3452
• fix(dashboard): use proper timestamp for actor status #3809
• fix(engine): require namespace for actor id-specific routes #3828
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

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.

[graphite-app]

Graphite Automations

"Test" took an action on this PR • (12/01/25)

1 assignee was added to this PR based on Kacper Wojciechowski's automation.

[pkg-pr-new]

More templates

• actor-actions
• example-ai-agent
• example-ai-and-user-generated-actors-freestyle
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-cloudflare-workers-inline-client
• cross-actor-actions
• example-cursors
• example-cursors-raw-websocket
• custom-serverless
• example-sqlite
• example-elysia
• example-experimental-durable-streams-ai-agent
• hello-world
• example-hono
• hono-react
• example-kitchen-sink
• multi-region
• native-websockets
• next-js
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• scheduling
• state
• example-stream
• example-trpc

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@3561

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@3561

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@3561

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@3561

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@3561

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@3561

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@3561

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@3561

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@3561

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@3561

commit: fa4603d

[claude]

Pull Request Review: New Onboarding Experience

Overview

This is a substantial PR that introduces a new onboarding flow for Rivet Cloud, adding 4,337 lines across 96 files. The changes include new UI components, multi-step forms, provider integrations, and improved user experience.

✅ Positive Aspects

Architecture & Code Organization

• Well-structured stepper pattern: The use of defineStepper with schema validation provides a clean, type-safe approach to multi-step forms
• Component composition: Good separation of concerns with dedicated components
• Reusable form components: The new field.tsx component provides a flexible system
• Provider abstraction: Good abstraction in example-registry for different deployment providers

User Experience

• Real-time feedback: Health check polling with debouncing provides immediate feedback
• Visual polish: Animations, loading states, and clear success/error indicators
• Template system: Nice integration of example templates with preview images

🔍 Issues & Concerns

1. Error Handling & Type Safety

serverless-connection-check.tsx:194: Using any type defeats TypeScript purpose. Use unknown with proper type narrowing.

serverless-connection-check.tsx:86: Missing error handling in effect. If onChange throws, component crashes.

2. Race Conditions & Side Effects

getting-started.tsx:612: Effect fires every time hasActors changes without cleanup flag to prevent multiple navigations. Only logs errors with console.error instead of showing user feedback.

Recommendation: Add ref to track if navigation has occurred.

3. Performance Concerns

getting-started.tsx:584: Polling every 2.5 seconds is resource-intensive. Consider WebSocket/SSE, exponential backoff, or timeout after inactivity.

serverless-connection-check.tsx:65: Object.fromEntries with filter/map creates new objects on every render causing unnecessary re-renders. Should memoize the headers transformation.

4. Code Quality Issues

getting-started.tsx:458: Template literals without validation. If template contains spaces or special characters, command breaks. Need validation or escaping.

field.tsx:182: children in dependency array causes memo to recalculate on every render if children is inline JSX. Defeats purpose of useMemo.

5. Validation & Edge Cases

serverless-connection-check.tsx:20: URL schema silently swallows all parsing errors. Automatically adds https:// which could mask user intent. No validation for trailing slashes or ports. Need more specific error messages.

6. Accessibility

field.tsx:75: Using role="group" without ARIA labels. Screen readers cannot identify what the group represents. Add aria-labelledby or aria-label.

7. Magic Numbers

connect-cloudflare-frame.tsx:30: CLOUDFLARE_MAX_REQUEST_DURATION = 30 needs units documented (seconds).

Different polling intervals (3000ms vs 2500ms) without clear reasoning. Should be consistent or configurable.

8. Memory Leaks

getting-started.tsx:206: No cleanup if component unmounts during async operations. Could cause "state update on unmounted component" warnings. Use AbortController or track mounting state.

📝 Additional Observations

Testing

No test files added despite substantial new functionality. Multi-step form flow and edge cases need comprehensive test coverage.

Dependencies

• Major version bump for @hookform/resolvers (v3 → v5) could introduce breaking changes
• Pre-release package URL for cloud dependency makes reproducible builds difficult

Code Comments

Code lacks comments explaining complex business logic (stepper flow, health check). Per CLAUDE.md, comments should explain "why" not "what".

🎯 Recommendations

High Priority

1. Add proper error handling throughout async operations and effects
2. Fix type safety issues - replace any with unknown or proper types
3. Add test coverage for the new onboarding flow
4. Review polling strategies - consider WebSocket or exponential backoff
5. Fix potential race conditions in navigation effects

Medium Priority

6. Improve accessibility with proper ARIA labels
7. Memoize expensive computations to prevent unnecessary re-renders
8. Add input validation for user-provided URLs and template names
9. Document magic numbers and consider making them configurable

Low Priority

10. Add code comments explaining complex business logic
11. Consolidate polling intervals or document why they differ
12. Consider extracting constants to a configuration file

🔒 Security Considerations

• ✅ Good: URL validation with zod schema
• ⚠️ Review: Headers are user-provided - ensure backend properly validates/sanitizes
• ⚠️ Review: Template names used in shell commands - ensure proper escaping

📊 Summary

This PR delivers significant value by improving the onboarding experience, but has several areas needing attention:

• Critical: Error handling and type safety issues
• Important: Missing test coverage
• Nice-to-have: Performance optimizations and better documentation

The code is generally well-structured and follows React best practices, but needs polish in error handling, edge cases, and type safety to meet production quality standards.

Recommendation: Address high-priority issues before merging. Consider breaking into smaller PRs in future to make review and testing more manageable.

[NathanFlurry]

see linear

[claude]

PR Review: New Onboarding Experience

Overview

This PR introduces a comprehensive new onboarding experience for Rivet with template selection, provider-specific deployment flows, and streamlined backend/frontend setup. The changes span ~4,400 additions and ~1,800 deletions across 91 files, primarily in the frontend.

Code Quality & Best Practices

✅ Strengths

1. Well-structured component hierarchy: The new getting-started.tsx and templates.tsx components follow React best practices with proper separation of concerns.

2. Type safety: Consistent use of Zod schemas for form validation (e.g., configurationSchema, deploymentSchema, endpointSchema).

3. Good UX patterns:

   • Debounced endpoint validation to reduce API calls
   • Real-time health checks with polling
   • Loading states and skeletons throughout

4. Reusable components: New field.tsx component provides a flexible, accessible field system using data attributes and variants.

⚠️ Issues & Concerns

1. Error Handling - Form Validation (Medium Priority)

Location: frontend/src/app/forms/create-organization-form.tsx:14

name: z.string().nonempty("Name cannot be empty or contain whitespaces")

Issue: The error message says "or contain whitespaces" but the validation only checks if the string is empty, not for whitespace characters. This is misleading.

Recommendation:

name: z.string()
  .min(1, "Name is required")
  .refine((val) => val.trim().length > 0, "Name cannot contain only whitespaces")
  .refine((val) => !/\s/.test(val), "Name cannot contain whitespaces")

2. Security - URL Validation (High Priority)

Location: frontend/src/app/serverless-connection-check.tsx:20-38

The endpoint validation uses a regex domain check but has potential issues:

export const endpointSchema = z
  .string()
  .refine((val) => {
    if (!val) return false;
    const urlStr = /^https?:\/\//.test(val) ? val : `https://${val}`;
    try {
      const url = new URL(urlStr);
      if (!/^https?:$/.test(url.protocol)) return false;
      return z4.regexes.domain.test(url.hostname);
    } catch {
      return false;
    }
  }, "Invalid URL")

Issues:

• Silently catches all URL parsing errors, which could mask validation issues
• Auto-adding https:// on paste (line 456) could be confusing if users paste malformed URLs
• No validation of URL path, query params, or fragments which could contain injection attempts

Recommendations:

• Add more specific error messages for different validation failures
• Consider validating that the URL does not contain potentially dangerous characters
• Log validation failures for debugging (at least in dev mode)

3. Type Safety Issue (Low Priority)

Location: frontend/src/app/serverless-connection-check.tsx:193-196

function isRivetHealthCheckFailureResponse(
  error: any,
): error is Rivet.RunnerConfigsServerlessHealthCheckResponseFailure["failure"] {
  return error && "error" in error;
}

Issue: Using any type and weak type guard. The guard only checks for existence of error property but does not verify its structure.

Recommendation: Use unknown instead of any and add more robust checks.

4. Code Duplication (Medium Priority)

Location: frontend/src/app/getting-started.tsx:449-578

The TemplateSetup component contains significant duplication across package managers (npx, yarn, pnpm, bun, deno, git). Each creates nearly identical CodeFrame components.

Recommendation: Extract to a helper function or component to reduce duplication.

5. Performance - Unnecessary Re-renders (Low Priority)

Location: frontend/src/app/forms/connect-manual-serverless-form.tsx:296-414

The Headers component uses both watch and manual setValue calls which could cause extra re-renders:

value={watch(`headers.${index}.0`)}
onChange={(e) => {
  setValue(`headers.${index}.0`, e.target.value, {
    shouldDirty: true,
    shouldTouch: true,
    shouldValidate: true,
  });
}}

Recommendation: Use the field's onChange directly from react-hook-form instead of manual setValue calls.

6. Incomplete Error Handling (Medium Priority)

Location: frontend/src/app/getting-started.tsx:625-628

if (hasActors) {
  success().catch((error) => {
    console.error(error);
  });
}

Issue: Error is only logged to console. User will not see if navigation/invalidation fails.

Recommendation: Add user-facing error handling (toast notification, error boundary, etc.).

7. CSS Class Issue (Low Priority)

Location: frontend/src/app/forms/connect-manual-serverless-form.tsx:326-327

<div
  key={field.id}
  className="grid grid-cols-subgrid grid-rows-col-span-full flex-1"
>

Issue: CSS class name appears broken: grid-rows-col-span-full (likely should be grid-rows-subgrid based on context).

8. Dependency Update (Info)

Location: frontend/package.json:38

"@hookform/resolvers": "^5.2",

Major version bump from ^3.10.0 to ^5.2. Ensure this is tested thoroughly as major version changes can introduce breaking changes.

Performance Considerations

1. Polling intervals: The health check polling (3s default, 5s for configs/runners) is reasonable but could be optimized:

   • Consider exponential backoff for failed checks
   • Stop polling when tab is not visible using Page Visibility API

2. Query invalidation: Multiple places invalidate entire query caches. Consider more granular invalidation.

3. Image loading: Template preview images in templates.tsx do not use lazy loading. Consider adding loading="lazy" to images.

Security Concerns

1. URL handling: As mentioned above, the endpoint validation could be more robust.

2. Header injection: The custom headers feature in connect-manual-serverless-form.tsx should validate header names against dangerous headers (e.g., Host, Content-Length, etc.).

3. XSS in error messages: Error messages from the API are rendered directly. Ensure API responses are sanitized or use textContent instead of HTML rendering.

Test Coverage

Observation: No test files were added or modified in this PR. Given the scope of changes, consider adding:

1. Unit tests for form validation schemas
2. Integration tests for the onboarding flow
3. E2E tests for the complete user journey
4. Tests for URL validation edge cases

Minor Issues

1. Commented code: Commented out Railway code in getting-started.tsx:377-379 should either be removed or have a tracking issue.

Recommendations Summary

High Priority

• Improve URL validation and error handling in endpointSchema
• Add validation for custom header names to prevent header injection

Medium Priority

• Fix organization name validation message/logic mismatch
• Add user-facing error handling for async operations
• Reduce code duplication in template setup
• Test @hookform/resolvers v5 upgrade thoroughly

Low Priority

• Fix CSS class name in headers grid
• Improve type safety (replace any with unknown)
• Optimize polling with exponential backoff and visibility API
• Add lazy loading for template images
• Add test coverage

Nice to Have

• Extract reusable components from duplicated code
• Add JSDoc comments for complex validation logic
• Consider adding error boundaries around major sections

Conclusion

This is a substantial improvement to the onboarding experience with well-structured code. The main concerns are around input validation, error handling, and test coverage. Once the high-priority security items are addressed, this will be a solid addition to the codebase.

Overall Assessment: ✅ Approve with recommendations

fixed

[graphite-app]

Merge activity

• Jan 17, 12:58 AM UTC: jog1t added this pull request to the Graphite merge queue.
• Jan 17, 12:59 AM UTC: CI is running for this pull request on a draft pull request (#3953) due to your merge queue CI optimization settings.
• Jan 17, 12:59 AM UTC: CI is running for this pull request on a draft pull request (#3954) due to your merge queue CI optimization settings.
• Jan 17, 1:00 AM UTC: Merged by the Graphite merge queue via draft PR: #3954.