workflow example #4032

NathanFlurry · 2026-01-24T23:35:59Z

No description provided.

NathanFlurry · 2026-01-24T23:36:10Z

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(rivetkit): add icon & name customization #4033
workflow example #4032 👈 (View in Graphite)
feat(rivetkit): integrate workflows in to actors #4006
feat(rivetkit): workflows #3734
feat(rivetkit): add actor run handler #4005 : 1 other dependent PR (#4008 )
feat: actor messages & queues #3989 : 1 other dependent PR (#4002 )
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 · 2026-01-24T23:39:04Z

examples/workflow-sandbox/src/actors.ts

+// Workflow Sandbox - Actor Registry
+// Each actor demonstrates a different workflow feature using actor-per-workflow pattern
+
+import { setup } from "rivetkit";


The 'setup' function is imported from 'rivetkit' but the module cannot be found. This is because the root package.json needs to have resolutions for RivetKit packages. Add 'rivetkit': 'workspace:*' to the resolutions in the root package.json.

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

claude · 2026-01-24T23:41:33Z

Pull Request Review: Workflow Example

This PR adds a comprehensive workflow sandbox example and addresses several friction points in the RivetKit workflow API. Overall, this is a valuable contribution that improves developer experience and provides excellent documentation through a working example.

✅ Strengths

1. Excellent Documentation

workflow-friction.md is exceptional - documenting pain points during development is invaluable for improving the API
The example README follows the template correctly with clear feature sections
Good inline comments explaining workflow patterns

2. API Improvements

The PR addresses real friction points:

Added missing send() method to ActorQueue
Added missing broadcast() method to ActorWorkflowContext
Re-exported Loop from rivetkit/workflow to fix package resolution
Updated CLAUDE.md with RivetKit package resolution guidelines

3. Comprehensive Example

The workflow-sandbox example demonstrates:

Sequential steps (order processing)
Sleep/timers (countdown)
Loops with state (batch processing)
Listen with timeout (approval queue)
Join (parallel data fetching)
Race (work vs timeout)
Rollback/compensating transactions (payment)

Each pattern is implemented as a separate actor with clean separation of concerns.

⚠️ Issues & Recommendations

1. Type System Workaround (Critical)

Issue: The actorCtx() helper in _helpers.ts is a workaround for a fundamental type system problem documented in workflow-friction.md.

Location: examples/workflow-sandbox/src/actors/_helpers.ts:10-12

Problem: Every example needs to cast the loop context to access state and broadcast, which defeats type safety.

Recommendation:

Short-term: This workaround is acceptable for the example, but add a TODO comment linking to a tracking issue
Long-term: Fix the root cause by making ActorWorkflowContext the declared type for loop callbacks (as noted in friction log)

2. Type Cast in workflow/mod.ts

Issue: The return type is cast to satisfy RunConfig.

Recommendation: Consider:

Adjusting the RunConfig type to accept the actual return type
Ensuring the workflow run function signature matches what RunConfig expects
Adding a comment explaining why the cast is necessary if it's intentional

3. Error Handling Patterns

Issue: All actor files use try-catch with error serialization, but there's no consistent error handling pattern.

Examples:

order.ts:85-96 - catches and sets state.error
payment.ts:158-170 - same pattern
No validation of error types or structured error objects

Recommendation:

Consider creating a shared error handling utility
Define error types instead of using Error | unknown
Follow the custom error system documented in CLAUDE.md (packages/common/error/)

4. Logging Style Inconsistency

Issue: Pick a consistent naming convention for IDs (orderId vs txId vs id)

5. Documentation Completeness

Issue: The workflow-friction.md document is excellent but lives at the repo root instead of in a docs/ directory.

Recommendation:

Move to docs/development/workflow-friction.md or similar
Add a link from the main README or CONTRIBUTING.md
Consider converting this into tracking issues for each friction point

🔍 Security Considerations

✅ No security concerns identified:

No sensitive data handling
No external API calls
Simulated payment/order processing only

📊 Test Coverage

Missing: No test files in tests/ directory for the workflow-sandbox example.

Recommendation: Add tests following the pattern from examples/CLAUDE.md

📝 Code Quality

Positive:

Consistent formatting
TypeScript strict mode enabled
Good separation of concerns
Clear naming conventions

Areas for Improvement:

Reduce duplication in actor patterns (consider shared utilities)
Add JSDoc comments for exported types

📋 Checklist

✅ Follows repository conventions (CLAUDE.md)
✅ Uses pnpm workspace patterns correctly
✅ ESM imports with .ts extensions
✅ Structured logging with tracing
⚠️ Type safety (workarounds present)
❌ Missing test coverage
⚠️ Friction points documented but not fully resolved

🎬 Conclusion

Recommendation: Approve with minor changes

This PR significantly improves the RivetKit developer experience by:

Adding missing API methods that were clearly needed
Providing a comprehensive workflow example
Documenting friction points for future improvement

The type system workarounds are acceptable for now, given they're well-documented in the friction log. However, these should be addressed in follow-up work.

Required before merge:

None (approval can proceed)

Recommended follow-ups:

Create tracking issues for each friction point in workflow-friction.md
Add test coverage for the workflow-sandbox example
Fix the type system issues so actorCtx helper isn't needed
Review and potentially refactor the 880-line App.tsx component

Great work on documenting the friction points - this kind of developer feedback is invaluable! 🎉

graphite-app · 2026-01-24T23:43:27Z

examples/workflow-sandbox/src/actors.ts

+import { timer } from "./actors/timer.ts";
+import { order } from "./actors/order.ts";
+import { batch } from "./actors/batch.ts";
+import { approval } from "./actors/approval.ts";
+import { dashboard } from "./actors/dashboard.ts";
+import { race } from "./actors/race.ts";
+import { payment } from "./actors/payment.ts";


These imports need to be sorted alphabetically to pass Biome linting. Run 'pnpm biome check --apply' to automatically fix this issue.

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2026-01-24T23:43:29Z

examples/workflow-sandbox/frontend/App.tsx

+	useEffect(() => {
+		actor.connection?.getOrder().then(setOrder);
+	}, [actor.connection]);


This creates an unhandled floating Promise. Add a .catch() handler to properly handle potential errors: actor.connection?.getOrder().then(setOrder).catch(error => console.error('Failed to get order:', error));

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2026-01-24T23:43:30Z

examples/workflow-sandbox/frontend/App.tsx

+	useEffect(() => {
+		actor.connection?.getTask().then(setTask);
+	}, [actor.connection]);


Add error handling to this Promise: actor.connection?.getTask().then(setTask).catch(error => console.error('Failed to get task:', error));

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2026-01-24T23:43:31Z

examples/workflow-sandbox/frontend/App.tsx

+			<button className="approve" onClick={() => onApprove("Admin")}>
+				Approve
+			</button>


If onApprove returns a Promise, handle it properly: onClick={() => { const result = onApprove('Admin'); if (result instanceof Promise) result.catch(err => console.error('Approval failed:', err)); }}

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

queues example

7404ebe

This was referenced Jan 24, 2026

feat(rivetkit): integrate workflows in to actors #4006

Open

feat(rivetkit): workflows #3734

Open

NathanFlurry mentioned this pull request Jan 24, 2026

feat(rivetkit): add icon & name customization #4033

Open

NathanFlurry changed the title ~~queues example~~ workflow example Jan 24, 2026

graphite-app bot reviewed Jan 24, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

workflow example #4032

workflow example #4032

Uh oh!

NathanFlurry commented Jan 24, 2026

Uh oh!

NathanFlurry commented Jan 24, 2026 •

edited

Loading

Uh oh!

graphite-app bot Jan 24, 2026

Uh oh!

claude bot commented Jan 24, 2026

Uh oh!

graphite-app bot Jan 24, 2026

Uh oh!

graphite-app bot Jan 24, 2026

Uh oh!

graphite-app bot Jan 24, 2026

Uh oh!

graphite-app bot Jan 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

workflow example #4032

Are you sure you want to change the base?

workflow example #4032

Uh oh!

Conversation

NathanFlurry commented Jan 24, 2026

Uh oh!

NathanFlurry commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to use the Graphite Merge Queue

Uh oh!

graphite-app bot Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

claude bot commented Jan 24, 2026

Pull Request Review: Workflow Example

✅ Strengths

1. Excellent Documentation

2. API Improvements

3. Comprehensive Example

⚠️ Issues & Recommendations

1. Type System Workaround (Critical)

2. Type Cast in workflow/mod.ts

3. Error Handling Patterns

4. Logging Style Inconsistency

5. Documentation Completeness

🔍 Security Considerations

📊 Test Coverage

📝 Code Quality

Positive:

Areas for Improvement:

📋 Checklist

🎬 Conclusion

Uh oh!

graphite-app bot Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

NathanFlurry commented Jan 24, 2026 •

edited

Loading